本地脚本 API¶

运行 OpenBot 的计算机上的脚本可以向 agent 发送消息、等待其回答、运行 routine、读取待处理的问题和审批、提交响应、更改 agent 的模型或提供商账户，以及与 agent 开始新的聊天。为集成所需的每个 agent 启用 Local scripts。使用此 API 可以实现本地 Slack 桥接、报告构建结果，或从终端向 agent 分配任务。

long-job; curl -sS -X POST "$(cat "$OPENBOT_AUTOMATION/url")/v1/agents/<agentId>/routines/<routineId>/run" \
  -H @"$OPENBOT_AUTOMATION/headers" \
  -H 'Content-Type: application/json' \
  -d '{"payload":"long-job ended with code 0"}'

$OPENBOT_AUTOMATION 并非由 OpenBot 设置；它代表下面这个文件夹。

命令行¶

openbot-cli 使用此 API，因此您无需自己编写请求。它需要 Node 18 或更高版本。OpenBot 将其放在资源文件夹中：

• macOS: /Applications/OpenBot.app/Contents/Resources/cli/openbot-cli.mjs
• Linux: resources/cli/openbot-cli.mjs in the install folder (for an AppImage, copy it out of the image)
• Windows: resources\cli\openbot-cli.mjs in the install folder. The default folder is %LOCALAPPDATA%\Programs\OpenBot.

alias openbot-cli='node "/Applications/OpenBot.app/Contents/Resources/cli/openbot-cli.mjs"'
openbot-cli list                                    # the agents with Local scripts on
openbot-cli run "Ada" "Run the tests and tell me what failed" --wait
openbot-cli run "Ada" - --wait --json < task.md     # the task from standard input, one JSON answer
openbot-cli status "Ada" <deliveryId>               # a delivery that an earlier run left
openbot-cli agent set-account "Ada" <accountId>     # or "default" for the provider's own sign-in
openbot-cli agent set-model "Ada" claude-opus-5-5 --effort high
openbot-cli agent new-chat "Ada"                    # the agent forgets the chat; its setup stays

<agent> 是 agent ID 或名称；不区分大小写。没有 --wait 时，run 会在消息进入队列后返回。使用 --wait 时，它会在轮次结束时打印该轮次的回答。--timeout（90s、5m、2h；默认 30m）只停止等待，不停止工作。--id <key> 是消息的重试键（参见 POST /v1/agents/:agentId/messages）；没有它时，每次运行都会发送一条新消息。使用 --json 时，输出是一个 JSON 对象，失败时也是如此（{ "ok": false, "exitCode", "error" }）。

该命令每次运行时都会读取下面的文件，并且只在请求头中发送 token。当 OpenBot 在等待期间重启时，命令会读取新文件并继续等待。设置 OPENBOT_AUTOMATION_DIR 以使用另一个文件夹，例如某个开发 profile 的文件夹。

启用¶

该设置按 agent 分别生效，默认关闭。打开 agent 的设置，选择 Permissions，然后开启 Local scripts。当主机支持 agent-host-settings-v1 时，所有者或管理员也可以从已连接的桌面、web 或 iPhone 客户端更改此设置。agent 不能为自己或队友开启它。

对于无头（headless）主机，请以其所有者或管理员身份连接，并在那里开启该设置。监听器和下面介绍的文件位于该主机上。在该主机上，以运行 OpenBot 的 OS 用户身份运行脚本。无需本地屏幕。关闭同一设置即可移除该 agent 的访问权限。

该设置还允许脚本回答问题以及接受或拒绝审批。浏览器接管和密保问题必须在 OpenBot 中完成。已经启用 Local scripts 的 agent 在升级后即可获得这些操作，无需重新选择加入。较旧的客户端仍然可以更改此设置，尽管它们的界面文本只能描述 routines。

在主机的本地桌面窗口中，当该设置开启时，agent 的每条 routine 都带有 Copy run command。它在 macOS 和 Linux 上复制 curl 命令，在 Windows 上复制 PowerShell 命令。agent 也会学习该命令，因此它可以在后台启动一条耗时较长的命令，并在命令结束时请求被唤醒。

文件¶

当至少一个 agent 允许本地脚本时，OpenBot 会在一个空闲端口上监听 127.0.0.1，并在 <userData>/automation/ 中写入三个文件：

