CodeBuddy HTTP API (Beta)

注意：说明：

注意：Beta: 此 API 处于 Beta 阶段，接口可能会有调整。欢迎反馈意见。

·REST API (/api/v1/*) — 无状态 HTTP 请求/响应，适合 Webhook 接入、管理操作、简单查询

·ACP (/api/v1/acp) — 有状态流式协议（JSON-RPC over SSE），适合构建完整 Agent 客户端应用

二、启动 HTTP 服务

codebuddy –serve –port 8080 –session-id my-session

三、API 文档（Swagger UI）

服务启动后访问：

·交互式文档: http://127.0.0.1:8080/api/docs

·OpenAPI 规范: http://127.0.0.1:8080/api/openapi.json

Swagger UI 提供所有公开端点的交互式测试界面。

四、验证服务正常

curl http://127.0.0.1:8080/api/v1/health# {"data":{"status":"ok","uptime":12.3,"platforms":["generic","wecom","wechat-kf"]}}

五、API 分层

七、自定义请求头

所有 API 请求（除豁免路径外）必须携带自定义请求头：

X-CodeBuddy-Request: 1

原理：自定义请求头会使浏览器的跨域请求变为"非简单请求"，强制触发 CORS preflight。配合 CORS 白名单，非法源的请求会被拦截。即使攻击者使用 fetch(url, { mode: 'no-cors' })，浏览器也不允许在 no-cors 模式下发送自定义头，请求会因缺少该头而被服务端拒绝（403）。

八、豁免路径

以下路径不需要携带 X-CodeBuddy-Request 头：

可通过环境变量 CODEBUDDY_DISABLE_REQUEST_VALIDATION=1 关闭此校验。

九、CORS 白名单

跨域请求的 Origin 会与服务端 CORS 白名单匹配，不在白名单中的来源会被拒绝（预检返回无 CORS 头的 204，实际请求返回 403 Origin not allowed）。白名单来源：

·本地端点自身的回环变体（localhost / 127.0.0.1 / [::1]，仅限服务实际监听的端口）

·Tunnel URL（如启用）

·配置项 gateway.corsOrigins

·环境变量 CODEBUDDY_CODE_CORS_ORIGINS（逗号分隔，支持精确 origin、*.domain 子域通配和 * 全开）

注意：回环来源不再被无条件放行。 早期实现允许任意 localhost / 127.0.0.1 来源（不论端口），这使用户浏览器中任何占用本地端口的页面（如恶意页运行在 http://localhost:3000）都能跨源调用本服务的执行进程 / 文件读写接口。Cookie 的 SameSite=Strict 无法防护此场景 —— 端口不属于 "site" 的组成部分，localhost:3000 与 localhost:8321 属同 site 不同 origin，浏览器会照常携带会话 Cookie。

本地开发（Vite dev server 5173 → 后端 8321 属跨源）需显式声明来源：

CODEBUDDY_CODE_CORS_ORIGINS=http://localhost:5173 codebuddy –serve

被拒绝时，服务端日志与 403 响应体的 hint 字段都会提示该配置方式。

绑定 0.0.0.0 时（如 –host 0.0.0.0，常见于云虚拟机 / 局域网暴露场景），若未显式设置 CODEBUDDY_CODE_CORS_ORIGINS，服务端会自动允许所有来源（等价于配置 *），无需额外配置即可通过任意 IP 或域名访问 Web UI；显式设置该环境变量时以用户配置为准。此场景下认证为强制开启（见下），凭据仍是必需的。

十、认证

–serve 默认开启密码认证。首次启动会生成随机密码并写入 ~/.codebuddy/settings.json，同时在终端打印一条带密码的可点链接：

Endpoint http://127.0.0.1:8321 Web UI http://127.0.0.1:8321/?password=<生成的密码> Password <生成的密码> Config ~/.codebuddy/settings.json

点击该链接即可登录 Web UI（服务端会下发有效期 30 天的 gateway_session Cookie，后续直接访问端点即可，无需重复输入）。

认证模式优先级（高 → 低）：

注意：安全说明：

注意：这组端点包含执行进程（/api/v1/process/*）、读写任意文件（/api/v1/files/*、/api/v1/fs/*）和交互式终端（/api/v1/pty/*）等敏感能力。因此默认强制认证（secure by default，与 E2B Secured Access 的默认行为一致）。关闭认证意味着同机任意进程都能通过该服务执行命令、读写文件，仅建议在隔离环境（容器 / 一次性沙箱）或 CI 中使用。

关闭认证（仅在明确知晓风险时使用，启动时会打印警告）：

codebuddy –serve –auth none# 或CODEBUDDY_GATEWAY_AUTH=none codebuddy –serve

十一、携带凭据的方式

API 请求（/api/v1/*）只接受请求头或 Cookie：

# 1) Bearer Token（推荐，同时携带安全头）curl -H "X-CodeBuddy-Request: 1" \\ -H "Authorization: Bearer YOUR_PASSWORD" \\ http://host:port/api/v1/sessions# 2) X-Access-Token（与 Bearer 等价，对齐 E2B envd 的凭据头习惯）curl -H "X-CodeBuddy-Request: 1" \\ -H "X-Access-Token: YOUR_PASSWORD" \\ http://host:port/api/v1/sessions# 3) Cookie（浏览器登录后自动携带）curl -H "X-CodeBuddy-Request: 1" \\ -H "Cookie: gateway_session=<sha256(password)>" \\ http://host:port/api/v1/sessions

注意：?password= 仅对 GET / 与 POST /api/v1/auth/login 有效，对其他 /api/v1/* 端点无效（会返回 401）。这是有意设计：URL 会被记录到浏览器历史、服务端访问日志，并在用户复制分享链接时泄露，因此密码不出现在 API 请求的网址中。?password= 的唯一用途是首次进门换取 gateway_session Cookie。

注意：用 ?password= 测 API 会得到 401，这不是认证实现有问题。

十二、响应格式

所有 /api/v1/* 端点使用统一的信封格式：

// 成功{ "data": { … }}// 错误{ "error": { "code": "AUTH_REQUIRED", // 机器可读错误码 "message": "Authentication required" // 人类可读描述 }}

十四、系统

十五、认证

十六、Runs（Agent 执行）

十七、Webhooks（第三方平台接入）

支持的平台：generic、wecom（企业微信）、wechat-kf（微信客服）

十八、会话

十九、PTY（终端）

20、Workers & Daemon

Worker 是运行中的 CLI 进程（interactive / bg / daemon），通过 PID 文件注册表管理。

Workers 查询参数:

·?kind=bg — 按类型过滤（interactive / bg / daemon / daemon-worker）

·?local=true — 仅返回本地 Worker（远程代理调用时使用）

日志类型参数 (GET /api/v1/workers/:id/logs):

·?type=telemetry — 遥测日志（~/.codebuddy/logs/{date}/）

·?type=process — 进程 stdout/stderr（bg/daemon 日志）

·?type=debug — 调试日志（~/.codebuddy/debug/，需 –debug）

·?type=transcript — 对话历史摘要

·?tail=200 — 只返回最后 N 行

·不传 type 时自动选择最佳来源（telemetry > process > debug > transcript）

21、Jobs（后台智能体实例）

Jobs 是由 /bg、左箭头转后台或 codebuddy agents 派发出的后台智能体实例。它们与 CLI agent-view / TUI 共用 JobStore 和生命周期语义。

派发请求体 (POST /api/v1/jobs):

effort、permissionMode、bgIsolation 按白名单校验，非法值返回 400 BAD_REQUEST。请求省略可选字段时不覆盖会话或全局默认值。

生命周期字段:

·state: working / blocked / done / failed / stopped

·status: 存活进程的即时状态 busy / waiting / idle / stopped

·tempo: active / idle / blocked

·alive 与 settled 独立；settled=true && alive=false 表示已结束历史

·foregroundHeld=true 表示仍被前台终端持有，暂时不能 attach

·webUrl 仅在 job worker 存活并监听 loopback HTTP(S) 时返回，否则为 null

对话与错误:

·/transcript 一次性返回 { sessionId, updates }，最多包含最近 1000 行转换后的 ACP replay updates。

·/stream 返回 text/event-stream；先回放最多 1000 行，再每秒尾随新增 JSONL 记录；shell job 返回空流。

·不存在的 job 返回 404 JOB_NOT_FOUND。

·删除若被 worktree 或前台持有守卫拒绝，仍返回 HTTP 200，但 body 为 { "deleted": false, "reason": "…" }。

# 派发后台智能体curl -H "X-CodeBuddy-Request: 1" \\ -H "Authorization: Bearer $PASSWORD" \\ -H 'Content-Type: application/json' \\ -X POST http://127.0.0.1:8080/api/v1/jobs \\ -d '{"prompt":"检查当前仓库的测试状态","cwd":"/repo/app"}'# 订阅 job 列表变化curl -N -H "X-CodeBuddy-Request: 1" \\ -H "Authorization: Bearer $PASSWORD" \\ http://127.0.0.1:8080/api/v1/jobs/events

22、Channels（远程控制）

23、文件系统（E2B 兼容）

文件内容操作（对齐 E2B envd HTTP 端点）：

文件操作（对齐 E2B filesystem.proto）：

文件监听（对齐 E2B filesystem.proto）：

CBC 增强：

24、进程管理（E2B 兼容）

对齐 E2B process.proto，将 gRPC 方法映射为 REST 端点：

25、ACP（Agent Client Protocol）

26、文件变更（Checkpoint）— Internal

注意：这些是内部端点，无稳定性保证，仅供 Web UI 消费。

27、插件管理

28、配置管理

29、工作目录

30、任务模板

31、使用统计

32、链路追踪

Traces 查询参数:

·?offset=0&limit=50 — 分页（limit 上限 200）

·?session_id=xxx — 按会话 ID 过滤

·?worker_pid=12345 — 指定 Worker 实例（支持远程代理）

·?worker_pid=all — 扫描所有实例

33、定时任务

定时任务查询参数:

·?sessionId=xxx — 会话 ID（必需，不传则使用当前活跃会话）

34、使用示例

以下示例为突出各端点自身的参数而省略了公共请求头。实际调用 /api/v1/* 时需要补上：

-H "X-CodeBuddy-Request: 1" -H "Authorization: Bearer $PASSWORD"

其中 $PASSWORD 是 –serve 启动时打印的密码（见认证）。缺少安全头会得到403 Missing required header，缺少凭据会得到 401 AUTH_REQUIRED。仅/api/v1/health、/api/v1/auth/status 等豁免端点可直接访问。

35、健康检查

curl http://127.0.0.1:8080/api/v1/health

36、发起 Agent 执行

# 发送消息（body 为 Gateway Protocol 格式，id/type 必填）curl -X POST http://127.0.0.1:8080/api/v1/runs \\ -H "Content-Type: application/json" \\ -H "X-CodeBuddy-Request: 1" \\ -d '{ "id": "run-1", "type": "message", "source": {"platform": "generic", "sender": {"id": "dev", "name": "Developer"}, "conversation": {"id": "run-1", "type": "direct"}}, "payload": {"text": "帮我分析代码性能"} }'# 响应: {"data": {"runId": "uuid-xxx", "status": "accepted"}}# 通过 SSE 流获取结果（同样需携带 X-CodeBuddy-Request 头）curl -H "X-CodeBuddy-Request: 1" http://127.0.0.1:8080/api/v1/runs/uuid-xxx/stream

37、请求体字段（Gateway Protocol）

POST /api/v1/runs 的请求体为 Gateway Protocol 入站消息格式：

权威定义见源码 src/node/remote-gateway/gateway-protocol.ts 的 GatewayInboundMessage。

38、PTY 终端管理

# 创建终端curl -X POST http://127.0.0.1:8080/api/v1/pty \\ -H "Content-Type: application/json" \\ -d '{"cols": 120, "rows": 40}'# 列出终端curl http://127.0.0.1:8080/api/v1/pty# SSE 流式获取输出（替代 WebSocket）curl http://127.0.0.1:8080/api/v1/pty/SESSION_ID/output# 发送输入curl -X POST http://127.0.0.1:8080/api/v1/pty/SESSION_ID/input/send \\ -H "Content-Type: application/json" \\ -d '{"data": "ls -la\\n"}'# 调整大小curl -X POST http://127.0.0.1:8080/api/v1/pty/SESSION_ID/resize \\ -H "Content-Type: application/json" \\ -d '{"cols": 200, "rows": 50}'# 销毁终端curl -X DELETE http://127.0.0.1:8080/api/v1/pty/SESSION_ID

39、文件系统操作（E2B 兼容）

# 下载文件curl "http://127.0.0.1:8080/api/v1/files/download?path=/tmp/test.txt"# 上传文件curl -X POST "http://127.0.0.1:8080/api/v1/files/upload?path=/tmp/upload.txt" \\ -H "Content-Type: application/octet-stream" \\ –data-binary @local-file.txt# 获取文件信息curl -X POST http://127.0.0.1:8080/api/v1/fs/stat \\ -H "Content-Type: application/json" \\ -d '{"path": "/tmp"}'# 列出目录curl -X POST http://127.0.0.1:8080/api/v1/fs/list \\ -H "Content-Type: application/json" \\ -d '{"path": "/tmp", "depth": 2}'# 创建目录curl -X POST http://127.0.0.1:8080/api/v1/fs/mkdir \\ -H "Content-Type: application/json" \\ -d '{"path": "/tmp/new-dir"}'# 文件模糊搜索（CBC 增强）curl "http://127.0.0.1:8080/api/v1/fs/search?query=component&limit=10"

40、进程管理（E2B 兼容）

# 启动进程（JSON 模式）curl -X POST http://127.0.0.1:8080/api/v1/process/start \\ -H "Content-Type: application/json" \\ -d '{"process": {"cmd": "python3", "args": ["script.py"]}, "tag": "my-script"}'# 启动进程（SSE 流式输出）curl -X POST http://127.0.0.1:8080/api/v1/process/start \\ -H "Content-Type: application/json" \\ -H "Accept: text/event-stream" \\ -d '{"process": {"cmd": "python3", "args": ["script.py"]}}'# 列出运行中进程curl http://127.0.0.1:8080/api/v1/process/list# 发送 stdincurl -X POST http://127.0.0.1:8080/api/v1/process/input/send \\ -H "Content-Type: application/json" \\ -d '{"process": {"pid": 12345}, "input": {"stdin": "hello\\n"}}'# 发送信号（SIGTERM）curl -X POST http://127.0.0.1:8080/api/v1/process/signal/send \\ -H "Content-Type: application/json" \\ -d '{"process": {"tag": "my-script"}, "signal": 15}'# 系统指标 + 实例进程指标curl http://127.0.0.1:8080/api/v1/metrics# 响应: { data: { ts, cpuCount, cpuUsedPct, memTotalMib, memUsedMib, diskUsed, diskTotal, instances: [{ id, cwd, pid, rssMib, heapUsedMib, heapTotalMib, uptimeSeconds, … }] } }

41、会话管理

# 获取当前工作空间的会话列表curl http://127.0.0.1:8080/api/v1/sessions# 获取所有工作空间的会话列表curl http://127.0.0.1:8080/api/v1/sessions?cwd=*# 获取指定工作目录的会话列表curl http://127.0.0.1:8080/api/v1/sessions?cwd=/path/to/workspace# 获取指定项目的会话列表（按压缩工作目录名过滤）curl http://127.0.0.1:8080/api/v1/sessions?cwd=*&projectId=workspace-hash# 重命名会话curl -X POST http://127.0.0.1:8080/api/v1/sessions/SESSION_ID/rename \\ -H "Content-Type: application/json" \\ -d '{"name": "性能优化讨论"}'

cwd 查询参数说明:

42、文件变更管理（Internal）

# 获取文件 diff（需要文件在 checkpoint 中被跟踪）curl -X POST http://127.0.0.1:8080/internal/file-changes/diff \\ -H "Content-Type: application/json" \\ -d '{"path": "/path/to/file.ts"}'# 响应: {"data": {"path": "/path/to/file.ts", "oldText": "…", "newText": "…"}}# 列出可回退的 checkpointcurl -X POST http://127.0.0.1:8080/internal/file-changes/checkpoints \\ -H "Content-Type: application/json" \\ -d '{}'# 响应: {"data": {"checkpoints": [{"id": "xxx", "label": "…", "createdAt": 1234567890, "files": […], "additions": 5, "deletions": 2}]}}# 按文件撤回变更curl -X POST http://127.0.0.1:8080/internal/file-changes/revert \\ -H "Content-Type: application/json" \\ -d '{"paths": ["/path/to/file.ts"]}'# 响应: {"data": {"success": true, "revertedFiles": ["/path/to/file.ts"]}}# 回退到指定 checkpointcurl -X POST http://127.0.0.1:8080/internal/file-changes/revert \\ -H "Content-Type: application/json" \\ -d '{"checkpointId": "checkpoint-uuid", "scope": "CodeAndConversation"}'# scope 可选值: "Code"（仅回退文件）, "Conversation"（仅回退对话）, "CodeAndConversation"（全部回退）# 撤回全部变更（回退到最早的 checkpoint）curl -X POST http://127.0.0.1:8080/internal/file-changes/revert \\ -H "Content-Type: application/json" \\ -d '{}'

43、插件管理

# 列出已安装插件（每项带 isBuiltIn 布尔字段，标识是否属于内置市场）curl http://127.0.0.1:8080/api/v1/plugins# 只列出用户自行安装的插件，过滤掉内置市场下的插件curl "http://127.0.0.1:8080/api/v1/plugins?includeBuiltin=false"# 安装插件（"name@marketplace" 格式）curl -X POST http://127.0.0.1:8080/api/v1/plugins \\ -H "Content-Type: application/json" \\ -d '{"plugin": "my-plugin@my-marketplace"}'# 启用插件curl -X POST http://127.0.0.1:8080/api/v1/plugins/enable \\ -H "Content-Type: application/json" \\ -d '{"plugin": "my-plugin@my-marketplace"}'# 禁用插件curl -X POST http://127.0.0.1:8080/api/v1/plugins/disable \\ -H "Content-Type: application/json" \\ -d '{"plugin": "my-plugin@my-marketplace"}'# 卸载插件curl -X POST http://127.0.0.1:8080/api/v1/plugins/uninstall \\ -H "Content-Type: application/json" \\ -d '{"plugin": "my-plugin@my-marketplace"}'# 更新插件到最新版本（传 waitForApply=true 可等待重建生效后再返回）curl -X POST http://127.0.0.1:8080/api/v1/plugins/update \\ -H "Content-Type: application/json" \\ -d '{"plugin": "my-plugin@my-marketplace"}'# 列出插件市场（每项带 isBuiltIn 布尔字段）curl http://127.0.0.1:8080/api/v1/plugins/marketplaces# 只列出用户自行添加的市场，过滤掉内置市场curl "http://127.0.0.1:8080/api/v1/plugins/marketplaces?includeBuiltin=false"# 添加插件市场curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces \\ -H "Content-Type: application/json" \\ -d '{"source": "https://example.com/marketplace", "name": "my-marketplace"}'# 添加插件市场并默认开启自动更新（等价于添加后再调一次 marketplaces/auto-update）curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces \\ -H "Content-Type: application/json" \\ -d '{"source": "https://example.com/marketplace", "name": "my-marketplace", "autoUpdate": true}'# 浏览市场中的插件curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces/browse \\ -H "Content-Type: application/json" \\ -d '{"marketplace": "my-marketplace"}'# 更新市场（真正从远端拉取最新内容）curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces/update \\ -H "Content-Type: application/json" \\ -d '{"marketplace": "my-marketplace"}'# 开启/关闭市场自动更新（开启后后台周期性同步并升级已安装插件）curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces/auto-update \\ -H "Content-Type: application/json" \\ -d '{"marketplace": "my-marketplace", "autoUpdate": true}'# 删除插件市场curl -X DELETE http://127.0.0.1:8080/api/v1/plugins/marketplaces/my-marketplace

44、配置管理

# 列出所有配置curl http://127.0.0.1:8080/api/v1/settings# 按作用域列出配置curl "http://127.0.0.1:8080/api/v1/settings?scope=user"# 获取单个配置curl http://127.0.0.1:8080/api/v1/settings/model# 设置配置值curl -X PUT http://127.0.0.1:8080/api/v1/settings/theme \\ -H "Content-Type: application/json" \\ -d '{"value": "dark"}'# 向数组类配置追加值curl -X POST http://127.0.0.1:8080/api/v1/settings/permissions/items \\ -H "Content-Type: application/json" \\ -d '{"values": ["Allow: Read(**)"]}'# 从数组类配置移除值curl -X POST http://127.0.0.1:8080/api/v1/settings/permissions/remove \\ -H "Content-Type: application/json" \\ -d '{"values": ["Allow: Read(**)"]}'

45、工作目录

管理附加工作目录，使权限系统放行这些目录下的文件操作（与 /add-dir 命令效果一致）。

# 列出当前附加工作目录curl http://127.0.0.1:8080/api/v1/workspace-dirs# 添加工作目录curl -X POST http://127.0.0.1:8080/api/v1/workspace-dirs \\ -H "Content-Type: application/json" \\ -d '{"path": "/Users/me/other-project"}'# 移除工作目录curl -X DELETE "http://127.0.0.1:8080/api/v1/workspace-dirs?path=/Users/me/other-project"# 全量同步（页面刷新恢复后调用）curl -X PUT http://127.0.0.1:8080/api/v1/workspace-dirs/sync \\ -H "Content-Type: application/json" \\ -d '{"dirs": ["/Users/me/project-a", "/Users/me/project-b"]}'

注意：说明：

46、使用统计

# 获取历史使用统计（活动热力图、模型/工具使用排行、连续活跃天数等）curl http://127.0.0.1:8080/api/v1/stats# 获取当前会话的实时成本统计curl http://127.0.0.1:8080/api/v1/stats/session

47、链路追踪

# 获取 trace 列表（分页）curl "http://127.0.0.1:8080/api/v1/traces?offset=0&limit=20"# 按会话 ID 过滤curl "http://127.0.0.1:8080/api/v1/traces?session_id=SESSION_ID"# 获取 trace 详情（含所有 spans）curl http://127.0.0.1:8080/api/v1/traces/TRACE_ID# 从远程 Worker 获取 tracescurl "http://127.0.0.1:8080/api/v1/traces?worker_pid=12345"# 清空所有 tracescurl -X DELETE http://127.0.0.1:8080/api/v1/traces

48、定时任务管理

# 获取定时任务列表curl "http://127.0.0.1:8080/api/v1/scheduled-tasks?sessionId=SESSION_ID"# 创建定时任务（每 5 分钟执行）curl -X POST http://127.0.0.1:8080/api/v1/scheduled-tasks \\ -H "Content-Type: application/json" \\ -d '{"cron": "*/5 * * * *", "prompt": "检查构建状态", "sessionId": "SESSION_ID"}'# 创建一次性任务（每周一上午 9 点）curl -X POST http://127.0.0.1:8080/api/v1/scheduled-tasks \\ -H "Content-Type: application/json" \\ -d '{"cron": "0 9 * * 1", "prompt": "生成周报", "recurring": false, "sessionId": "SESSION_ID"}'# 创建持久化任务（重启后仍保留）curl -X POST http://127.0.0.1:8080/api/v1/scheduled-tasks \\ -H "Content-Type: application/json" \\ -d '{"cron": "0 0 * * *", "prompt": "每日清理", "durable": true, "sessionId": "SESSION_ID"}'# 删除定时任务curl -X DELETE "http://127.0.0.1:8080/api/v1/scheduled-tasks/TASK_ID?sessionId=SESSION_ID"

49、错误码