{"title":"Computer Control API","slug":"computers","category":"api","summary":"远程控制已注册的计算机 — 排队命令、截屏、在远程机器上运行脚本。","audience":["human","llm"],"tags":["api","computers","remote-control","automation"],"difficulty":"advanced","updated":"2026-06-27","word_count":177,"read_minutes":1,"llm_context":"Two sides: user-facing (Mind Key/JWT) and agent-facing (Computer Token)\nRegister agent: POST /computers/register { install_code } → returns computer_token\nList: GET /computers/list (Mind Key or JWT)\nQueue command: POST /computers/:id/commands { type, payload }\nCommand types: screenshot, click, move, type, key, scroll, drag\nAgent poll: GET /computers/me/poll?wait=5 (Computer Token)\nAgent result: POST /computers/me/commands/:cid/result (Computer Token)\nOne-shot screenshot: GET /computers/:id/screenshot (waits 30s for result)\nPattern: register agent on remote machine → user queues commands → agent polls and executes\n","lang":"zh","translated":true,"requested_lang":"zh","content_markdown":"\n# Computer Control API\n\nComputer Control API 让你能够远程控制已注册的计算机。目标机器上会运行一个小型 Agent（`screen-remote-agent`），轮询命令、执行命令并回传结果。这使 LLM 驱动的 GUI 自动化成为可能。\n\n## 架构\n\n```\n┌─────────────┐ 排队命令 ┌──────────┐ 轮询 ┌─────────────────┐\n│ LLM Agent │ ───────────▶ │ Synapse │ ◀───── │ screen-remote │\n│ (用户侧) │ │ Server │ ──────▶│ (在目标 PC 上) │\n└─────────────┘ └──────────┘ 结果 └─────────────────┘\n ▲\n │\n ┌─────────────┐\n │ Human UI │\n │ (浏览器) │\n └─────────────┘\n```\n\n## 用户侧端点（Mind Key 或 JWT）\n\n### GET /computers/list\n\n列出所有已注册的计算机。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/computers/list\n```\n\n### GET /computers/:id\n\n获取单台计算机的详情。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/computers/comp_001\n```\n\n### POST /computers/install-code\n\n为注册新计算机生成一个安装码。\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/computers/install-code \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"computer_name\": \"office-mac\"}'\n```\n\n响应：`{ \"install_code\": \"ic_xyz789\", \"expires_at\": \"...\" }`\n\n### POST /computers/:id/commands\n\n为远程 Agent 排队一条待执行的命令。\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/computers/comp_001/commands \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"type\": \"screenshot\",\n \"payload\": {}\n }'\n```\n\n响应：`{ \"command_id\": \"cmd_001\", \"status\": \"queued\" }`\n\n### GET /computers/:id/command（通过查询参数）\n\n通过 GET 方式排队命令（用于简单场景）。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/computers/comp_001/command?type=screenshot\"\n```\n\n### GET /computers/:id/commands\n\n列出某台计算机最近的命令。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/computers/comp_001/commands?limit=50\"\n```\n\n### GET /computers/:id/commands/:cid\n\n获取某条具体命令的状态与结果。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/computers/comp_001/commands/cmd_001\n```\n\n### GET /computers/:id/screenshot\n\n一次性操作：排队截图命令并等待最多 30 秒拿结果。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/computers/comp_001/screenshot > screenshot.png\n```\n\n### POST /computers/:id/disable\n\n禁用某台计算机（吊销其令牌，保留记录以备审计）。\n\n```bash\ncurl -X POST -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/computers/comp_001/disable\n```\n\n### DELETE /computers/:id\n\n永久删除某台计算机。\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/computers/comp_001\n```\n\n## Agent 侧端点（Computer Token）\n\n以下端点由运行在目标机器上的 `screen-remote-agent` 使用。它们使用 Computer Token（由 `/computers/register` 返回），而不是 Mind Key。\n\n### POST /computers/register\n\n兑换安装码并获取 Computer Token。\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/computers/register \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"code\": \"ic_xyz789\",\n \"computer_name\": \"office-mac\",\n \"platform\": \"darwin\",\n \"platform_release\": \"14.5.0\",\n \"python\": \"3.12.4\"\n }'\n```\n\n响应：`{ \"computer_id\": \"comp_001\", \"computer_token\": \"ct_...\" }`\n\n> [!CRITICAL]\n> 请妥善保存 `computer_token` — 它只显示一次，且所有 Agent 侧端点都需要它。\n\n### GET /computers/me/poll\n\n长轮询新命令。Agent 会在循环中调用此端点。\n\n```bash\ncurl -H \"Authorization: Bearer ct_YOUR_COMPUTER_TOKEN\" \\\n \"https://synapse.schaefer.zone/computers/me/poll?wait=30\"\n```\n\n如果有待执行命令，则立即返回；否则等待 `wait` 秒后返回。\n\n### POST /computers/me/commands/:cid/result\n\n提交某条命令的执行结果。\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/computers/me/commands/cmd_001/result \\\n -H \"Authorization: Bearer ct_YOUR_COMPUTER_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"status\": \"done\",\n \"result\": { \"screenshot_b64\": \"iVBORw0KG...\" }\n }'\n```\n\n## 命令类型\n\n| 类型 | Payload | 说明 |\n|------|---------|-------------|\n| `screenshot` | `{}` | 截屏为 PNG（base64） |\n| `click` | `{x, y}` | 在指定坐标点击 |\n| `move` | `{x, y}` | 将鼠标移动到指定坐标 |\n| `type` | `{text}` | 在光标处输入文本 |\n| `key` | `{keys: [\"Ctrl\",\"c\"]}` | 按下组合键 |\n| `scroll` | `{deltaX, deltaY}` | 滚动滚轮 |\n| `drag` | `{fromX, fromY, toX, toY}` | 拖拽 |\n\n## 常见模式：LLM 驱动的 GUI 自动化\n\n```python\n# LLM Agent 工作流\n1. 列出计算机：GET /computers/list\n2. 截屏：GET /computers/:id/screenshot\n3. 分析截图（视觉模型）\n4. 排队点击：POST /computers/:id/commands {type:\"click\", payload:{x,y}}\n5. 等待结果：GET /computers/:id/commands/:cid\n6. 重新截屏验证\n7. 重复直到任务完成\n```\n\n## 下一步\n\n- [Browser 代理](/docs/api/browser) — 用于浏览器自动化的独立服务\n- [自托管 Agent 指南](/docs/guides/self-hosted-agents)\n","content_html":"

Computer Control API

\n

Computer Control API 让你能够远程控制已注册的计算机。目标机器上会运行一个小型 Agent（screen-remote-agent），轮询命令、执行命令并回传结果。这使 LLM 驱动的 GUI 自动化成为可能。

\n

架构

\n
┌─────────────┐  排队命令   ┌──────────┐  轮询  ┌─────────────────┐\n│ LLM Agent   │ ───────────▶ │ Synapse  │ ◀───── │ screen-remote   │\n│ (用户侧)    │              │  Server  │ ──────▶│ (在目标 PC 上) │\n└─────────────┘              └──────────┘ 结果   └─────────────────┘\n                                     ▲\n                                     │\n                              ┌─────────────┐\n                              │  Human UI   │\n                              │ (浏览器)    │\n                              └─────────────┘

用户侧端点（Mind Key 或 JWT）

\n

GET /computers/list

\n

列出所有已注册的计算机。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/computers/list

GET /computers/:id

\n

获取单台计算机的详情。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/computers/comp_001

POST /computers/install-code

\n

为注册新计算机生成一个安装码。

\n
curl -X POST https://synapse.schaefer.zone/computers/install-code \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"computer_name": "office-mac"}'

响应：{ "install_code": "ic_xyz789", "expires_at": "..." }

\n

POST /computers/:id/commands

\n

为远程 Agent 排队一条待执行的命令。

\n
curl -X POST https://synapse.schaefer.zone/computers/comp_001/commands \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{\n    "type": "screenshot",\n    "payload": {}\n  }'

响应：{ "command_id": "cmd_001", "status": "queued" }

\n

GET /computers/:id/command（通过查询参数）

\n

通过 GET 方式排队命令（用于简单场景）。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/computers/comp_001/command?type=screenshot"

GET /computers/:id/commands

\n

列出某台计算机最近的命令。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/computers/comp_001/commands?limit=50"

GET /computers/:id/commands/:cid

\n

获取某条具体命令的状态与结果。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/computers/comp_001/commands/cmd_001

GET /computers/:id/screenshot

\n

一次性操作：排队截图命令并等待最多 30 秒拿结果。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/computers/comp_001/screenshot > screenshot.png

POST /computers/:id/disable

\n

禁用某台计算机（吊销其令牌，保留记录以备审计）。

\n
curl -X POST -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/computers/comp_001/disable

DELETE /computers/:id

\n

永久删除某台计算机。

\n
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/computers/comp_001

Agent 侧端点（Computer Token）

\n

以下端点由运行在目标机器上的 screen-remote-agent 使用。它们使用 Computer Token（由 /computers/register 返回），而不是 Mind Key。

\n

POST /computers/register

\n

兑换安装码并获取 Computer Token。

\n
curl -X POST https://synapse.schaefer.zone/computers/register \\\n  -H "Content-Type: application/json" \\\n  -d '{\n    "code": "ic_xyz789",\n    "computer_name": "office-mac",\n    "platform": "darwin",\n    "platform_release": "14.5.0",\n    "python": "3.12.4"\n  }'

响应：{ "computer_id": "comp_001", "computer_token": "ct_..." }

\n
请妥善保存 `computer_token` — 它只显示一次，且所有 Agent 侧端点都需要它。

GET /computers/me/poll

\n

长轮询新命令。Agent 会在循环中调用此端点。

\n
curl -H "Authorization: Bearer ct_YOUR_COMPUTER_TOKEN" \\\n     "https://synapse.schaefer.zone/computers/me/poll?wait=30"

如果有待执行命令，则立即返回；否则等待 wait 秒后返回。

\n

POST /computers/me/commands/:cid/result

\n

提交某条命令的执行结果。

\n
curl -X POST https://synapse.schaefer.zone/computers/me/commands/cmd_001/result \\\n  -H "Authorization: Bearer ct_YOUR_COMPUTER_TOKEN" \\\n  -H "Content-Type: application/json" \\\n  -d '{\n    "status": "done",\n    "result": { "screenshot_b64": "iVBORw0KG..." }\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\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
类型Payload说明
screenshot{}截屏为 PNG（base64）
click{x, y}在指定坐标点击
move{x, y}将鼠标移动到指定坐标
type{text}在光标处输入文本
key{keys: ["Ctrl","c"]}按下组合键
scroll{deltaX, deltaY}滚动滚轮
drag{fromX, fromY, toX, toY}拖拽
\n

常见模式：LLM 驱动的 GUI 自动化

\n
# LLM Agent 工作流\n1. 列出计算机：GET /computers/list\n2. 截屏：GET /computers/:id/screenshot\n3. 分析截图（视觉模型）\n4. 排队点击：POST /computers/:id/commands {type:"click", payload:{x,y}}\n5. 等待结果：GET /computers/:id/commands/:cid\n6. 重新截屏验证\n7. 重复直到任务完成

下一步

\n\n","urls":{"html":"/docs/api/computers","text":"/docs/api/computers?format=text","json":"/docs/api/computers?format=json","llm":"/docs/api/computers?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}