文件夹权限为 0700，文件权限为 0600，因此只有同一 OS 用户才能读取。OpenBot 在每次启动时都会生成新的 token 和新的端口。命令在运行时才会读取这些文件，因此您在重启前复制的命令仍然有效。当最后一个 agent 关闭该设置，或 OpenBot 退出时，OpenBot 会停止监听并删除这些文件。

<userData> 是 OpenBot 应用程序数据文件夹：

• macOS: ~/Library/Application Support/OpenBot
• Linux: ~/.config/OpenBot
• Windows: %APPDATA%\OpenBot

路由¶

每个请求都需要 Authorization: Bearer <token>。

GET /v1/agents¶

允许本地脚本的 agent 及其 routines：

[{ "id": "agent-1", "name": "Ada", "routines": [{ "id": "routine-1", "name": "Wake", "active": false }] }]

POST /v1/agents/:agentId/routines/:routineId/run¶

请求体：{ "payload"?: string, "waitId"?: string }，并包含 Content-Type: application/json。运行的启动方式与 Test run 相同，对于已暂停的 routine 也是如此。payload 位于 routine 指令之后、标题 --- event from a local script --- 下方，并附有一行文字，告诉 agent 将其作为数据而非指令来读取。运行历史会保留它，因此被重启中断的运行会再次发送它。

一个代理可以停止请求并等待事件：它通过 openbot.await_event 打开一个等待，并将等待 ID 提供给用户。没有 waitId 的运行会唤醒该代理所有没有例程或具有此例程的打开等待。带有 waitId 的运行只唤醒该等待。如果没有这样的等待处于打开状态，运行将直接开始而不等待。运行的输入会重复请求和代理的备注，因此代理可以继续处理该请求。

答复：202 { "runId": string, "deliveryId": string | null }。

202 表示运行已进入队列，并不表示已经执行。当代理的提供商账户达到使用限制时，运行会连同其负载一起在队列中等待，并在重置后开始。设置为在限制时跳过的例程会改为丢弃该运行，其运行历史会显示为已取消。

一个代理最多可以有 20 个打开的等待。openbot.list_waits 会显示代理打开的等待及其 ID，openbot.close_wait 按 ID 关闭一个等待。与例程工具一样，使用 agentId 时，这两个工具会作用于另一个本地代理的等待。openbot.list_agents 会为每个有打开等待的代理显示 openWaits。

POST /v1/agents/:agentId/messages¶

发送 { "text": "Ask me which build to run", "clientMessageId": "bridge-message-123" }，并设置 Content-Type: application/json。该消息使用普通对话队列。响应为 202 { "messageId": string, "deliveries": [{ "id": string, "recipientAgentId": string, "status": string, "position": number | null }] }。

重试同一消息时，请保持 clientMessageId（1–128 个字符）不变。普通队列会在 24 小时内返回该代理和该键的第一份回执，重启后依然如此。新的工作请使用新的键。此路由不支持附件。

GET /v1/agents/:agentId/deliveries/:deliveryId¶

一条消息投递给该代理的状态。使用消息回执中的投递 ID。

{ "id": "delivery-1", "status": "completed", "turnId": "turn-1", "error": null, "answer": "The tests pass." }

status 为 queued、starting、running、completed、failed、interrupted 或 cancelled。answer 是代理在该轮次中的最后回答。在投递结束前以及代理未给出回答时，它为 null。投递给其他代理或已不存在的投递会返回 404。此读取不计入请求限制。

POST /v1/agents/:agentId/settings¶

发送以下一个或多个字段：{ "provider": "claude", "model": "claude-opus-5-5", "reasoningEffort": "high", "providerAccountId": "default" }，并设置 Content-Type: application/json。这等同于代理设置中的模型和账户控件。providerAccountId 是设置 > 提供商中的账户 ID，default 表示提供商自己的登录账户，或为 null。不带 provider 的 model 会使用列出该模型的提供商；不带 model 的 provider 会使用该提供商的默认模型。当新模型不支持代理当前的推理强度时，该强度会变为模型的默认值。提供商未列出的模型或强度会返回 409 及有效值。更改提供商或账户会等待代理空闲：如果代理正在工作，则返回 409 并附原因。成功响应为 200，包含 id、name、provider、model、reasoningEffort 和 providerAccountId。其他字段（如名称、权限或本地脚本）会返回 400：请在 OpenBot 中更改。

