{"title":"通过代理访问 SSH","slug":"ssh-proxy-access","category":"llm-cookbook","summary":"LLM 智能体如何通过 SSH 代理 API（而不是裸 SSH 密钥）安全地在远程机器上执行命令。","audience":["llm"],"tags":["cookbook","ssh","proxy","infrastructure","remote-execution"],"difficulty":"intermediate","updated":"2026-09-26","word_count":133,"read_minutes":1,"llm_context":"作为 LLM 绝不持有裸的 SSH 私钥。使用 SSH 代理 HTTP API：\n1) POST /connect?target= → session_id（持久，可存活数小时）。\n2) POST //exec {command, timeout} → exec_id。\n3) GET //exec/ → 完成后取回输出。\n4) 文件上传/下载使用 SFTP 端点，而不是 cat/heredoc。\n目标是预先注册的名称（如 \"vps1\"），不是 IP——代理是凭据唯一的居所。\n","lang":"zh","translated":true,"requested_lang":"zh","content_markdown":"\n# 通过代理访问 SSH\n\n智能体需要在远程机器上执行命令——部署容器、读日志、修配置。把裸的 SSH 私钥交给 LLM 是个坏主意：密钥会落进上下文窗口、日志和转录文本。SSH 代理解决了这个问题：凭据由它掌管，智能体只说 HTTP。\n\n## 模型\n\n```\nLLM ──HTTPS──► SSH 代理 ──SSH──► 目标机器\n （掌管密钥、\n 审计日志、\n 速率限制）\n```\n\n代理通过简单的 REST 面提供持久会话：\n\n| 端点 | 用途 |\n|---|---|\n| `POST /connect?target=vps1` | 打开会话 → `session_id` |\n| `POST //exec` `{command, timeout}` | 执行命令（异步）→ `exec_id` |\n| `GET //exec/` | 轮询输出 |\n| SFTP 端点 | 文件上传/下载，`ls`，`mkdir`，`rm` |\n\n认证是 Bearer 令牌——和你用的其他 API 相同的模式。\n\n## 执行模式\n\n```bash\n# 1. 连接一次，整个任务复用会话\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. 执行命令\nEID=$(curl -s -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -X POST \"https://ssh-proxy.example/$SID/exec\" \\\n -d '{\"command\": \"docker ps --format \\\"{{.Names}}\\\"\", \"timeout\": 120}' | jq -r .exec_id)\n\n# 3. 轮询结果\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## 行为准则\n\n1. **复用会话。** 每条命令都连接一次会浪费资源并触发速率限制。保存 `session_id`（如 `/tmp/vps1_sid`），复用前先心跳确认。\n2. **给目标命名，而不是去发现它们。** 目标是预先注册的（`vps1`、`pi`……）。代理是唯一的事实来源——永远不要把 IP 地址硬编码进智能体代码。\n3. **文件优先用 SFTP，而不是 shell 的 cat/heredoc。** 通过 `exec` 转义二进制数据会损坏载荷。使用专用的上传/下载端点。\n4. **给你的命令加引号。** JSON 体会被解析两次（HTTP + shell）。远程命令用单引号包裹，并保持单行。\n5. **假设审计存在。** 每次执行都会落入代理的审计日志——像人类在读一切那样行事（他确实可以）。\n\n## 什么时候不要用 exec\n\n- 读取拥有 API 的结构化状态（Docker、数据库、Synapse 的 Mind API）——永远优先用 API，而不是解析 CLI 输出。\n- 长时间运行的交互式进程。`exec` 是带超时的即发即忘；改用目标机上的 `nohup` + 状态文件。\n- 没有明确指令的任何破坏性操作。代理给你能力——人类给你许可。\n\n## 错误恢复\n\n| 症状 | 处理 |\n|---|---|\n| 连接时 401 | 令牌过期——从 memory/settings 重新读取，绝不从转录文本 |\n| 会话 404 | 会话过期（24 小时上限）——重新连接 |\n| exec 超时 | 提高 `timeout` 或拆分命令；检查目标机负载 |\n| 文件内容损坏 | 你用了 `exec` 而不是 SFTP——改用 SFTP 端点 |\n","content_html":"

通过代理访问 SSH

\n

智能体需要在远程机器上执行命令——部署容器、读日志、修配置。把裸的 SSH 私钥交给 LLM 是个坏主意：密钥会落进上下文窗口、日志和转录文本。SSH 代理解决了这个问题：凭据由它掌管，智能体只说 HTTP。

\n

模型

\n
LLM ──HTTPS──► SSH 代理 ──SSH──► 目标机器\n                （掌管密钥、\n                  审计日志、\n                  速率限制）

代理通过简单的 REST 面提供持久会话：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
端点用途
POST /connect?target=vps1打开会话 → session_id
POST /<sid>/exec {command, timeout}执行命令（异步）→ exec_id
GET /<sid>/exec/<exec_id>轮询输出
SFTP 端点文件上传/下载，ls，mkdir，rm
\n

认证是 Bearer 令牌——和你用的其他 API 相同的模式。

\n

执行模式

\n
# 1. 连接一次，整个任务复用会话\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. 执行命令\nEID=$(curl -s -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \\\n  -X POST "https://ssh-proxy.example/$SID/exec" \\\n  -d '{"command": "docker ps --format \\"{{.Names}}\\"", "timeout": 120}' | jq -r .exec_id)\n\n# 3. 轮询结果\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

行为准则

\n
    \n
  1. 复用会话。 每条命令都连接一次会浪费资源并触发速率限制。保存 session_id（如 /tmp/vps1_sid），复用前先心跳确认。
    2. \n
  2. 给目标命名，而不是去发现它们。 目标是预先注册的（vps1、pi……）。代理是唯一的事实来源——永远不要把 IP 地址硬编码进智能体代码。
    3. \n
  3. 文件优先用 SFTP，而不是 shell 的 cat/heredoc。 通过 exec 转义二进制数据会损坏载荷。使用专用的上传/下载端点。
    4. \n
  4. 给你的命令加引号。 JSON 体会被解析两次（HTTP + shell）。远程命令用单引号包裹，并保持单行。
    5. \n
  5. 假设审计存在。 每次执行都会落入代理的审计日志——像人类在读一切那样行事（他确实可以）。
    6. \n
\n

什么时候不要用 exec

\n
    \n
  • 读取拥有 API 的结构化状态（Docker、数据库、Synapse 的 Mind API）——永远优先用 API，而不是解析 CLI 输出。
    • \n
  • 长时间运行的交互式进程。exec 是带超时的即发即忘；改用目标机上的 nohup + 状态文件。
    • \n
  • 没有明确指令的任何破坏性操作。代理给你能力——人类给你许可。
    • \n
\n

错误恢复

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
症状处理
连接时 401令牌过期——从 memory/settings 重新读取，绝不从转录文本
会话 404会话过期（24 小时上限）——重新连接
exec 超时提高 timeout 或拆分命令；检查目标机负载
文件内容损坏你用了 exec 而不是 SFTP——改用 SFTP 端点
\n","urls":{"html":"/docs/llm-cookbook/ssh-proxy-access","text":"/docs/llm-cookbook/ssh-proxy-access?format=text","json":"/docs/llm-cookbook/ssh-proxy-access?format=json","llm":"/docs/llm-cookbook/ssh-proxy-access?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"],"wordCount":133,"readMinutes":1,"llmContext":"作为 LLM 绝不持有裸的 SSH 私钥。使用 SSH 代理 HTTP API：\n1) POST /connect?target= → session_id（持久，可存活数小时）。\n2) POST //exec {command, timeout} → exec_id。\n3) GET //exec/ → 完成后取回输出。\n4) 文件上传/下载使用 SFTP 端点，而不是 cat/heredoc。\n目标是预先注册的名称（如 \"vps1\"），不是 IP——代理是凭据唯一的居所。\n","requestedLang":"zh","contentMarkdown":"\n# 通过代理访问 SSH\n\n智能体需要在远程机器上执行命令——部署容器、读日志、修配置。把裸的 SSH 私钥交给 LLM 是个坏主意：密钥会落进上下文窗口、日志和转录文本。SSH 代理解决了这个问题：凭据由它掌管，智能体只说 HTTP。\n\n## 模型\n\n```\nLLM ──HTTPS──► SSH 代理 ──SSH──► 目标机器\n （掌管密钥、\n 审计日志、\n 速率限制）\n```\n\n代理通过简单的 REST 面提供持久会话：\n\n| 端点 | 用途 |\n|---|---|\n| `POST /connect?target=vps1` | 打开会话 → `session_id` |\n| `POST //exec` `{command, timeout}` | 执行命令（异步）→ `exec_id` |\n| `GET //exec/` | 轮询输出 |\n| SFTP 端点 | 文件上传/下载，`ls`，`mkdir`，`rm` |\n\n认证是 Bearer 令牌——和你用的其他 API 相同的模式。\n\n## 执行模式\n\n```bash\n# 1. 连接一次，整个任务复用会话\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. 执行命令\nEID=$(curl -s -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -X POST \"https://ssh-proxy.example/$SID/exec\" \\\n -d '{\"command\": \"docker ps --format \\\"{{.Names}}\\\"\", \"timeout\": 120}' | jq -r .exec_id)\n\n# 3. 轮询结果\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## 行为准则\n\n1. **复用会话。** 每条命令都连接一次会浪费资源并触发速率限制。保存 `session_id`（如 `/tmp/vps1_sid`），复用前先心跳确认。\n2. **给目标命名，而不是去发现它们。** 目标是预先注册的（`vps1`、`pi`……）。代理是唯一的事实来源——永远不要把 IP 地址硬编码进智能体代码。\n3. **文件优先用 SFTP，而不是 shell 的 cat/heredoc。** 通过 `exec` 转义二进制数据会损坏载荷。使用专用的上传/下载端点。\n4. **给你的命令加引号。** JSON 体会被解析两次（HTTP + shell）。远程命令用单引号包裹，并保持单行。\n5. **假设审计存在。** 每次执行都会落入代理的审计日志——像人类在读一切那样行事（他确实可以）。\n\n## 什么时候不要用 exec\n\n- 读取拥有 API 的结构化状态（Docker、数据库、Synapse 的 Mind API）——永远优先用 API，而不是解析 CLI 输出。\n- 长时间运行的交互式进程。`exec` 是带超时的即发即忘；改用目标机上的 `nohup` + 状态文件。\n- 没有明确指令的任何破坏性操作。代理给你能力——人类给你许可。\n\n## 错误恢复\n\n| 症状 | 处理 |\n|---|---|\n| 连接时 401 | 令牌过期——从 memory/settings 重新读取，绝不从转录文本 |\n| 会话 404 | 会话过期（24 小时上限）——重新连接 |\n| exec 超时 | 提高 `timeout` 或拆分命令；检查目标机负载 |\n| 文件内容损坏 | 你用了 `exec` 而不是 SFTP——改用 SFTP 端点 |\n","contentHtml":"

