用 Runtime API 自动化

在脚本中运行单个任务

codewhale exec "Reply with exactly: pong"
codewhale exec --auto --sandbox workspace-write "fix the failing test and run it again"
codewhale exec --auto --sandbox workspace-write --output-format stream-json "update the changelog"

普通的 exec 只回答一次，不使用工具。--auto 默认启用 Full Access（完全访问）：工具无需批准即可运行，shell 命令没有 Codewhale 沙箱，信任模式允许文件工具写入工作区以外的路径。除 danger-full-access 外的任何 --sandbox（或配置中对应的 sandbox_mode）都会保持信任模式关闭。加上 --sandbox workspace-write 可在可用时启用 shell 沙箱，并保留文件工具的工作区限制；external-sandbox 则依赖你自行提供的隔离。请把标志放在提示词前；提示词以 - 开头或包含需要按字面理解的 exec 标志时，应先加上 --。向模型提供工具的运行会在所有输出格式下保存。--output-format stream-json 每行输出一个 JSON 事件，也会保存仅作答的运行，以便之后用 --continue 接着运行。--max-turns 和 --allowed-tools 可以为一次运行设定限制。

启动 Runtime API

export CODEWHALE_RUNTIME_TOKEN="$(openssl rand -hex 32)"
codewhale app-server --http            # http://127.0.0.1:7878

请在启动前自己设置令牌；如果不设置，Codewhale 会为该进程生成一个令牌，但不会打印出来。每个 /v1/* 请求都必须以 Authorization: Bearer <token> 的形式携带它。--port 可以更改端口。

发送一个回合并观察它

API=http://127.0.0.1:7878
AUTH="Authorization: Bearer $CODEWHALE_RUNTIME_TOKEN"

THREAD=$(curl -s -X POST "$API/v1/threads" -H "$AUTH" \
  -H "Content-Type: application/json" -d '{}' | jq -r .id)

curl -s -X POST "$API/v1/threads/$THREAD/turns" -H "$AUTH" \
  -H "Content-Type: application/json" -d '{"prompt": "Summarize README.md"}'

curl -N "$API/v1/threads/$THREAD/events?since_seq=0" -H "$AUTH"

线程就是一段对话；回合是一次请求，以及 Codewhale 为它所做的一切。事件流会从你给出的序号开始回放，然后保持连接等待新事件，因此重新连接的客户端不会漏掉任何内容。

停止回合

POST /v1/threads/{id}/turns/{turn_id}/interrupt

回应审批

POST /v1/approvals/{approval_id}

引导正在运行的回合

POST /v1/threads/{id}/turns/{turn_id}/steer

列出已保存的会话

GET /v1/sessions

docs/RUNTIME_API.md 列出了所有路由、请求体和事件。

选择其他连接方式

codewhale app-server --stdio

通过标准输入输出传输 JSON-RPC，不监听网络。适合 SDK 或本地探测。

codewhale serve --acp

面向 Zed 等编辑器的 Agent Client Protocol。

codewhale serve --mcp

把 Codewhale 的工具提供给其他 MCP 客户端。见用 MCP 连接工具。

codewhale web

内置的浏览器客户端，基于同一个 API。

codewhale doctor --json

以 JSON 输出健康状况和能力信息，不含任何密钥。

保持私密

• 服务默认只监听 127.0.0.1。令牌只是本地防护，不能替代 TLS 或 VPN；不要把端口暴露到网络上。
• --insecure-no-auth 只在回环地址上被接受。
• API 从不返回你的提供商密钥。健康和能力报告只包含元数据——没有密钥、文件内容或消息。

下一步