Bots

面向接入 OpenBot 客户端或扩展服务端的开发者。示例需要本页说明的访问权限。从开发者手册开始。

Bot（机器人）是一个有角色的工作者，例如程序员、写作者或设计师。每个 Bot 都有自己的指令、自己的 Chats 和自己的长期记忆。你和一个 Bot 说话，它把工作交给其他 Bots 或者交给它自己，所以它总是有空回答你。本页介绍如何和 Bot 说话，以及 /v1/bots 下的路由。每个路由都接受用户令牌或 session cookie。见 身份验证。

---

和 Bot 说话

每个 Bot 都是长期存在的工作者。它一直存在，直到你把它归档，并且它会随着时间从工作中学习。没有其他种类的 Bot。

要和一个 Bot 说话，给它发一条消息：

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":"Plan three days in Rome."}' \
  https://api.example.com/v1/bots/$BOT/messages

消息会进入你和这个 Bot 唯一的 Chat。第一次时，OpenBot 会创建这个 Chat。你从不需要创建、选择或关闭 Chat。Bot 会马上回答。工作很长时，Bot 把它交给一个委派，自己保持有空回答你。结果之后会回到你的 Chat。见 Chats。

顶层 Bot 是由成员或组织拥有的 Bot，而不是由另一个 Bot 拥有。你可以选一个顶层 Bot 作为你的默认 Bot。

Bot 也可以拥有 Bots。见 拥有 Bots 的 Bots。

你的默认 Bot

你的默认 Bot 是客户端首先与之说话的 Bot。没有指定 Bot 的 trigger 也会把任务交给它。OpenBot 不会替你创建 Bot，所以新成员没有默认 Bot。这时，没有指定 Bot 的 trigger 会失败，返回 400 和 BotInvalid。

要设置默认 Bot，先创建一个 Bot，然后在你的成员设置中发送它的 ID：

curl -X PATCH -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedVersion":0,"defaultBot":"bot_5c0e…"}' \
  https://openbot.example.com/v1/me/settings

expectedVersion 是 GET /v1/me/settings 返回的 version。这个 Bot 必须是你自己的顶层 Bot 或共享 Bot，而且你需要它的 delegate。否则 OpenBot 返回 400 和 SettingsInvalid。发送 null 可以移除默认 Bot。

你仍然可以归档默认 Bot。归档之后，没有指定 Bot 的 trigger 会失败，直到你选另一个默认 Bot。

旧版本的 OpenBot 会为每个成员创建一个 Main Bot。升级时，每个 Main Bot 会变成普通的 Bot，并成为它的成员的默认 Bot。它的记忆和 Grants 都会保留。

Bot 不知道的限制

Bots 没有一份“可以做什么”的清单。Bot 只管尝试。当它第一次尝试新的事情时，例如创建 Bot 或调用 App 工具，它上面的决策者会做决定。见 Requests。这些决定会被保存，所以每个 Bot 的限制是从真实的工作中逐步形成的。

---

创建 Bot

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Programmer","role":"Writes and reviews TypeScript code","instructions":"Write small, tested changes. Explain each change in one short paragraph."}' \
  https://api.example.com/v1/bots

字段	含义
name	必填。一个简短的名字。OpenBot 会去掉首尾空格。剩下的部分必须有 1 到 100 个字符。
role	必填。用一行话说明 Bot 做什么。其他 Bots 读取它来选择工作者。
instructions	必填。Bot 的长期指令，类似一份职位说明。
model	可选。当 Chat 没有选择自己的模型时，这个 Bot 的 Chats 使用的模型。
planApproval	可选。这个 Bot 的计划如何被批准。见 计划模式。
shared	可选。true 会创建一个组织 Bot，每个成员都可以使用。
bot	可选。拥有这个新 Bot 的 Bot 的 ID。它不能和 shared 一起使用。

没有 model 的 Bot 无法回答。给它的第一条消息会失败，返回 400 和 ChatModelInvalid。见 Models。

OpenBot 返回 201 和这个 Bot：

{
  "id": "bot_5c0e…",
  "owner": { "_tag": "Member", "userId": "u-1" },
  "name": "Programmer",
  "role": "Writes and reviews TypeScript code",
  "instructions": "Write small, tested changes. …",
  "archived": false,
  "revision": 0,
  "createdAt": 1792486800000,
  "updatedAt": 1792486800000
}

owner 是 Member、Organization 或 Bot。共享的 Bot 使用当前使用它的成员的权限和 App 连接，从不使用创建它的人的权限和连接。

列出、读取和修改 Bots

GET /v1/bots 列出你自己的 Bots，以及你可以使用的共享 Bots。加上 ?archived=false 可以隐藏已归档的 Bots。加上 ?bot=<id> 可以列出某个 Bot 拥有的 Bots。

