作者注：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 文檔中心
