作者注：OpenBot 没有“选模型”的界面，模型写在 .env 和租户包的 model.yaml 里。本文讲清怎样改三行环境变量加一行 yaml 接上 API易，先只放行 3 个电脑工具，再用一次“开网页 + 读文件 + 看审计”完成验收。
你把 CopilotKit 的 OpenBot 克隆下来，打开 .env.example，又在前端页面里来回找，始终没找到“选择模型供应商”的下拉框。你手上没有 OpenAI 官方卡，只想用 API易 按量计费去驱动 claude-opus-5-5，结果连模型配在哪都不知道。
先说结论：OpenBot 没有“选模型”的开关。模型写在 .env 和租户包的 model.yaml 里。接 API易 不需要改代码，改三行环境变量，再改一行 yaml 就够了。改完以后先只放行 3 个电脑工具，验收通过再按需放开。
这不是“一键跑通”的教程。OpenBot 本身是模板，跑起来需要 Docker、Bun 1.4+、一个 CopilotKit Intelligence 项目，外加一把模型 key。这些前置条件本文都会写清楚。另外，GitHub 上有两个叫 OpenBot 的项目，本文讲的是 CopilotKit 这个。
核心价值：读完本文，你能自己改对三处配置，用 3 个工具起步，跑一次可验收的“开网页 + 读文件 + 看审计”。遇到 400、401、模型不存在、工具不被调用、启动被拒这几类常见故障，也有一张排错表可以对照。
OpenBot 的模型不在界面里配
OpenBot 是模板，不是产品
CopilotKit/OpenBot 是 MIT 许可的开源仓库，2026-08-17 创建。到 2026-11-02，仓库有 9,561 个 star，最新正式 Release 是 v0.2.0（2026-10-12），README 顶部仍标着 Beta。它的口号是让每个 AI 同事（仓库里叫 Bot）拥有一台自己的电脑，包括真实浏览器、自己的登录态、自己的文件，以及被授予的那几个工具。
README 里写得很直白：这是“A template， not a product”。它没有托管版可以注册，也不作为依赖包发布。正确用法是把仓库克隆下来，把 examples/ 下的示例租户包换成你自己的同事、频道和技能，然后自己运行。所以“模型在哪选”这个问题，答案在配置文件里，不在界面上。
OpenBot 跑起来的四个前置
下面这张表列出了接模型之前必须先备好的东西。缺任何一项，后面的配置都无从验证。
| 前置项 | 具体要求 | 说明 |
|---|---|---|
| Docker | 跑 PostgreSQL（含 pgvector）和自带 Bot | scripts/start.sh 会拉起 Docker 服务并跑迁移 |
| Bun | 1.4 及以上 | 安装依赖用 bun install |
| CopilotKit Intelligence | 一个项目加 license，有免费计划 | 本地评估环境是 macOS + Docker Desktop，本地 licence 有效期 30 天，可用 npx copilotkit@latest local renew 续期 |
| 模型 key | 一把 OpenAI 兼容端点的 key | 本文用 API易 令牌，base_url 为 https://api.apiyi.com/v1 |
Intelligence 这一项最容易被低估。.env.example 的注释写明，缺少 Intelligence 的 URL、gateway URL 或 key 时，服务端会直接拒绝启动，原文是“There is no degraded mode.”。原因是持久线程和记忆都由它持有，没有它，每次对话都会丢失上下文。所以 OpenBot 不能被描述成“完全离线”的方案。
OPENAI_BASE_URL 改的是整个部署
README 的说法是“no model ships in the box”：模型不随包发布，凭据由管理员提供，加密后落库，不进日志。决定模型的是部署级环境变量。其中最关键的是 OPENAI_BASE_URL，官方定义它可以是任何说同一套 API 的端点，包括多供应商网关、代理，或者你自己硬件上跑的模型。.env.example 的注释写得更具体：任何支持 /v1/chat/completions 的端点都可以。
这个变量作用于整个部署，而不是单个 Bot。API server 给内置 agent 用的客户端、自己构造客户端的 agent-bot、BOT_PROVIDER=openai 的 agent-langgraph，三处都读它。官方认为这样做的好处是，同一个部署不会出现一半请求指向新地址、一半还留在旧地址的情况。
三处改动接上 API易：OpenBot 环境变量逐项配置
OpenBot 与 API易 的对接点
API易 提供 OpenAI 兼容接口，base_url 填 https://api.apiyi.com/v1,请求走 /v1/chat/completions，正好满足 OpenBot 对 OPENAI_BASE_URL 的要求。还有一点要注意：OpenBot 对模型名做原样传输（verbatim），API易 的 /v1/models 返回的是裸名 claude-opus-5-5，所以不要照着官方网关示例加 openai/ 前缀。官方示例里的 openai/gpt-5.6-terra 只适用于给模型名加了命名空间的端点。
先看一张总表，再按步骤操作。
| 改哪里 | 改成什么 | 为什么 |
|---|---|---|
.env 的 OPENAI_API_KEY |
你在 API易 控制台创建的 sk-... 令牌 |
内置 agent 和两个自带 Bot 默认都用这把 key |
.env 的 OPENAI_BASE_URL |
https://api.apiyi.com/v1 |
把整个部署的模型请求指向 API易 的兼容端点 |
.env 的 BOT_MODEL |
claude-opus-5-5 |
指定正在启动的 Bot 用哪个模型，不填则取 provider spec 文件里的行 |
examples/<你的包>/model.yaml 的 default_model |
claude-opus-5-5 |
示例包当前是 gpt-5.6-terra，不改会出现模型不存在 |
.env 的 BOT_RESPONSES_API |
保持 false |
Claude 在 API易 的 Responses 端点上会返回 400 |
第一步：准备一把专用令牌
- 在 API易 令牌页
api.apiyi.com/token新建一把 key，给它设置余额上限和有效期，用途写明“OpenBot 本机评估”。 - 本机先用 curl 发一次
GET https://api.apiyi.com/v1/models,请求头为Authorization: Bearer sk-...。
验收标准：返回 HTTP 200，列表里能找到 claude-opus-5-5。我们在 2026-11-02 实测这一步，拿到 259 个模型，claude-opus-5-5 和 claude-opus-5-5-thinking 都在其中。
单独开一把令牌，是为了把“这台机器专用”和“生产用”分开。模板阶段 Bot 会反复试错，有余额上限兜底，心里更踏实。
第二步：改 .env 三行
按官方快速开始，先执行 cp .env.example .env 和 bun install。接着依次运行 npx --yes copilotkit@latest login、npx --yes copilotkit@latest project select、bun scripts/setup-learning.ts，把 runtime key 和 Learning container 写进 .env。然后改下面三行：
OPENAI_API_KEY=sk-你的API易令牌OPENAI_BASE_URL=https://api.apiyi.com/v1BOT_MODEL=claude-opus-5-5
另外检查四项：BOT_PROVIDER 保持默认的 openai；BOT_RESPONSES_API 保持 false；KEY_ENCRYPTION_KEY 用 openssl rand -base64 32 生成；AGENT_BOT_MODEL 只给概念验证用的 agent-bot 使用，默认是 gpt-5.5，和 BOT_MODEL 互不影响。如果你也要启动 agent-bot，请到 /v1/models 里确认这个名字存在，或者把它也改成你要用的型号。
验收标准:grep OPENAI_ .env 输出的 key 和地址正确，地址末尾带 /v1，没有多余的斜杠或空格。如果容器内访问同一端点需要走不同路由，再用 OPENAI_CONTAINER_BASE_URL 覆盖。不过 API易 是公网地址，通常用不到这个变量。
第三步：改租户包 model.yaml 一行
打开 examples/fintech/model.yaml，或者你复制出来的租户包。当前内容是 model.provider: openai、model.credential_secret_ref: openai-api-key、model.default_model: gpt-5.6-terra。
- 把
default_model改为claude-opus-5-5。 provider保持openai。官方规定这里只接受openai或anthropic，走 API易 的 OpenAI 兼容端点就选openai。credential_secret_ref不要改成明文 key，它引用的是已存储的凭据。
验收标准：执行 bash scripts/start.sh 后，健康检查逐个通过，打开 http://localhost:3010 能看到 General Assistant 和 Knowledge 两个默认同事。
这里有一个坑必须提前说明。服务端启动时，本来会去问一次 OpenAI 或 Anthropic“这把 key 能不能调用 default_model”，不能调用就打印 model-unavailable 或 model-credential-rejected。但只要设置了 OPENAI_BASE_URL，这一步检查就会被跳过。所以接 API易 时，模型名写错不会在启动阶段报错，要等第一条消息发出才会暴露。启动成功只说明服务起来了，不代表模型配置正确。
关于版本：v0.2.0 与 main 分支的差别
这一点必须写清楚。main 分支 CHANGELOG 的 Unreleased 段里有一条变更：内置 Bot 的 openai/... 模型如果走的是“既不是 OpenAI、也不是 Azure”的 OPENAI_BASE_URL，会改为调用该端点的 /chat/completions，不再走 Responses API。官方给的理由是大多数 OpenAI 兼容端点只提供 Chat Completions。同一改动还新增了 COPILOTKIT_OPENAI_API=responses|chat，用于强制二选一。
这条变更还没有进入 v0.2.0 这个正式 tag。如果你检出的是 v0.2.0，内置 Bot 走第三方 base URL 时可能仍会去调 Responses。结合我们下面的实测，这很可能是 400 报错的来源。处理办法有两种：一是基于 main 分支评估，并清楚它仍在变动；二是等这条变更正式发版后再接入。
🚀 快速开始：在动 OpenBot 之前，建议先用 API易 apiyi.com 的令牌单独调通一次
/v1/chat/completions，带上一个函数定义，确认finish_reason返回tool_calls。接口这一侧确认没问题，后面排错时就只需要看 OpenBot 的配置。
先只放行 3 个工具：OpenBot 起步限权
为什么 OpenBot 不该一开始就全开
官方对工具数量的判断原文是：“A model picks the right tool reliably out of about ten， and unreliably out of thirty.” 也就是说，在十个左右的工具里模型能稳定选对，到了三十个就不可靠了。OpenBot 源码注册了十三个电脑类工具，再加上 MCP 目录里的工具，第一天就很容易超过这条线。
超过十二个工具的 Bot，每次运行只会拿到与当前消息匹配的 skill 所需的工具。但官方特别说明，这只是收窄可见范围，“It is not a boundary， and it never substitutes for one”。真正的边界有三样：按 Bot 在 Admin 里给的授予（grant）、AGENT_COMPUTER_POLICY 动作策略，以及审计行。还要注意，出厂启动默认是 deny: [] 加 allow: ["true"]，等于全部放行。
起步阶段的 3 个工具清单
| 工具名 | 作用 | 起步阶段 |
|---|---|---|
computer_navigate |
浏览器打开网址 | ✅ 放行 |
computer_snapshot |
获取页面快照 | ✅ 放行 |
computer_read_file |
读取工作区文件 | ✅ 放行 |
computer_click / computer_type / computer_key |
点击、输入、按键 | ⏸ 验收后按需放开 |
computer_write_file |
写文件 | ⏸ 验收后按需放开 |
computer_run_command |
执行 shell 命令 | ⛔ 明确拒绝 |
computer_run_command 必须单独挡住。在 Compose 下开启 COMPUTER_SEPARATE_WORKSPACES 后，每个 Bot 会在自己的文件夹里起 shell，但官方承认“Commands can still read other folders”。要做到真正隔离，需要 computers.mode: sandbox。起步阶段没有必要承担这个风险。
写 AGENT_COMPUTER_POLICY
策略是一段 JSON，规则用 CEL 表达式，可以读取 tool.name、page.host、file.path 等字段。起步可以这样写：
- 在
.env里写一行：AGENT_COMPUTER_POLICY={"mode":"enforce","deny":["tool.name == 'computer_run_command'"],"allow":["tool.name in ['computer_navigate','computer_snapshot','computer_read_file']"]} - 在 Admin 里给 General Assistant 授予这三个工具，不要多给。
- 重启服务。如果 JSON 格式错误，服务端会直接启动失败，这反而方便你发现问题。
这里有两条求值规则需要了解。第一，deny 先于 allow，所以即使以后 allow 写得宽了，shell 依然被挡住。第二，引擎是 fail closed 的：策略缺失或为空时什么都不允许；deny 写坏了按拒绝处理；allow 写坏了不算放行。原则就一句话：先关小，再按需放开。验收通过后，再逐个加入点击、输入或写文件，每次加完都去看审计。
OpenBot 接 API易 的验收与排错
一次可验收动作：开网页、读文件、看审计
按官方架构，一次工具调用的顺序是：解析目标，按当前策略评估，写一条审计行，然后才真正调用电脑；如果转发出去的动作失败，会再写第二条审计行。电脑本身不做策略判断，边界在 server 的 gateway。所以验收要同时覆盖“能做”和“被记录”两件事：
- 在
/workspace放一个notes.md，随便写两行内容。 - 对 General Assistant 说：打开某个公开网页，告诉我标题，再读
/workspace/notes.md的内容。 - 再对它说：运行
ls /。这条应该被拒绝，并且回复中能说出是哪条规则拦下的。 - 打开 Audit 页面，能看到 navigate、snapshot、read_file 的放行记录和 run_command 的拒绝记录。如需导出，可调用
GET /api/admin/audit-events?format=csv，单次最多 5,000 行。
模型这一侧的可用性，我们只在 API易 侧做过实测。2026-11-02，用 claude-opus-5-5 调用 /v1/chat/completions 并带上一个 read_file 函数定义，返回 HTTP 200，耗时 4.06 秒，finish_reason 为 tool_calls，参数是 {"path":"/workspace/notes.md"}，用量为 prompt 393 tokens、completion 55 tokens。加上 stream: true 后，同样返回 200，SSE 分块里能看到函数名和参数的增量输出，最后以 data: [DONE] 结束。这说明 API易 的 chat 端点能把 Claude 的工具调用按 OpenAI 格式返回，这正是“模型只决定调哪个函数、不负责执行”的 Agent 所需要的。
排错表：五类常见失败
| 现象 | 最可能原因 | 处理办法 |
|---|---|---|
400 field messages is required |
请求走到了 Responses 端点。我们实测 claude-opus-5-5 打 API易 的 /v1/responses 会返回这个错误 |
确认 BOT_RESPONSES_API=false；如果用的是 v0.2.0，内置 Bot 可能仍在调 Responses，可改用 main 分支并设置 COPILOTKIT_OPENAI_API=chat（仍属 Unreleased） |
| 401 | key 填错、过期，或令牌余额上限已用完 | 回到 API易 令牌页检查有效期和余额，用 curl 重新测试 /v1/models |
| 模型不存在 | default_model 还是 gpt-5.6-terra，或者名字前加了 openai/ |
两处都写裸名 claude-opus-5-5；由于启动检查被跳过，要发消息才能验证 |
| 工具没被调用 | 型号不支持工具调用、grant 没给，或策略把工具挡住了 | 官方原话是没有工具调用的 Bot 无法驱动电脑；先查审计里有没有拒绝记录 |
| 启动被拒 | 缺少 Intelligence 配置、策略 JSON 写错，或在 provider spec 里新增了供应商却没同步 PROVIDER_IDS |
补齐 Intelligence 三项；校验 JSON；接 API易 不需要新增供应商，保持 openai 即可 |
💡 排错建议：遇到报错时，先把同一个请求直接发给 API易 apiyi.com 的
/v1/chat/completions。如果直连成功、OpenBot 里失败，问题出在 OpenBot 的配置或版本；如果直连也失败，再检查令牌和型号。这样可以先把问题范围缩小一半。
OpenBot 跑 Claude 的成本参考
API易 采用按量计费，没有固定月费。claude-opus-5-5 在 2026-11-02 查到的价格如下，claude-opus-5-5-thinking 价格相同：
| 计费项 | 单价（每百万 tokens） |
|---|---|
| 输入 | $4 |
| 输出 | $20 |
| 缓存读 | $0.2 |
型号与价格以平台型号列表为准。拿我们那次带工具的实测请求来算，393 个输入 token 加 55 个输出 token，单次费用很小。但 Bot 一旦开始多轮浏览和读文件，上下文会快速增长，建议配合令牌余额上限一起使用。
常见问题
Q1:OpenBot 接 API易 需要改源码吗？
不需要。改 `.env` 里的 `OPENAI_API_KEY`、`OPENAI_BASE_URL`、`BOT_MODEL` 三行，再把租户包 `model.yaml` 的 `default_model` 改掉即可。只有新增一个全新的供应商类型时才需要改 provider spec 和 `PROVIDER_IDS`，而 API易 走的是 OpenAI 兼容接口，不属于这种情况。
Q2：为什么不用 openai/claude-opus-5-5 这种带前缀的写法？
OpenBot 对模型名原样传输，应该使用端点自己发布的写法。API易 apiyi.com 的 `/v1/models` 列出的是裸名 `claude-opus-5-5`，加上前缀反而找不到模型。
Q3：能不能打开 BOT_RESPONSES_API 来用 Responses API？
接 Claude 时不要打开。我们实测 `claude-opus-5-5` 打 API易 的 `/v1/responses` 会返回 400 `field messages is required`，换成 `gpt-5.4-mini` 则返回 200。官方也要求，只有端点真正实现了 Responses API 时才能打开这个开关。
Q4：你们把 OpenBot 整套跑通了吗？
没有。我们只验证了 API易 这一端：模型列表、带工具的 chat 调用、流式输出，以及 Responses 端点的报错。OpenBot 整套（Docker 加 Intelligence 项目）没有在写稿机器上跑过，文中涉及 OpenBot 内部行为的部分都依据官方仓库和文档。
Q5：按量计费的 key 怎么避免被 Bot 用超？
在 API易 apiyi.com 的令牌页给这把 key 设置余额上限和有效期，和生产用的 key 分开管理。再配合本文的 3 工具策略，Bot 能做的事情和能花的钱都有上限。
总结
OpenBot 接 API易 核心要点 Key Takeaways
- 模型不在界面里：写在
.env三行和租户包model.yaml一行。 - base_url 作用于全部署:
OPENAI_BASE_URL一改，三类 Bot 一起切换。 - 启动成功不代表模型正确：接网关后检查被跳过，发第一条消息才能验证。
- 版本要看清：改调
/chat/completions仍在 main 分支 Unreleased 中，尚未进入 v0.2.0。 - 起步只放 3 个工具:deny 先于 allow，shell 单独拒绝，先关小再放开。
- 用 API易 按量起步：专用令牌加余额上限，
claude-opus-5-5用裸名。
OpenBot 让人找不到模型配置，是因为它根本不在界面里。把这三处改对：.env 三行、model.yaml 一行、Responses 保持关闭，再用一份只放行 3 个工具的策略起步，整条链路就清晰了。验收时只看三件事：网页能打开、文件能读取、拒绝的动作在审计里有记录。
推荐先用 API易 apiyi.com 的专用令牌把 chat 加工具调用单独测通，再接入 OpenBot。这样即使出问题，也能很快判断是哪一侧的原因。
📚 参考资料
- CopilotKit/OpenBot 仓库:README、Requirements 与 Quick start
- 链接：
github.com/CopilotKit/OpenBot -
说明：模板定位、前置条件、v0.2.0 Release 信息
-
OpenBot 配置文档：模型环境变量、
model.yaml、启动校验 - 链接：
github.com/CopilotKit/OpenBot/blob/main/docs/configuration.md -
说明：
OPENAI_BASE_URL、BOT_MODEL、BOT_RESPONSES_API的原始定义 -
OpenBot 架构文档:gateway、策略与审计
- 链接：
github.com/CopilotKit/OpenBot/blob/main/docs/architecture.md -
说明：工具调用顺序、审计导出接口
-
API易 文档中心:OpenAI 兼容模式、函数调用、型号列表
- 链接：
docs.apiyi.com - 说明：base_url 写法、tools 格式、
claude-opus-5-5价格
作者: APIYI 技术团队
技术交流: 欢迎在 API易 官网 apiyi.com 联系我们，更多接入资料可访问 docs.apiyi.com 文档中心
