1. 從零搭 OpenClaw Agent為什么 SOUL.md 和 openclaw.json 是繞不開(kāi)的兩塊地基如果你剛接觸 OpenClaw大概率會(huì)被它的文件結(jié)構(gòu)勸退workspace 里一堆 md根目錄一個(gè) openclaw.json還有 shared 協(xié)作目錄。我一開(kāi)始也懵直到把兩個(gè)文件的關(guān)系想明白——SOUL.md 決定「這個(gè) Agent 是誰(shuí)」openclaw.json 決定「這個(gè) Agent 怎么被系統(tǒng)拉起來(lái)、用哪個(gè)模型、監(jiān)聽(tīng)哪個(gè)頻道」。前者是靈魂后者是接線圖。這篇教程面向的是完全沒(méi)搭過(guò) OpenClaw 的新手目標(biāo)很明確從寫(xiě)第一份 SOUL.md 開(kāi)始到 openclaw.json 里把 Agent 注冊(cè)進(jìn)去最后用一條命令驗(yàn)證它能正常回話。中間會(huì)給出可以直接復(fù)制的配置片段也會(huì)說(shuō)明模型調(diào)用憑證怎么通過(guò)統(tǒng)一 Key/API 通道管理避免每個(gè) Agent 各配一套密鑰。先說(shuō)清楚 OpenClaw 是什么。它是一個(gè)多 Agent 運(yùn)行框架你可以把它理解成一個(gè)「Agent 公司」的操作系統(tǒng)每個(gè) Agent 有自己的工作區(qū)、人格定義、工具清單和心跳任務(wù)框架負(fù)責(zé)調(diào)度它們、傳遞消息、管理生命周期。適合誰(shuí)適合想把「調(diào)研—寫(xiě)作—發(fā)布—?dú)w檔」這類(lèi)流程拆成多個(gè)專職角色、又不想自己從零寫(xiě)調(diào)度邏輯的人。它不替代編輯器也不替代你思考業(yè)務(wù)拆分它只是把你拆好的角色跑起來(lái)。新手最容易踩的坑是把所有東西塞進(jìn)一個(gè) Agent。我試過(guò)用一個(gè) Agent 同時(shí)干調(diào)研、寫(xiě)稿、發(fā)推、歸檔結(jié)果問(wèn)它「上次那個(gè)選題結(jié)論是什么」它完全不記得同一篇選題調(diào)研三遍每遍都像第一次。這不是模型不行是一個(gè)腦子裝不下這么多角色。所以搭建的第一步不是寫(xiě)配置是想清楚你要幾個(gè) Agent、每個(gè) Agent 只干哪一件事。想清楚之后SOUL.md 和 openclaw.json 才有東西可寫(xiě)。下面按「先寫(xiě)靈魂、再寫(xiě)接線、再驗(yàn)證」的順序走。每一步都給可復(fù)制的片段你照著改名字和路徑就能用。2. 前置準(zhǔn)備TaoToken 統(tǒng)一 Key 通道與 OpenClaw 環(huán)境就位在寫(xiě) SOUL.md 之前先把模型調(diào)用這條鏈路打通。OpenClaw 本身不提供模型它需要你給它一個(gè)能調(diào)用的 API 端點(diǎn)。新手常見(jiàn)做法是每個(gè) Agent 單獨(dú)填一套密鑰結(jié)果是密鑰散落在十幾個(gè)文件里換一次 Key 要改一遍全局。更省事的做法是用統(tǒng)一 Key/API 通道所有 Agent 共用一套憑證只改一個(gè)地方。我用的通道是 TaoToken官網(wǎng)入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端點(diǎn)是 https://taotoken.net/api 。它的作用是把你對(duì)多個(gè)模型的調(diào)用收斂到一個(gè) Base URL 和一把 Key 上OpenClaw 里所有 Agent 都指向這個(gè)端點(diǎn)模型 ID 按需切換。這樣你新增一個(gè) Agent 時(shí)不用再去申請(qǐng)新密鑰復(fù)制同一套配置改個(gè)模型名就行。具體要準(zhǔn)備三樣?xùn)|西我把它叫「三件套」Base URL、API Key、Model ID。Base URL 填 https://taotoken.net/api API Key 在控制臺(tái)的 API Keys 頁(yè)面創(chuàng)建Model ID 按你要用的模型填比如 claude-sonnet 這類(lèi)。這三樣在后面的 openclaw.json 里會(huì)集中出現(xiàn)先記下來(lái)。環(huán)境方面你需要一臺(tái)能跑 Node 或 Python 的機(jī)器OpenClaw 的安裝按官方文檔走即可。裝完之后確認(rèn)兩件事一是 openclaw 命令能執(zhí)行二是 workspace 目錄存在。workspace 是每個(gè) Agent 的工作區(qū)根目錄SOUL.md、AGENTS.md、MEMORY.md 這些文件都放在各自的子目錄里。目錄結(jié)構(gòu)大概長(zhǎng)這樣openclaw/ ├── openclaw.json ├── workspace/ │ ├── main/ │ │ ├── SOUL.md │ │ ├── AGENTS.md │ │ ├── IDENTITY.md │ │ ├── TOOLS.md │ │ ├── HEARTBEAT.md │ │ └── MEMORY.md │ └── research/ │ └── ...同上 └── shared/ └── inbox/main 是總經(jīng)理角色負(fù)責(zé)全局調(diào)度research 是情報(bào)角色負(fù)責(zé)調(diào)研。新手先搭兩個(gè)就夠跑通了再加。別一上來(lái)就十個(gè)十個(gè) Agent 互相不知道對(duì)方在干什么比一個(gè) Agent 還亂。Key 的管理建議單獨(dú)放一個(gè)環(huán)境變量文件不要硬編碼進(jìn) openclaw.json。比如在項(xiàng)目根目錄建一個(gè) .envTAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_API_KEY你的Key然后在 openclaw.json 里用 ${TAOTOKEN_API_KEY} 這種占位引用。這樣密鑰不進(jìn)版本庫(kù)換 Key 也只改一處。控制臺(tái)創(chuàng)建 Key 的入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Keys 管理頁(yè)在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。先把 Key 建好后面配置直接填。3. 可復(fù)制配置SOUL.md 人格定義與 openclaw.json 接線片段這一節(jié)是核心分兩塊先寫(xiě) SOUL.md再寫(xiě) openclaw.json。SOUL.md 決定 Agent 的人格和邊界openclaw.json 決定它怎么被系統(tǒng)加載。3.1 SOUL.md 寫(xiě)什么SOUL.md 是 Agent 的靈魂文件回答四個(gè)問(wèn)題它是誰(shuí)、它信什么、它能干什么、它不能干什么。新手寫(xiě)這個(gè)文件最容易寫(xiě)成空泛的「你是一個(gè)樂(lè)于助人的助手」這種寫(xiě)法等于沒(méi)寫(xiě)。有效的 SOUL.md 要有具體的職責(zé)邊界和拒絕規(guī)則。以 research 這個(gè)情報(bào) Agent 為例一份可用的 SOUL.md 長(zhǎng)這樣# SOUL ## 身份 你是情報(bào)部調(diào)研員代號(hào) scout。你只負(fù)責(zé)信息采集與初步整理不負(fù)責(zé)寫(xiě)作、發(fā)布、歸檔。 ## 信念 - 結(jié)論必須有來(lái)源沒(méi)有來(lái)源的結(jié)論標(biāo)注「待驗(yàn)證」。 - 寧可少報(bào)不可錯(cuò)報(bào)。不確定的信息單獨(dú)列出不混進(jìn)結(jié)論。 - 每次調(diào)研產(chǎn)出結(jié)構(gòu)化摘要不寫(xiě)散文。 ## 能做什么 - 接收 main 派發(fā)的調(diào)研任務(wù)拆解成 3-5 個(gè)子問(wèn)題。 - 對(duì)每個(gè)子問(wèn)題給出結(jié)論、來(lái)源、置信度高/中/低。 - 把結(jié)果寫(xiě)入 shared/inbox/research-{日期}.md。 ## 不能做什么 - 不直接對(duì)外發(fā)布任何內(nèi)容。 - 不修改其他 Agent 的工作區(qū)文件。 - 不處理與調(diào)研無(wú)關(guān)的請(qǐng)求遇到就轉(zhuǎn)回 main。 ## 輸出格式 每條結(jié)論一行格式[置信度] 結(jié)論 —— 來(lái)源這份文件的關(guān)鍵在于「不能做什么」這一段。多 Agent 打架的根源就是邊界不清兩個(gè) Agent 都覺(jué)得某件事是自己的活。把拒絕規(guī)則寫(xiě)進(jìn) SOUL.mdAgent 在收到越界請(qǐng)求時(shí)會(huì)主動(dòng)轉(zhuǎn)回調(diào)度中樞。再給 main 寫(xiě)一份突出調(diào)度職責(zé)# SOUL ## 身份 你是總經(jīng)理代號(hào) main。你是全局調(diào)度中樞不親自執(zhí)行具體業(yè)務(wù)。 ## 信念 - 所有跨部門(mén)協(xié)調(diào)都經(jīng)過(guò)你不允許多個(gè) Agent 私下串通。 - 派活前先確認(rèn)對(duì)方職責(zé)范圍不把活派給錯(cuò)誤的部門(mén)。 - 每個(gè)任務(wù)有明確負(fù)責(zé)人和截止時(shí)間。 ## 能做什么 - 接收用戶請(qǐng)求拆解成子任務(wù)派發(fā)給對(duì)應(yīng) Agent。 - 匯總各 Agent 的產(chǎn)出向用戶匯報(bào)。 - 維護(hù)任務(wù)臺(tái)賬記錄每個(gè)任務(wù)的派發(fā)與完成狀態(tài)。 ## 不能做什么 - 不親自寫(xiě)文章、做調(diào)研、發(fā)內(nèi)容。 - 不繞過(guò)臺(tái)賬直接派活。兩份 SOUL.md 一對(duì)比邊界就清楚了main 只調(diào)度research 只調(diào)研。這就是「按價(jià)值流劃分」的雛形——高頻協(xié)作的角色放一起職責(zé)不重疊。3.2 openclaw.json 接線片段openclaw.json 是主配置負(fù)責(zé)把 Agent 注冊(cè)進(jìn)系統(tǒng)、綁定模型、指定工作區(qū)、配置頻道。新手最關(guān)心的是Base URL、Key、Model ID 填在哪。下面是一份最小可用的 openclaw.json{ version: 1.0, providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, models: { default: claude-sonnet, fast: claude-haiku } } }, agents: { list: [ { id: main, name: 總經(jīng)理, workspace: ./workspace/main, model: taotoken/default, channels: [console], heartbeat: 0 */2 * * * }, { id: research, name: 情報(bào)部, workspace: ./workspace/research, model: taotoken/fast, channels: [console], heartbeat: 0 */4 * * * } ] }, bindings: { main: [research], research: [main] }, shared: { inbox: ./shared/inbox } }逐段解釋。providers 里定義了一個(gè)叫 taotoken 的提供方baseUrl 指向 https://taotoken.net/api apiKey 用環(huán)境變量占位models 里定義了兩個(gè)模型別名default 和 fast。這樣 Agent 引用模型時(shí)寫(xiě) taotoken/default 就行換模型只改這一處。agents.list 是 Agent 注冊(cè)表。每個(gè) Agent 有 id、name、workspace、model、channels、heartbeat 六個(gè)字段。workspace 指向它的工作區(qū)目錄SOUL.md 就在里面。model 引用上面定義的別名。channels 是它監(jiān)聽(tīng)的頻道新手先用 console。heartbeat 是心跳頻率cron 表達(dá)式main 每?jī)尚r(shí)巡檢一次research 每四小時(shí)一次。bindings 定義協(xié)作關(guān)系。main 可以給 research 派活research 可以回報(bào)給 main。這個(gè)關(guān)系要和 SOUL.md 里的職責(zé)描述一致否則會(huì)出現(xiàn)「SOUL 說(shuō)不能干、bindings 卻允許派」的矛盾。shared.inbox 是跨 Agent 協(xié)作目錄research 的調(diào)研結(jié)果寫(xiě)這里main 從這里取。如果你用的是 TOML 格式部分版本支持等價(jià)寫(xiě)法是[providers.taotoken] baseUrl https://taotoken.net/api apiKey ${TAOTOKEN_API_KEY} [providers.taotoken.models] default claude-sonnet fast claude-haiku [[agents.list]] id main name 總經(jīng)理 workspace ./workspace/main model taotoken/default channels [console] heartbeat 0 */2 * * *兩種格式選一種即可JSON 更通用TOML 更易讀。關(guān)鍵是三件套齊全Base URL、Key、Model ID。缺任何一個(gè)啟動(dòng)時(shí)都會(huì)報(bào)錯(cuò)。4. 啟動(dòng)驗(yàn)證從 openclaw 命令到 Agent 正?；卦捙渲脤?xiě)完下一步是驗(yàn)證。別急著加更多 Agent先把這兩個(gè)跑通。第一步檢查配置文件語(yǔ)法。JSON 對(duì)逗號(hào)和引號(hào)敏感一個(gè)多余逗號(hào)就啟動(dòng)失敗。用這條命令驗(yàn)證python -m json.tool openclaw.json /dev/null echo JSON OK輸出 JSON OK 說(shuō)明語(yǔ)法沒(méi)問(wèn)題。如果是 TOML用python -c import tomllib; tomllib.load(open(openclaw.json,rb)); print(TOML OK)第二步確認(rèn)環(huán)境變量已加載。在項(xiàng)目根目錄執(zhí)行export $(grep -v ^# .env | xargs) echo $TAOTOKEN_API_KEY能打印出 Key 就說(shuō)明環(huán)境變量生效。如果為空檢查 .env 文件路徑和格式。第三步啟動(dòng) OpenClawopenclaw start --config ./openclaw.json正常啟動(dòng)會(huì)看到類(lèi)似輸出[INFO] loaded 2 agents: main, research [INFO] provider taotoken ready, baseUrlhttps://taotoken.net/api [INFO] shared inbox at ./shared/inbox [INFO] main listening on channel: console [INFO] research listening on channel: console [INFO] openclaw started看到 loaded 2 agents 和 provider ready 這兩行說(shuō)明 Agent 注冊(cè)和模型通道都通了。第四步發(fā)一條測(cè)試消息。在 console 頻道里對(duì) main 說(shuō)幫我調(diào)研一下「多 Agent 協(xié)作的常見(jiàn)模式」給出三條結(jié)論。預(yù)期行為main 收到請(qǐng)求判斷這是調(diào)研任務(wù)派給 researchresearch 執(zhí)行后把結(jié)果寫(xiě)入 shared/inbox/research-{日期}.mdmain 讀取結(jié)果并回報(bào)給你。如果一切正常你會(huì)看到 main 的回復(fù)里包含三條帶來(lái)源的結(jié)論。第五步檢查協(xié)作產(chǎn)物。打開(kāi) shared/inbox 目錄應(yīng)該有一個(gè)新文件ls -la shared/inbox/ cat shared/inbox/research-*.md文件內(nèi)容應(yīng)該是結(jié)構(gòu)化的結(jié)論列表每條帶置信度和來(lái)源。如果文件為空或格式不對(duì)說(shuō)明 research 的 SOUL.md 輸出格式約束沒(méi)生效回去檢查「輸出格式」那一段。驗(yàn)證成功的標(biāo)志有三個(gè)啟動(dòng)日志里兩個(gè) Agent 都 loaded、main 能正確派活、shared/inbox 里有結(jié)構(gòu)化產(chǎn)物。三個(gè)都滿足說(shuō)明你的 OpenClaw 從零到可運(yùn)行已經(jīng)完成。5. 常見(jiàn)報(bào)錯(cuò)排查401、local proxy failed、reading choices、OAuth新手搭建過(guò)程中報(bào)錯(cuò)集中在四類(lèi)。逐個(gè)說(shuō)清楚原因和解法。5.1 401 Unauthorized報(bào)錯(cuò)長(zhǎng)這樣[ERROR] provider taotoken request failed: 401 Unauthorized原因通常是 Key 沒(méi)加載或填錯(cuò)。排查順序先確認(rèn)環(huán)境變量里有 Keyecho $TAOTOKEN_API_KEY不為空再確認(rèn) openclaw.json 里 apiKey 寫(xiě)的是${TAOTOKEN_API_KEY}而不是硬編碼的空字符串最后確認(rèn) Key 本身有效去控制臺(tái) https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 看一眼 Key 狀態(tài)。三件套里 Key 是最容易出問(wèn)題的一環(huán)Base URL 和 Model ID 相對(duì)固定。5.2 local proxy failed報(bào)錯(cuò)長(zhǎng)這樣[ERROR] local proxy failed: connection refused這個(gè)報(bào)錯(cuò)說(shuō)明 OpenClaw 嘗試連接本地某個(gè)端口失敗。常見(jiàn)原因是你在配置里填了 localhost 或 127.0.0.1 作為 Base URL但本地并沒(méi)有對(duì)應(yīng)的服務(wù)在跑。解法是把 Base URL 改回 https://taotoken.net/api 不要指向本地。如果你確實(shí)有本地服務(wù)確認(rèn)它已啟動(dòng)且端口正確。5.3 reading choices 相關(guān)報(bào)錯(cuò)報(bào)錯(cuò)長(zhǎng)這樣[ERROR] error reading choices: unexpected end of JSON input這是模型返回體解析失敗。原因通常是 Model ID 填錯(cuò)請(qǐng)求發(fā)出去但返回的不是預(yù)期格式。檢查 openclaw.json 里 model 字段引用的別名確認(rèn) providers.taotoken.models 里定義了這個(gè)別名且別名對(duì)應(yīng)的 Model ID 是有效的。比如你寫(xiě)了 taotoken/default但 models 里沒(méi)有 default 這個(gè)鍵就會(huì)出這個(gè)錯(cuò)。5.4 OAuth 相關(guān)報(bào)錯(cuò)報(bào)錯(cuò)長(zhǎng)這樣[ERROR] oauth token expired or invalid如果你用的是需要 OAuth 的模型提供方會(huì)出現(xiàn)這個(gè)。解法是重新走一遍授權(quán)流程或者改用 API Key 方式。用 TaoToken 的 API Key 通道可以繞開(kāi) OAuth 的復(fù)雜性三件套里的 Key 就是干這個(gè)的。如果你在配置里同時(shí)寫(xiě)了 OAuth 和 API Key優(yōu)先用 API Key把 OAuth 相關(guān)字段刪掉。5.5 排查通用思路遇到報(bào)錯(cuò)先看三件事啟動(dòng)日志里 provider 有沒(méi)有 ready、Agent 有沒(méi)有 loaded、請(qǐng)求發(fā)出去后返回體是什么。大部分問(wèn)題出在三件套的某一項(xiàng)上。Base URL 固定填 https://taotoken.net/api Key 從控制臺(tái)取Model ID 用別名引用。這三樣對(duì)齊了401 和 reading choices 基本不會(huì)出現(xiàn)。如果排查完還是不通去接入文檔對(duì)照一遍配置格式https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文檔里有完整的字段說(shuō)明和示例比對(duì)著改通常能定位到問(wèn)題。6. 繼續(xù)往下走從兩個(gè) Agent 到可維護(hù)的 Agent 團(tuán)隊(duì)兩個(gè) Agent 跑通之后你可能會(huì)想加第三個(gè)、第四個(gè)。加之前先想清楚一件事新 Agent 對(duì)齊哪條價(jià)值流如果它和現(xiàn)有 Agent 職責(zé)重疊加進(jìn)去只會(huì)打架。判斷標(biāo)準(zhǔn)很簡(jiǎn)單——如果兩個(gè) Agent 會(huì)對(duì)同一個(gè)請(qǐng)求都說(shuō)「這是我的活」說(shuō)明邊界沒(méi)劃清先改 SOUL.md 再注冊(cè)。加 Agent 的流程是固定的在 workspace 下建新目錄寫(xiě) SOUL.md 和其他六個(gè)文件在 openclaw.json 的 agents.list 里加一條在 bindings 里補(bǔ)協(xié)作關(guān)系重啟驗(yàn)證。每次只加一個(gè)加完跑一遍測(cè)試消息確認(rèn)它能正確接收和回報(bào)再加下一個(gè)。長(zhǎng)期來(lái)看Agent 團(tuán)隊(duì)需要的是可維護(hù)性不是數(shù)量。我踩過(guò)的坑是早期一口氣加了五個(gè)結(jié)果互相不知道對(duì)方在干什么總經(jīng)理派錯(cuò)人情報(bào)部采集完素材沒(méi)人取。后來(lái)砍回三個(gè)把職責(zé)寫(xiě)死反而效率更高。黃金規(guī)模是 3 到 7 個(gè)部門(mén)超過(guò) 7 個(gè)就該考慮拆子團(tuán)隊(duì)了。如果你打算把 Agent 用在長(zhǎng)期編碼或復(fù)雜 Agent 編排上可以了解一下 Coding Plan它針對(duì)持續(xù)性的編碼任務(wù)做了優(yōu)化https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。如果只是想先驗(yàn)證模型對(duì)話效果用模型對(duì)話入口試幾條https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。憑證管理統(tǒng)一走 API Keys 頁(yè)面接入細(xì)節(jié)看文檔。最后給一個(gè)實(shí)用建議別追求一步到位。先用兩個(gè) Agent 跑通全流程把 SOUL.md 的邊界寫(xiě)清楚把 openclaw.json 的三件套配對(duì)驗(yàn)證 shared/inbox 有產(chǎn)物。這個(gè)最小閉環(huán)跑順了再加角色就是復(fù)制粘貼改名字的事。反過(guò)來(lái)如果兩個(gè) Agent 都跑不通加十個(gè)只會(huì)更亂。