REST API

仅 Cloud

云端 REST API 位于 https://api.adhf.dev。自托管用户可以访问本地 API —— 参见 Self-hosted API。

本页记录托管云自动化界面。

它不尝试涵盖：

诸如 /api/v1/status 之类的本地 standalone 端点
诸如 session-host 恢复之类的自托管运行时操作者流程
诸如 /api/v1/mux/* 之类的本地终端 mux 端点

对于这些内容，请改用 OSS 自托管文档。

认证

所有 API 请求都需要在 Authorization 头中提供一个 API 密钥：

bash

curl -H "Authorization: Bearer adk_..." \
     https://api.adhf.dev/api/v1/daemons

注意： 当前版本不支持通过仪表板签发 API 密钥。现有密钥仍可继续使用。如需访问，请联系支持。

对于常规的云自动化，API 密钥是主要的认证界面。

一些敏感的云账户变更现在需要一次近期的浏览器登录，而非 API 密钥认证。这些路由期望一个新鲜的仪表板 JWT 会话，当用 API 密钥或陈旧会话调用时会返回 403 RECENT_LOGIN_REQUIRED。

当前受近期登录保护的路由：

POST /api/v1/webhooks
PATCH /api/v1/webhooks/{webhookId}
DELETE /api/v1/webhooks/{webhookId}
POST /api/v1/webhooks/{webhookId}/test
POST /api/v1/daemons/{daemonId}/disconnect
POST /api/v1/daemons/{daemonId}/revoke
POST /api/v1/api-keys（创建）
DELETE /api/v1/api-keys/{keyId}（吊销）

权限范围

范围	说明
`ide:read`	列出守护进程、读取 IDE 状态
`ide:control`	启动/停止 IDE、发送守护进程命令
`agent:read`	读取聊天消息、代理状态
`agent:control`	发送消息、批准/拒绝操作
`terminal:exec`	在机器上执行终端命令
`webhook:manage`	检查投递，并在近期仪表板登录后管理 webhook

公开 API 结构

对于大多数云集成，请按以下层次思考：

GET /api/v1/daemons 查找已连接的机器
GET /api/v1/daemons/{daemonId}/status 检查机器和会话状态
/api/v1/shortcuts/* 用于你实际想要的常见代理操作
/api/v1/webhooks/* 用于向你自己的系统投递事件

除非你特别需要原始的守护进程命令路由器，否则请优先使用 Shortcuts。

所有守护进程和 shortcut 路由都限定在已认证云账户所拥有的机器和会话范围内。提供其他账户的守护进程或合成会话 id 会返回 404，而不会跨越账户边界。

守护进程

管理已连接的机器（守护进程）及其 IDE。

列出守护进程

http

GET /api/v1/daemons

范围： ide:read

返回所有已连接的机器及其托管的 IDE 和 CLI 代理。

响应：

json

{
  "daemons": [
    {
      "id": "c79baa8f...",
      "hostname": "M1-Server",
      "nickname": "작업용",
      "platform": "darwin",
      "cdpConnected": true,
      "ides": [
        { "id": "c79baa8f:ide:cursor_myproject", "type": "cursor", "cdpConnected": true }
      ],
      "clis": [
        { "id": "c79baa8f:cli:claude-cli", "type": "claude-cli", "name": "Claude Code" }
      ]
    }
  ]
}

获取守护进程状态

http

GET /api/v1/daemons/{daemonId}/status

范围： ide:read

返回详细的守护进程状态，包括 IDE/CLI 状态、工作区信息和代理活动。

发送守护进程命令

http

POST /api/v1/daemons/{daemonId}/command

范围： ide:control

向目标机器发送一个直接命令。

对于大多数集成，请优先使用下面的 Shortcuts API。POST /daemons/:id/command 是更底层的应急出口。

请求体：

json

{
  "type": "send_chat",
  "payload": { "message": "Hello!" }
}

可用命令类型

命令	目标	负载	说明
`send_chat`	IDE/CLI	`message`	发送一条聊天消息
`read_chat`	IDE/CLI	—	读取当前聊天内容
`resolve_action`	IDE/CLI	`action`	批准/拒绝代理操作
`screenshot`	IDE	`width?`	截取一张截图
`launch_ide`	守护进程	`ideType, enableCdp?`	启动一个 IDE
`launch_cli`	守护进程	`cliType, dir?, model?`	启动 CLI 会话
`stop_cli`	守护进程	`cliType`	停止 CLI 会话

内部路由器中并非每个命令都适合放入公开自动化材料。如果你在构建一个常规集成，请保持在已记录的命令集或 shortcut 端点上。

执行终端命令

http

POST /api/v1/daemons/{daemonId}/terminal

范围： terminal:exec

在守护进程机器上执行一个终端命令。

请求体：

json

{
  "command": "ls -la",
  "name": "my-terminal",
  "cwd": "/home/user"
}

断开守护进程

http

POST /api/v1/daemons/{daemonId}/disconnect

范围： ide:control

强制断开守护进程。守护进程可以自动重连。

这是一个受近期登录保护的云操作。API 密钥和陈旧的浏览器会话会收到 403 RECENT_LOGIN_REQUIRED。

撤销守护进程令牌

http

POST /api/v1/daemons/{daemonId}/revoke

范围： ide:control

永久撤销守护进程的连接令牌。需要在机器上重新运行 adhdev setup。

这是一个受近期登录保护的云操作。API 密钥和陈旧的浏览器会话会收到 403 RECENT_LOGIN_REQUIRED。

Shortcuts

面向最常见代理操作的便捷端点。

启动 IDE / CLI

http

POST /api/v1/shortcuts/{daemonId}/launch

范围： ide:control

请求体：

IDECLI

json

{ "type": "cursor" }

json

{ "type": "claude-cli", "dir": "/path/to/project" }

停止 CLI

http

POST /api/v1/shortcuts/{daemonId}/stop

范围： ide:control

请求体：

json

{ "type": "claude-cli" }

发送聊天消息

http

POST /api/v1/shortcuts/{ideId}/chat

范围： agent:control

向 AI 代理发送一条消息。ideId 是守护进程/会话状态 API 返回的机器范围目标 ID，包括诸如 {daemonId}:session:{sessionId} 之类的合成会话路由。

这是外部自动化的默认发送路径。

请求体（旧版文本形式）：

json

{ "message": "Fix the bug in auth.ts" }

请求体（规范信封形式）：

json

{
  "input": {
    "parts": [
      { "type": "text", "text": "Fix the bug in auth.ts" }
    ],
    "textFallback": "Fix the bug in auth.ts"
  }
}

可选 —— 为多代理 IDE 指定代理类型：

json

{ "message": "Fix the bug", "agentType": "cursor" }

你必须提供 message 或 input 之一。

读取聊天

http

GET /api/v1/shortcuts/{ideId}/chat

范围： agent:read

从代理读取当前聊天内容。可选地按 ?agentType=cursor 过滤。

聊天调试包

http

GET /api/v1/shortcuts/{ideId}/chat/debug
POST /api/v1/shortcuts/{ideId}/chat/debug

范围： agent:read

为当前聊天/会话构建一个有界、已脱敏的调试包。守护进程生成权威的提供方/解析器/会话/终端证据；POST 可以包含一个仪表板 frontendSnapshot，用当前渲染的前端状态对其进行补充。

POST 的可选请求体：

json

{ "agentType": "codex-cli", "frontendSnapshot": { "activeConversation": { "sessionId": "session_..." } } }

响应包含 bundle 和可直接复制的 text。密钥和凭据默认会被脱敏。

批准 / 拒绝操作

http

POST /api/v1/shortcuts/{ideId}/approve

范围： agent:control

批准或拒绝一个待处理的代理操作。

请求体：

json

{ "action": "approve" }

或

json

{ "action": "reject", "agentType": "cursor" }

获取代理状态

http

GET /api/v1/shortcuts/{ideId}/status

范围： agent:read

返回当前状态（idle、generating、waiting_approval、error）、存在时的提供方摘要元数据/控件，以及工作区信息。

Webhook

管理用于实时事件通知的 webhook 订阅。设置说明和签名验证请参见 Webhook 功能指南。

列出 Webhook

http

GET /api/v1/webhooks

范围： webhook:manage

创建 Webhook

http

POST /api/v1/webhooks

范围： webhook:manage

请求体：

json

{
  "url": "https://example.com/hook",
  "events": ["agent:status", "agent:approve_request"]
}

events 是一个允许列表 —— 哪些事件可单独订阅、哪些只能通过 "*" 接收，参见下方的事件一节。使用 ["*"] 订阅所有事件。响应包含一个用于签名验证的 secret（只显示一次）。

这是一个受近期登录保护的云操作。API 密钥和陈旧的浏览器会话会收到 403 RECENT_LOGIN_REQUIRED。

切换 Webhook

http

PATCH /api/v1/webhooks/{webhookId}

范围： webhook:manage

请求体：

json

{ "active": false }

这是一个受近期登录保护的云操作。API 密钥和陈旧的浏览器会话会收到 403 RECENT_LOGIN_REQUIRED。

删除 Webhook

http

DELETE /api/v1/webhooks/{webhookId}

范围： webhook:manage

这是一个受近期登录保护的云操作。API 密钥和陈旧的浏览器会话会收到 403 RECENT_LOGIN_REQUIRED。

列出投递

http

GET /api/v1/webhooks/{webhookId}/deliveries?limit=20

范围： webhook:manage

返回最近的投递历史，包含状态码、响应体和计时。

测试 Webhook

http

POST /api/v1/webhooks/{webhookId}/test

范围： webhook:manage

向 webhook URL 发送一个测试 webhook:test 事件。

这是一个受近期登录保护的云操作。API 密钥和陈旧的浏览器会话会收到 403 RECENT_LOGIN_REQUIRED。

TURN 凭证

http

GET /api/v1/turn/credentials

为仪表板自身的 P2P 连接签发短期 TURN/STUN 凭证（守护进程通过 WebSocket auth_ok 消息单独接收凭证——这个 REST 端点仅供仪表板使用）。需要经过身份验证的请求（访问令牌）；令牌过期会返回 401，调用方应回退到仅 STUN。

TURN 在包括 Free 在内的所有销售计划上都是启用的——这是一个刻意的产品决策，而不是 Free 层级的限制。响应仅在以下情况回退到仅 STUN（turn: false）：管理员通过覆盖将某个计划设为 turnenabled: false，或者 TURN 服务本身未配置或返回错误。

响应：

json

{
  "iceServers": [ { "urls": "stun:stun.cloudflare.com:3478" } /* 启用 TURN 时会附加 TURN 服务器 */ ],
  "turn": true,
  "plan": "pro"
}

