teleport-tsh-ssh

使用此技能，可通过 tsh 命令配合显式指定的身份文件（-i）及持久化代理配置，访问 Teleport SSH 节点。

建议搭配 teleport-tbot-bootstrap 使用，以完成本地 Machine ID 身份源的初始化与持久化存储。

兼容性

已在 Teleport/tsh/tbot 18.7.0 版本上完成测试。

身份策略（必需）

所有 tsh 命令均须显式传入 -i 参数。

默认身份文件路径：

• ~/.openclaw/workspace/tbot/identity

若默认路径不存在，则在工作区中自动发现候选身份文件，并选取最匹配的一项。

身份文件发现回退机制

当默认身份文件缺失时，在工作区中按以下命名模式搜索候选文件：

• identity
• *.identity
• tbot/identity

使用前需校验候选文件格式。有效的 Teleport Machine ID 身份文件通常包含多个区块，例如：

• -----BEGIN PRIVATE KEY-----
• 一条 OpenSSH 用户证书行（*-cert-v01@openssh.com ...）
• 一个或多个 -----BEGIN CERTIFICATE----- 区块

优先选择最可能为当前有效文件的候选项：路径位于 tbot/ 子目录下的优先；若存在多个，取最后修改时间（mtime）最新的。

安全说明

• 切勿将身份文件、tbot 状态目录、令牌或注册密钥提交至版本控制系统。
• 自动化身份应优先采用显式路径与最小权限角色映射。

已知限制（v1.0.0）

• 聚焦于 Teleport SSH 节点访问场景（tsh ssh、tsh ls、tsh scp）。
• 暂不支持 Teleport App / DB / Kubernetes 等访问流程。

代理解析（必需）

按以下顺序解析代理地址：

1. 若环境变量 TELEPORT_PROXY 已设置，则直接使用其值。
2. 否则，尝试读取 ~/.openclaw/workspace/tbot/proxy 文件（单行纯文本）中保存的代理地址（如存在）。
3. 否则，提示用户输入 Teleport 代理地址，并将其保存至 ~/.openclaw/workspace/tbot/proxy 供后续调用复用。

一旦成功解析代理地址，所有命令中均须显式包含该代理参数：

• tsh -i --proxy= ...

快速操作流程

1. 确认 tsh 已正确安装。
2. 解析身份文件路径（优先尝试默认路径，再启用回退发现机制）。
3. 若未找到有效身份文件，提示用户提供身份文件路径。
4. 解析代理地址（依次检查 TELEPORT_PROXY、已保存的 proxy 文件、最终交互式提示并保存）。
5. 必要时检查认证状态：tsh -i --proxy= status。
6. 如需获取节点列表，执行：tsh -i --proxy= ls。
7. 使用显式身份连接或执行命令：
   • tsh -i --proxy= ssh
   • tsh -i --proxy= ssh -- [args...]
8. 返回简洁结果，并附带可操作的错误详情。

常用命令模式

• 交互式 Shell：
  • tsh -i --proxy= ssh
• 远程命令执行：
  • tsh -i --proxy= ssh -- [args...]
• 指定远程登录用户：
  • tsh -i --proxy= ssh @
  • 或 tsh -i --proxy= ssh --login=
• 列出可用节点：
  • tsh -i --proxy= ls

若用户询问当前有哪些可用节点，请运行 tsh ls（携带身份与代理参数），并将结果返回。

当用户明确请求命令输出时，优先采用非交互式形式执行。

使用 Teleport SCP 进行文件传输

使用 tsh scp 配合身份文件与代理地址实现文件传输，语法与 OpenSSH scp 保持一致。

• 本地 → 远程：
  • tsh -i --proxy= scp :
• 远程 → 本地：
  • tsh -i --proxy= scp :

故障排查清单

• tsh: command not found → 安装 Teleport 客户端。
• 身份文件缺失或不可读 → 启用回退发现机制；若仍无匹配项，则提示用户提供路径。
• 代理地址缺失 → 提示用户输入代理地址，保存至 ~/.openclaw/workspace/tbot/proxy 后重试。
• not logged in / 证书已过期 → 刷新 Machine ID 输出（检查 tbot 服务健康状态）。
• access denied → 角色或登录用户不匹配；请核对目标主机与身份来源。
• host not found → 使用 tsh -i --proxy= ls 核实节点列表，并确认集群上下文与代理配置是否正确。

Clawhub 上架文案

Clawhub 简短描述

使用 tsh 命令配合显式 Machine ID 身份（-i），支持 Teleport SSH 访问、远程命令执行、节点列表查询及 tsh scp 文件传输。

配套技能

配合 teleport-tbot-bootstrap 使用，用于创建并持久化本地 Machine ID 身份源。

Clawhub 详细描述

通过“身份优先”的标准化命令模式统一 Teleport 服务器访问方式。强制要求显式指定身份、确保代理解析的一致性，同时支持节点发现、命令执行与文件传输，并提供实用的故障排查指引。

参考资料

• references/tsh-ssh-reference.md
• https://goteleport.com/docs/reference/cli/tsh/#tsh-ssh