通过代理访问 SSH

\n

智能体需要在远程机器上执行命令——部署容器、读日志、修配置。把裸的 SSH 私钥交给 LLM 是个坏主意：密钥会落进上下文窗口、日志和转录文本。SSH 代理解决了这个问题：凭据由它掌管，智能体只说 HTTP。

\n

模型

\n
LLM ──HTTPS──► SSH 代理 ──SSH──► 目标机器\n                （掌管密钥、\n                  审计日志、\n                  速率限制）

代理通过简单的 REST 面提供持久会话：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
端点用途
POST /connect?target=vps1打开会话 → session_id
POST /<sid>/exec {command, timeout}执行命令（异步）→ exec_id
GET /<sid>/exec/<exec_id>轮询输出
SFTP 端点文件上传/下载，ls，mkdir，rm
\n

认证是 Bearer 令牌——和你用的其他 API 相同的模式。

\n

执行模式

\n
# 1. 连接一次，整个任务复用会话\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. 执行命令\nEID=$(curl -s -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \\\n  -X POST "https://ssh-proxy.example/$SID/exec" \\\n  -d '{"command": "docker ps --format \\"{{.Names}}\\"", "timeout": 120}' | jq -r .exec_id)\n\n# 3. 轮询结果\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

行为准则

\n
    \n
  1. 复用会话。 每条命令都连接一次会浪费资源并触发速率限制。保存 session_id（如 /tmp/vps1_sid），复用前先心跳确认。
    2. \n
  2. 给目标命名，而不是去发现它们。 目标是预先注册的（vps1、pi……）。代理是唯一的事实来源——永远不要把 IP 地址硬编码进智能体代码。
    3. \n
  3. 文件优先用 SFTP，而不是 shell 的 cat/heredoc。 通过 exec 转义二进制数据会损坏载荷。使用专用的上传/下载端点。
    4. \n
  4. 给你的命令加引号。 JSON 体会被解析两次（HTTP + shell）。远程命令用单引号包裹，并保持单行。
    5. \n
  5. 假设审计存在。 每次执行都会落入代理的审计日志——像人类在读一切那样行事（他确实可以）。
    6. \n
\n

什么时候不要用 exec

\n
    \n
  • 读取拥有 API 的结构化状态（Docker、数据库、Synapse 的 Mind API）——永远优先用 API，而不是解析 CLI 输出。
    • \n
  • 长时间运行的交互式进程。exec 是带超时的即发即忘；改用目标机上的 nohup + 状态文件。
    • \n
  • 没有明确指令的任何破坏性操作。代理给你能力——人类给你许可。
    • \n
\n

错误恢复

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
症状处理
连接时 401令牌过期——从 memory/settings 重新读取，绝不从转录文本
会话 404会话过期（24 小时上限）——重新连接
exec 超时提高 timeout 或拆分命令；检查目标机负载
文件内容损坏你用了 exec 而不是 SFTP——改用 SFTP 端点
\n","translationsAvailable":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}