成功获取的 TURN 凭证会在服务器端缓存 1 小时，因此在该窗口内重复调用会返回相同的服务器并带有 cached: true。

提供方注册表

http

GET /api/v1/registry/providers
GET /api/v1/registry/providers/{type}
GET /api/v1/registry/providers/{type}/{version}
GET /api/v1/registry/providers/{type}/{version}/download

已发布提供方包的公开、无需认证的目录——守护进程用它来同步提供方包。?channel=preview 可选择进入 preview 命名空间；省略（或使用其他值）则返回 stable。这个注册表分发机制是一项独立、未冻结的能力，与已冻结的提供方浏览仪表板界面是分开的。

写入端点仅限管理员，或持有更窄的 registry:publish 权限范围的 API 密钥使用：

http

POST   /api/v1/registry/providers
POST   /api/v1/registry/providers/{type}/{version}/promote
DELETE /api/v1/registry/providers/{type}/{version}

POST /registry/providers 用于发布新包，且请求体中必须始终包含显式的 channel: "preview"——直接发布到 stable 会被拒绝；stable 发布只能通过 promote 端点完成，该端点引用已有 preview 版本的构件，而不接受新字节内容。DELETE 用于撤回某个版本（默认是 stable 渠道，除非指定 ?channel=preview）。