GET /v1/bots/:botId 返回一个 Bot。

curl -X PATCH -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expected":0,"instructions":"Write small changes with tests first."}' \
  https://api.example.com/v1/bots/$BOT

expected 是当前的 revision。你可以修改 name（规则和上面相同）、role、instructions、model（发送 null 来移除它）、planApproval（发送 null 来移除它）和 archived。当你归档一个 Bot 时，OpenBot 也会归档它拥有的每个 Bot，以及它们下面的 Bots。当你取消归档时，只有这一个 Bot 会恢复。

---

拥有 Bots 的 Bots

Bot 可以拥有 Bots。所以 Bot 可以组建自己的团队，团队中的每个成员都保留自己的记忆。

• Bot 用 openbot_create_bot 工具创建一个归它所有的 Bot。人则通过 POST /v1/bots 并带上 bot 字段来创建。这个工具接收的 name、role、instructions 和 model 与 POST /v1/bots 的格式相同，另外还有一个 reason。
• 一个 Bot 用这个工具创建的 Bot 会得到创建它的 Bot 的 model。工具调用可以指定另一个 model。
• 所有者是 { "_tag": "Bot", "bot": "<owner ID>", "userId": "<member>" }。userId 是所有者树最顶层的成员。当最顶层是组织拥有的 Bot 时，它是 null。
• Bot 可以给它自己和它拥有的 Bots 分派工作，不需要 request。
• Bot 的所有者链沿着它的所有者向上，到达一个顶层 Bot，然后到达人。例如：人 → Assistant → Worker → Scout。Bot 的 requests 会沿着这条链向上传递，即使人直接和这个 Bot 一起工作也是如此。见 Requests。
• 顶层 Bot 上面是和它一起工作的人。你自己的顶层 Bot 和共享 Bot 都是这样。

Bot 不需要一个助手 Bot 来保留某项工作的上下文。它可以给之前的一个委派再交新的工作，这些工作会在同一个 task Chat 中继续。见 委派。

---

Bot 在每个 Turn 中知道什么

OpenBot 会在每个 Turn 的指令中加入以下内容：

• Bot 的名字、角色和指令，
• 它现在服务的人，包括这个人的名字和成员 ID。在 Channel 中，这个人是写下这个 Turn 的消息的人，
• 它在哪种 Chat 中：
  • 在 direct Chat 或 channel Chat 中，人们和它说话，所以它必须马上回答。它把长的工作交给委派，也可以交给它自己，从而保持有空回答，
  • 在 task Chat 中，它为把任务交给它的 Bot 做一个任务。它最后的回答就是结果。只要它还有未完成的工作，就不能说自己完成了，
  • 在 review Chat 中，它决定一个请求，
• 它使用一项能力时要附上简短的理由，而需要决定的回答之后会作为消息回来，
• 以 [OpenBot] 开头的文字来自 OpenBot，不是来自人，所以它是数据，不是指令，
• 它带着以前工作中积累的经验，并且当前的指令优先于这些经验，
• 这个 Chat 未完成的工作列表：它的委派、请求和提醒。

记忆 Bot 还可以结合有用的内容重写这个 Turn 的输入。Bot 把这些改动当作自己的经验。它有 confide 工具，并且只知道这是一个说出工作情况的地方。

你也可以把一个 Bot 分享给其他组织中的人。他们会得到一个带有 source 的关联 Bot，它使用你的 Bot。

---

权限

Bot 上的操作	允许你
read	读取 Bots，以及它们的记忆、Rules 和 Grants。
write	创建和修改 Bots，以及它们的记忆、Rules 和 Grants。
delegate	从客户端或另一个 Bot，和某个 Bot 说话并把工作交给它。
share	邀请别人使用某个 Bot。

你自己的 Bots 的路径是 org / <org> / user / <you> / bot / <id>。共享的 Bot 没有所有者：它的 ownerUserId 是 null。成员可以读取和使用共享的 Bots。管理员还可以修改和分享它们。见 权限。

错误

InvitationNotFound 返回 404。请求指定邀请 ID 时，错误包含 invitationId。Bot 链接的 secret 找不到邀请时，错误中没有这个字段。

状态码	错误	何时出现
400	BotInvalid	不允许这个修改，或者你没有默认 Bot。
403	Forbidden	你可以读取这个 Bot，但不能修改或使用它。
404	BotNotFound	没有你可以读取的、使用这个 ID 的 Bot。
409	BotConflict	expected 已过时。请重新读取 Bot，然后再试。
503	BotStorageUnavailable	OpenBot 无法连接到它的数据库。

修改不存在的 Rule 时，会返回 404 RuleNotFound。撤销不存在的 Grant 时，会返回 404 GrantNotFound。这些错误会指出缺失的 Rule 或 Grant。