POST /v1/agents/:agentId/context/clear¶

无请求体。这等同于代理设置中的新聊天：代理会忘记对话，其下一轮次会开始新的提供商会话。消息仍显示在分隔线上方，而指令、模型、工具、记忆、工作区和浏览器不会改变。在开始新任务前用它为代理提供全新上下文，这样长对话就不会随每次调用再次发送。成功响应为 200 { "ok": true }。当代理正在工作或队列中有消息时，返回 409 并附原因；请等待后重试。此请求不计入请求限制。

GET /v1/agents/:agentId/pending¶

轮询此路由以获取需要人工处理的请求。不会返回对话历史或浏览器内容。响应包含三个数组：

{
  "prompts": [{
    "requestId": "opaque-request-id",
    "requiresOpenBot": false,
    "questions": [{ "id": "build", "header": "Build", "question": "Which build?",
      "options": [{ "label": "Debug", "description": "Use debug settings" }] }]
  }],
  "approvals": [],
  "browserTakeovers": []
}

审批包含 requestId、agentId、threadId、turnId、kind、command、cwd、reason、grantRoot 和 permissions。在接受之前，请向操作人员展示完整详细信息。文本已对机密内容进行脱敏。浏览器接管只包含 requestId 和 requiresOpenBot: true。机密问题，或 ID 或选项标签需要脱敏的问题，其 requiresOpenBot 为 true 且 questions 数组为空。对于这些请求，请引导操作人员在 OpenBot 中联系对应代理。

请求 ID 是不透明的。请保持其不变。它们标识一个待处理请求，并在该请求结束时过期，即使提供商复用了自己的 ID 也是如此。主机重启后它们不会保留。

POST /v1/agents/:agentId/prompts/:requestId/answer¶

发送 { "answers": { "build": ["Debug"] } }，并设置 Content-Type: application/json。使用问题 ID 作为键，回答字符串作为数组值。普通问题处理器会恢复代理。成功响应为 200 { "ok": true }。

POST /v1/agents/:agentId/approvals/:requestId/respond¶

发送 { "decision": "accept" } 或 { "decision": "decline" }，并带有 Content-Type: application/json。成功响应为 200 { "ok": true }。这两个选项都不会更改 agent 已保存的权限设置。

agent 仍然必须允许 Local scripts 才能进行每次读取和响应。无法通过此 API 回答针对其他 agent 的请求、已过期的请求或秘密问题。已过期的请求返回 409；请刷新待处理列表，而不是重试旧的响应。

所有请求正文的大小限制为 32 KiB。消息和例程运行共享每个 agent 每小时 30 个已接受请求的限制，包括消息重试。读取、注意力响应、设置更改和新聊天不占用该限制。例程运行没有重试键；重试一次运行可能会使其启动两次。

Windows¶

Invoke-RestMethod -Method Post `
  -Uri ((Get-Content -Raw "$env:APPDATA\OpenBot\automation\url").Trim() + '/v1/agents/<agentId>/routines/<routineId>/run') `
  -Headers @{ Authorization = 'Bearer ' + (Get-Content -Raw "$env:APPDATA\OpenBot\automation\token").Trim() } `
  -ContentType 'application/json' -Body '{"payload":"long-job ended"}'

安全¶

• 监听器仅绑定 127.0.0.1。其他计算机无法访问它。
• 带有 Origin 头或 Host 不是 127.0.0.1:<port> 的请求会在 OpenBot 读取 token 之前收到 403。网页无法通过 DNS 重绑定来使用它。
• token 是一个机密：OpenBot 会从日志中将其遮蔽，并且绝不会将其放入 prompt 中。agent 只能获得文件路径。
• 不要将 token 放在命令的参数中，例如使用 -H "Authorization: Bearer $(cat token)"。在 Linux 上，其他用户可以读取正在运行的进程的参数。请使用 -H @headers。
• OpenBot 会记录每次运行的 agent 和例程，但绝不会记录 payload。
• 以相同 OS 用户身份运行的进程可以读取 token。仅针对你希望此类进程能够向其发送消息并进行控制的 agent 开启此设置，包括批准决策、agent 的模型和提供商账户以及新聊天。脚本无法更改 agent 的权限或开启 Local scripts。