事件

这些事件会被投递给 webhook，并同时驱动实时云通知流程。webhook 的 events 订阅是一个允许列表，而不是自由列出的名称（参见 packages/server/src/utils/webhook-events.ts 中的 normalizeWebhookEvents）：

可单独订阅：

事件	说明
`daemon:connect`	机器上线
`daemon:disconnect`	机器下线
`agent:status`	代理状态变化（限流，每个守护进程每 10 秒最多 1 次）
`agent:approve_request`	保留字段 —— 在允许列表中，但服务器目前不会发出

会被发出，但仅投递给用 "*" 订阅的 webhook：

事件	说明
`agent:generating_started`	代理开始生成响应
`agent:generating_completed`	代理完成生成（守护进程观测到本轮开始时，包含以整数秒为单位的 `duration`）
`agent:waiting_approval`	代理正在等待用户批准
`agent:waiting_choice`	代理正在等待多选提示的选择
`agent:stopped`	代理会话已停止
`monitor:no_progress`	代理看起来已停滞、没有进展（旧别名：`monitor:long_generating`）
`webhook:test`	通过 `POST /webhooks/{id}/test` 显式请求的测试投递 —— 仅投递给被测试的那个 webhook，绕过订阅过滤

事件负载

每次投递都是一个 JSON 正文，包含三个顶层字段：event、payload 和 timestamp（服务器发出这次投递的时间，epoch 毫秒）。对于代理和监控事件（除 agent:status 以外的 agent:*，以及 monitor:no_progress），负载如下所示：

json

{
  "event": "agent:generating_completed",
  "payload": {
    "daemonId": "8e1f4c2a9b7d3e5f6a0c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f",
    "daemonType": "adhdev-daemon",
    "event": "agent:generating_completed",
    "timestamp": 1714000000000,
    "targetSessionId": "9b2d7c4e-1f3a-4b5c-8d6e-0a1b2c3d4e5f",
    "providerType": "claude-cli",
    "providerSessionId": "3f2a9c1e-5b7d-4e8a-9c0f-1a2b3c4d5e6f",
    "workspaceName": "/home/dev/projects/myproject",
    "duration": 42,
    "surfaceHidden": false,
    "muted": false
  },
  "timestamp": 1714000000215
}

