# 通过代理访问 SSH
SUMMARY: LLM 智能体如何通过 SSH 代理 API（而不是裸 SSH 密钥）安全地在远程机器上执行命令。

KEY CONTEXT:
作为 LLM 绝不持有裸的 SSH 私钥。使用 SSH 代理 HTTP API：
1) POST /connect?target=<name> → session_id（持久，可存活数小时）。
2) POST /<session_id>/exec {command, timeout} → exec_id。
3) GET /<session_id>/exec/<exec_id> → 完成后取回输出。
4) 文件上传/下载使用 SFTP 端点，而不是 cat/heredoc。
目标是预先注册的名称（如 "vps1"），不是 IP——代理是凭据唯一的居所。

通过代理访问 SSH
智能体需要在远程机器上执行命令——部署容器、读日志、修配置。把裸的 SSH 私钥交给 LLM 是个坏主意：密钥会落进上下文窗口、日志和转录文本。SSH 代理解决了这个问题：凭据由它掌管，智能体只说 HTTP。
模型
[CODE BLOCK]
代理通过简单的 REST 面提供持久会话：
| 端点 | 用途 |
|---|---|
|  | 打开会话 →  |
|   | 执行命令（异步）→  |
|  | 轮询输出 |
| SFTP 端点 | 文件上传/下载，，， |
认证是 Bearer 令牌——和你用的其他 API 相同的模式。
执行模式
[CODE BLOCK]
行为准则
1. 复用会话。 每条命令都连接一次会浪费资源并触发速率限制。保存 （如 ），复用前先心跳确认。
2. 给目标命名，而不是去发现它们。 目标是预先注册的（、……）。代理是唯一的事实来源——永远不要把 IP 地址硬编码进智能体代码。
3. 文件优先用 SFTP，而不是 shell 的 cat/heredoc。 通过  转义二进制数据会损坏载荷。使用专用的上传/下载端点。
4. 给你的命令加引号。 JSON 体会被解析两次（HTTP + shell）。远程命令用单引号包裹，并保持单行。
5. 假设审计存在。 每次执行都会落入代理的审计日志——像人类在读一切那样行事（他确实可以）。
什么时候不要用 exec
- 读取拥有 API 的结构化状态（Docker、数据库、Synapse 的 Mind API）——永远优先用 API，而不是解析 CLI 输出。
- 长时间运行的交互式进程。 是带超时的即发即忘；改用目标机上的  + 状态文件。
- 没有明确指令的任何破坏性操作。代理给你能力——人类给你许可。
错误恢复
| 症状 | 处理 |
|---|---|
| 连接时 401 | 令牌过期——从 memory/settings 重新读取，绝不从转录文本 |
| 会话 404 | 会话过期（24 小时上限）——重新连接 |
| exec 超时 | 提高  或拆分命令；检查目标机负载 |
| 文件内容损坏 | 你用了  而不是 SFTP——改用 SFTP 端点 |