1. 從零跑通 OpenClaw 飛書機(jī)器人為什么個(gè)人開(kāi)發(fā)者總卡在 settings 這一步OpenClaw 是一個(gè)可以自托管的 AI 助手網(wǎng)關(guān)它能把你常用的聊天入口比如飛書和背后的大模型 API 串起來(lái)讓你在飛書里直接跟滿血 Claude 對(duì)話。適合誰(shuí)適合想低成本體驗(yàn) Claude、又不想折騰復(fù)雜網(wǎng)絡(luò)環(huán)境的個(gè)人開(kāi)發(fā)者。它的核心價(jià)值在于可視化配置、無(wú)需寫代碼、一條 settings 配置就能切換模型后端。但我在實(shí)際搭建時(shí)發(fā)現(xiàn)真正讓人卡住的不是部署而是 settings 文件里那幾個(gè)字段——Base URL 填錯(cuò)、Model ID 寫成了展示名、Key 沒(méi)帶前綴都會(huì)導(dǎo)致機(jī)器人上線后要么不回消息要么返回 401。這篇教程就按「部署 → 配置 settings → 接飛書 → 驗(yàn)證鏈路」的順序把每一步的可復(fù)制片段和排障點(diǎn)講清楚。你需要準(zhǔn)備的東西很簡(jiǎn)單一臺(tái)能正常上網(wǎng)的電腦、一個(gè)飛書賬號(hào)個(gè)人版就行不需要企業(yè)認(rèn)證、以及一個(gè)可用的模型 API 服務(wù)。整個(gè)流程走下來(lái)從部署到在飛書里收到第一條回復(fù)大概 20 分鐘。先說(shuō)清楚鏈路結(jié)構(gòu)這樣后面排障你才知道該看哪一環(huán)飛書用戶發(fā)消息 ↓ 飛書開(kāi)放平臺(tái)事件回調(diào) ↓ OpenClaw 服務(wù)接收事件 調(diào)用模型 ↓ 模型 APIBase URL Key Model ID ↓ 返回結(jié)果 → 飛書機(jī)器人回復(fù)四個(gè)環(huán)節(jié)任何一個(gè)斷了表現(xiàn)都是「機(jī)器人不回消息」。所以驗(yàn)證的時(shí)候要分段測(cè)先確認(rèn) OpenClaw 服務(wù)本身活著再確認(rèn)模型 API 能通最后確認(rèn)飛書回調(diào)地址填對(duì)了。我試過(guò)最省事的做法是先在 OpenClaw 的調(diào)試面板里發(fā)一條測(cè)試消息確認(rèn)模型能返回內(nèi)容再去飛書里發(fā)消息。這樣如果飛書那邊沒(méi)反應(yīng)你就知道問(wèn)題出在回調(diào)配置而不是模型接入。關(guān)于模型 API 的選擇個(gè)人開(kāi)發(fā)者最在意的是「便宜 穩(wěn)定 不用折騰網(wǎng)絡(luò)」。TaoToken 提供了兼容 OpenAI 格式的接口Base URL 是https://taotoken.net/api你拿到 Key 之后直接填進(jìn) settings 就能用。它的模型對(duì)話入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以先在網(wǎng)頁(yè)上試一下模型是否正常響應(yīng)再去配置 OpenClaw。這一節(jié)的核心結(jié)論搭建失敗 80% 不是部署問(wèn)題而是 settings 里的三個(gè)字段Base URL、API Key、Model ID沒(méi)對(duì)齊。下一節(jié)我們先把 TaoToken 的 Key 拿到手再進(jìn)入配置環(huán)節(jié)。2. TaoToken 前置準(zhǔn)備拿到 Key 并確認(rèn)滿血 Claude 可用在改 settings 之前你得先有一個(gè)能用的 API Key。這一步很多人跳過(guò)直接去填配置結(jié)果報(bào) 401 又回頭查浪費(fèi)時(shí)間。正確順序是先拿 Key → 先在網(wǎng)頁(yè)驗(yàn)證模型能通 → 再填進(jìn) OpenClaw。2.1 注冊(cè)并創(chuàng)建 API Key打開(kāi) TaoToken 官網(wǎng) https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注冊(cè)登錄后進(jìn)入控制臺(tái)?？刂婆_(tái)地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 在左側(cè)菜單找到「API Keys」或「令牌管理」點(diǎn)擊創(chuàng)建。創(chuàng)建時(shí)注意兩點(diǎn)一是給 Key 起個(gè)能認(rèn)出來(lái)的名字比如openclaw-feishu方便以后排查二是創(chuàng)建后立刻復(fù)制頁(yè)面刷新后就看不到了。Key 的格式通常是一串以sk-開(kāi)頭的字符串。如果你還沒(méi)決定用哪個(gè)模型可以先在模型對(duì)話頁(yè)面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 試一下 Claude 系列。選一個(gè)模型輸入「你好請(qǐng)用一句話介紹你自己」看是否正常返回。這一步能通說(shuō)明你的 Key 和賬戶狀態(tài)都沒(méi)問(wèn)題。2.2 確認(rèn) Base URL 和 Model ID這是最容易出錯(cuò)的地方。OpenClaw 的 settings 里需要填三個(gè)關(guān)鍵字段字段填什么常見(jiàn)錯(cuò)誤Base URLhttps://taotoken.net/api多寫/v1或少寫/apiAPI Key你復(fù)制的sk-開(kāi)頭字符串復(fù)制時(shí)帶了空格Model ID模型列表里的準(zhǔn)確 ID填成了展示名如「Claude 3.5」Base URL 這塊要特別注意TaoToken 的接口地址是https://taotoken.net/api不要自己加/v1也不要寫成https://taotoken.net/api/v1/chat/completions這種完整路徑——OpenClaw 會(huì)自己拼接。填錯(cuò)的表現(xiàn)通常是404或local proxy failed。Model ID 必須用接口里定義的準(zhǔn)確名稱不是網(wǎng)頁(yè)上顯示的中文名。你可以在模型對(duì)話頁(yè)面選中模型后看請(qǐng)求詳情里的model字段那個(gè)才是要填進(jìn) settings 的值。2.3 用 curl 先驗(yàn)證一次在填進(jìn) OpenClaw 之前建議先用命令行驗(yàn)證一次這樣能把「Key 問(wèn)題」和「OpenClaw 配置問(wèn)題」分開(kāi)curl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: 你的Model ID, messages: [{role: user, content: 你好}] }如果返回里有choices字段和正常內(nèi)容說(shuō)明 Key 和模型都沒(méi)問(wèn)題。如果返回401檢查 Key 是否復(fù)制完整如果返回model not found檢查 Model ID 拼寫。這一步過(guò)了再進(jìn)入 OpenClaw 配置你就能確定問(wèn)題不在 API 側(cè)。下一節(jié)給出完整的 settings 配置片段。3. 可復(fù)制 settings 配置OpenClaw 接入 TaoToken 的完整片段這一節(jié)是全文的核心。OpenClaw 的配置方式取決于你用的版本常見(jiàn)的有 JSON 和 TOML 兩種格式。下面給出兩種可復(fù)制片段你按自己的版本選一個(gè)。3.1 JSON 格式 settings 片段如果你用的是可視化面板或 JSON 配置文件找到模型/Provider 配置區(qū)域填入以下內(nèi)容{ providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, models: { claude-sonnet: { id: 你的Model ID, name: Claude Sonnet via TaoToken } } } }, defaultProvider: taotoken, defaultModel: claude-sonnet }注意baseUrl結(jié)尾不要帶斜杠apiKey不要帶引號(hào)外的空格。id字段填的是接口里的準(zhǔn)確 Model IDname是你自己看的別名可以隨便起。3.2 TOML 格式 settings 片段如果你的 OpenClaw 用 TOML 配置對(duì)應(yīng)寫法是[providers.taotoken] base_url https://taotoken.net/api api_key sk-你的Key [providers.taotoken.models.claude-sonnet] id 你的Model ID name Claude Sonnet via TaoToken [default] provider taotoken model claude-sonnetTOML 里字符串用雙引號(hào)鍵名用下劃線。改完保存后重啟 OpenClaw 服務(wù)讓配置生效。3.3 飛書回調(diào)地址填寫OpenClaw 啟動(dòng)后會(huì)在本地或服務(wù)器上監(jiān)聽(tīng)一個(gè)端口比如http://你的IP:3000。飛書開(kāi)放平臺(tái)需要填兩個(gè)地址事件訂閱地址http://你的IP:3000/feishu/event消息回調(diào)地址http://你的IP:3000/feishu/callback具體路徑以 OpenClaw 文檔為準(zhǔn)但格式都是「你的服務(wù)地址 固定路徑」。填完后飛書會(huì)發(fā)一個(gè)驗(yàn)證請(qǐng)求OpenClaw 需要能正確響應(yīng) challenge否則會(huì)提示「回調(diào)地址驗(yàn)證失敗」。如果你在本地跑飛書無(wú)法直接訪問(wèn)你的localhost需要用內(nèi)網(wǎng)穿透工具把本地端口暴露出去。這一步不做飛書事件永遠(yuǎn)到不了 OpenClaw。3.4 飛書權(quán)限配置在飛書開(kāi)放平臺(tái)創(chuàng)建自建應(yīng)用后需要開(kāi)通機(jī)器人能力和事件權(quán)限。把以下權(quán)限 JSON 粘貼到權(quán)限配置里{ scopes: { tenant: [ im:message, im:message.group_at_msg:readonly, im:message.p2p_msg:readonly, im:message:readonly, im:message:send_as_bot, im:resource, im:chat.access_event.bot_p2p_chat:read ], user: [ im:chat.access_event.bot_p2p_chat:read ] } }粘貼后確認(rèn)然后一定要點(diǎn)「應(yīng)用」——很多人忘了這步權(quán)限沒(méi)生效機(jī)器人收不到消息。接著在「事件訂閱」里添加im.message.receive_v1事件這是接收用戶消息的關(guān)鍵事件。最后發(fā)布應(yīng)用版本等內(nèi)容審核通過(guò)個(gè)人版通常很快。配置完成后回到 OpenClaw 控制臺(tái)把飛書應(yīng)用的 App ID 和 App Secret 填進(jìn)去保存并重啟服務(wù)。下一節(jié)我們驗(yàn)證整條鏈路。4. 驗(yàn)證請(qǐng)求與成功結(jié)果一條測(cè)試消息跑通全鏈路配置填完不代表能跑通必須實(shí)際發(fā)一條消息驗(yàn)證。這一節(jié)給出分段驗(yàn)證方法讓你能定位問(wèn)題出在哪一環(huán)。4.1 先驗(yàn)證 OpenClaw 服務(wù)本身在服務(wù)器或本地終端執(zhí)行curl http://localhost:3000/health如果返回{status:ok}或類似內(nèi)容說(shuō)明 OpenClaw 服務(wù)活著。如果連接被拒絕檢查服務(wù)是否啟動(dòng)、端口是否被占用。4.2 再驗(yàn)證模型調(diào)用在 OpenClaw 的調(diào)試面板或日志里找一條模型調(diào)用記錄。如果日志里出現(xiàn)choices字段和正?；貜?fù)說(shuō)明模型接入沒(méi)問(wèn)題。如果出現(xiàn)401回到第 2 節(jié)檢查 Key如果出現(xiàn)local proxy failed檢查 Base URL 是否寫成了https://taotoken.net/api。4.3 最后在飛書里發(fā)消息打開(kāi)飛書在搜索框里搜你的機(jī)器人名稱點(diǎn)進(jìn)去發(fā)一條「你好」。正常情況幾秒內(nèi)會(huì)收到回復(fù)。如果沒(méi)反應(yīng)按以下順序排查第一看飛書開(kāi)放平臺(tái)的事件訂閱日志確認(rèn)事件有沒(méi)有推送到你的回調(diào)地址。如果日志里顯示「推送失敗」說(shuō)明回調(diào)地址填錯(cuò)了或服務(wù)不可達(dá)。第二看 OpenClaw 日志有沒(méi)有收到事件。如果飛書顯示推送成功但 OpenClaw 沒(méi)日志檢查回調(diào)路徑是否匹配。第三看 OpenClaw 有沒(méi)有調(diào)用模型。如果收到事件但沒(méi)調(diào)模型檢查默認(rèn) Provider 和 Model 是否配置正確。4.4 成功結(jié)果長(zhǎng)什么樣鏈路跑通后你在飛書里發(fā)「你好」機(jī)器人會(huì)回復(fù)一段 Claude 生成的內(nèi)容。同時(shí) OpenClaw 日志里會(huì)看到類似這樣的記錄[feishu] received message from user [model] calling taotoken/claude-sonnet [model] response received, 128 tokens [feishu] reply sent看到這四行說(shuō)明整條鏈路通了。如果只有前兩行沒(méi)有第三行問(wèn)題在模型調(diào)用如果只有前三行沒(méi)有第四行問(wèn)題在飛書回復(fù)權(quán)限。驗(yàn)證通過(guò)后你可以試著發(fā)一條復(fù)雜一點(diǎn)的消息比如「幫我寫一個(gè) Python 快速排序」看 Claude 是否能正常生成代碼。這一步能過(guò)說(shuō)明滿血 Claude 已經(jīng)通過(guò) TaoToken 接入成功。5. 本篇常見(jiàn)錯(cuò)排查401、local proxy failed、reading choices、OAuth搭建過(guò)程中最容易遇到四類報(bào)錯(cuò)這一節(jié)逐個(gè)給出原因和修復(fù)方法。5.1 401 Unauthorized報(bào)錯(cuò)原文通常是{error:{message:Invalid API key,type:invalid_request_error}}原因Key 填錯(cuò)、Key 過(guò)期、或 Key 前面多了空格。修復(fù)回到 TaoToken 控制臺(tái) https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 重新復(fù)制 Key粘貼時(shí)注意不要帶首尾空格。如果 Key 是在環(huán)境變量里檢查有沒(méi)有被 shell 轉(zhuǎn)義。5.2 local proxy failed報(bào)錯(cuò)原文local proxy failed: dial tcp: connection refused原因Base URL 填錯(cuò)或者 OpenClaw 無(wú)法訪問(wèn)該地址。修復(fù)確認(rèn) Base URL 是https://taotoken.net/api不要加/v1。如果你在服務(wù)器上跑確認(rèn)服務(wù)器能正常訪問(wèn)外網(wǎng)。5.3 reading choices 相關(guān)報(bào)錯(cuò)報(bào)錯(cuò)原文error reading choices: unexpected end of JSON input原因模型返回的不是標(biāo)準(zhǔn) OpenAI 格式通常是 Base URL 指向了錯(cuò)誤的端點(diǎn)或者 Model ID 不存在導(dǎo)致返回了錯(cuò)誤頁(yè)。修復(fù)用第 2.3 節(jié)的 curl 命令直接測(cè)一次確認(rèn)返回里有choices字段。如果沒(méi)有檢查 Model ID 是否準(zhǔn)確。5.4 OAuth 相關(guān)報(bào)錯(cuò)報(bào)錯(cuò)原文oauth token exchange failed原因飛書應(yīng)用的 App ID 或 App Secret 填錯(cuò)或者應(yīng)用沒(méi)發(fā)布。修復(fù)回到飛書開(kāi)放平臺(tái)確認(rèn)應(yīng)用已發(fā)布且權(quán)限已應(yīng)用。App Secret 只在創(chuàng)建時(shí)顯示一次如果忘了需要重置。5.5 三件套檢查清單無(wú)論遇到哪種報(bào)錯(cuò)先檢查這三件套是否齊全檢查項(xiàng)正確值在哪看Base URLhttps://taotoken.net/apisettings 配置API Keysk-開(kāi)頭完整字符串TaoToken 控制臺(tái)Model ID接口里的準(zhǔn)確 ID模型對(duì)話頁(yè)面請(qǐng)求詳情這三項(xiàng)對(duì)齊了90% 的報(bào)錯(cuò)都會(huì)消失。如果還不行去接入文檔 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 對(duì)照最新配置格式。6. 長(zhǎng)期使用建議把 OpenClaw 飛書機(jī)器人跑穩(wěn)的幾個(gè)實(shí)用技巧鏈路跑通只是開(kāi)始長(zhǎng)期用起來(lái)還有幾個(gè)坑要提前避開(kāi)。第一Key 不要硬編碼在配置文件里。如果你把 settings 提交到 GitKey 就泄露了。建議用環(huán)境變量在 settings 里寫apiKey: ${TAOTOKEN_API_KEY}然后在啟動(dòng)腳本里 export。這樣配置可以安全分享。第二飛書事件回調(diào)有重試機(jī)制。如果 OpenClaw 處理慢飛書會(huì)重復(fù)推送同一條消息導(dǎo)致機(jī)器人重復(fù)回復(fù)。建議在 OpenClaw 里開(kāi)啟消息去重按message_id過(guò)濾。第三模型選擇上日常對(duì)話用輕量模型復(fù)雜任務(wù)再切 Claude。你可以在 settings 里配多個(gè)模型通過(guò)飛書指令切換。這樣成本更可控。第四定期看 OpenClaw 日志里的 token 消耗。如果發(fā)現(xiàn)某類消息消耗異常高可能是 prompt 里帶了太多上下文。適當(dāng)精簡(jiǎn)系統(tǒng)提示詞能省不少。第五如果你要長(zhǎng)期跑 coding 類任務(wù)可以考慮 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它針對(duì)代碼場(chǎng)景做了優(yōu)化配合 OpenClaw 的 Agent 模式能處理更復(fù)雜的多步任務(wù)。最后說(shuō)一個(gè)我踩過(guò)的坑OpenClaw 升級(jí)后 settings 格式可能變升級(jí)前先備份配置文件。有一次我直接升級(jí)結(jié)果providers字段結(jié)構(gòu)變了服務(wù)起不來(lái)回滾才恢復(fù)?，F(xiàn)在我的習(xí)慣是改配置前先cp settings.json settings.json.bak出問(wèn)題一分鐘回滾。整套流程走下來(lái)你會(huì)發(fā)現(xiàn)最花時(shí)間的不是部署而是對(duì)齊三個(gè)字段和飛書權(quán)限。把這兩塊搞定剩下的就是享受在飛書里跟滿血 Claude 對(duì)話的體驗(yàn)了。