字段	出现条件
`daemonId`	始终 — 上报该事件的守护进程连接
`event`, `timestamp`	始终 — 事件名称，以及守护进程观测到它的时间（epoch 毫秒）
`targetSessionId`	事件针对某个代理会话时 — `agent:generating_completed` 和 `agent:stopped` 始终包含
`providerType`	守护进程能解析到会话时出现。代理提供方（例如 `claude-cli`、`cursor`）。无法解析时不含此字段，且不会填入守护进程类型
`daemonType`	始终。发送该事件的守护进程类型，目前为 `adhdev-daemon`
`providerSessionId`	提供方公开了自己的会话 ID 时
`workspaceName`	会话有工作区时 — CLI 代理的工作目录，或 IDE 的工作区
`duration`	仅 `agent:generating_completed`，且守护进程观测到了本轮开始时 — 整数秒
`elapsedSec`	`monitor:no_progress` — 没有可见进展的秒数
`modalMessage`, `modalButtons`	`agent:waiting_approval` / `agent:waiting_choice` — 审批提示文本及按钮标签
`surfaceHidden`, `muted`	守护进程托管该会话时 — 它在仪表盘上是否被隐藏或静音

daemon:connect、daemon:disconnect、agent:status 和 webhook:test 各自使用不同形状的负载。除 modalMessage 中的审批提示文本外，负载中绝不包含聊天消息、聊天标题或代理回复。

典型流程

最常见的 API 流程是：

用 GET /api/v1/daemons 列出机器
从守护进程状态负载中挑选一个目标代理
用 POST /api/v1/shortcuts/{ideId}/chat 发送一条消息
轮询 GET /api/v1/shortcuts/{ideId}/status 或使用 webhook
用 GET /api/v1/shortcuts/{ideId}/chat 读取对话记录

本页排除的内容

如果你在寻找以下任何内容，那这是错误的 API 页面：

standalone 的 GET /api/v1/status
standalone 的 POST /api/v1/command
托管本地 CLI 会话的运行时快照/事件端点
终端 mux 工作区端点

这些属于 Self-hosted API。

速率限制

单请求限制

限制	值
API 密钥	每分钟 120 个请求
IP 地址	每分钟 60 个请求
认证登录/回调端点	每 5 分钟 100 个请求
命令超时	60 秒

每月调用限制

套餐	每月 API 调用
Free	1,000
Pro	50,000
Ultra	500,000
Enterprise	无限

错误代码

状态	代码	说明
`400`	—	请求错误（验证失败）
`401`	`AUTH_REQUIRED`	缺少 `Authorization` 头
`401`	`AUTH_INVALID`	无效或已过期的 API 密钥
`403`	`AUTH_FORBIDDEN`	API 密钥缺少所需的范围
`403`	`RECENT_LOGIN_REQUIRED`	敏感的云操作需要一次新鲜的仪表板登录，而非 API 密钥认证或陈旧会话
`404`	—	未找到守护进程/资源、已过期的邀请/共享，或目标不属于已认证账户
`429`	`RATE_LIMITED`	超出每分钟速率限制
`429`	`API_LIMIT_EXCEEDED`	达到每月 API 调用限制
`500`	—	命令发送失败（守护进程离线）
`503`	—	守护进程已连接但 WebSocket 已断开
`504`	—	命令响应超时（超过 60 秒）

REST API ​

认证 ​

权限范围 ​

公开 API 结构 ​

守护进程 ​

列出守护进程 ​

获取守护进程状态 ​

发送守护进程命令 ​

可用命令类型 ​

执行终端命令 ​

断开守护进程 ​

撤销守护进程令牌 ​

Shortcuts ​

启动 IDE / CLI ​

停止 CLI ​

发送聊天消息 ​

读取聊天 ​

聊天调试包 ​

批准 / 拒绝操作 ​

获取代理状态 ​

Webhook ​

列出 Webhook ​

创建 Webhook ​

切换 Webhook ​

删除 Webhook ​

列出投递 ​

测试 Webhook ​

TURN 凭证 ​

提供方注册表 ​

事件 ​

事件负载 ​

典型流程 ​

本页排除的内容 ​

速率限制 ​

单请求限制 ​

每月调用限制 ​

错误代码 ​

REST API

认证

权限范围

公开 API 结构

守护进程

列出守护进程

获取守护进程状态

发送守护进程命令

可用命令类型

执行终端命令

断开守护进程

撤销守护进程令牌

Shortcuts

启动 IDE / CLI

停止 CLI

发送聊天消息

读取聊天

聊天调试包

批准 / 拒绝操作

获取代理状态

Webhook

列出 Webhook

创建 Webhook

切换 Webhook

删除 Webhook

列出投递

测试 Webhook

TURN 凭证

提供方注册表

事件

事件负载

典型流程

本页排除的内容

速率限制

单请求限制

每月调用限制

错误代码