1. OpenClaw 環(huán)境變量到底管什么從助手活動(dòng)范圍說(shuō)起OpenClaw 環(huán)境變量配置說(shuō)白了就是決定這個(gè)助手“能看哪些目錄、能調(diào)哪些模型、能連哪些渠道”的一整套開(kāi)關(guān)。你把它理解成給助手劃活動(dòng)范圍狀態(tài)目錄是它的活動(dòng)場(chǎng)地API Key 是它的通行證渠道令牌是它對(duì)外說(shuō)話的嘴。范圍劃不清楚要么助手跑不起來(lái)要么它偷偷用了你不想讓它用的密鑰。我見(jiàn)過(guò)太多人把 Key 直接寫進(jìn)代碼里或者一股腦塞進(jìn)系統(tǒng)級(jí)配置結(jié)果換臺(tái)機(jī)器就崩團(tuán)隊(duì)協(xié)作時(shí)還得挨個(gè)改。OpenClaw 的設(shè)計(jì)其實(shí)挺講究它把配置分成三層系統(tǒng)級(jí)、用戶級(jí)、應(yīng)用專屬.env。這三層不是隨便堆的而是有明確的優(yōu)先級(jí)覆蓋關(guān)系。搞懂這個(gè)關(guān)系你就能做到“本地開(kāi)發(fā)用一套 Key部署到服務(wù)器自動(dòng)切另一套”不用改一行代碼。這篇面向的是已經(jīng)裝好 OpenClaw、但配置還靠復(fù)制粘貼、遇到?jīng)_突就抓瞎的朋友。我會(huì)從.env文件加載講起把優(yōu)先級(jí)規(guī)則用可復(fù)制的命令驗(yàn)證一遍再演示怎么把 endpoint 和 Key 統(tǒng)一改到 TaoToken 通道。全程給命令、給模板、給排錯(cuò)對(duì)照表你跟著敲就能復(fù)現(xiàn)。先明確一個(gè)核心檢索詞OpenClaw 環(huán)境變量?jī)?yōu)先級(jí)。這是后面所有操作的骨架。優(yōu)先級(jí)從高到低大致是進(jìn)程級(jí)臨時(shí)變量 用戶級(jí) shell 配置 項(xiàng)目本地.env 全局~/.openclaw/.envopenclaw.json的 env 塊 系統(tǒng)級(jí)環(huán)境變量。記住這條鏈排查沖突時(shí)直接順著往下找。為什么要有這么多層因?yàn)槭褂脠?chǎng)景不同。臨時(shí)測(cè)試時(shí)你不想污染配置文件就在命令前加變量長(zhǎng)期個(gè)人使用寫進(jìn)~/.bashrc或~/.zshrc項(xiàng)目專屬的敏感信息放項(xiàng)目根目錄.env后臺(tái)服務(wù)部署則用~/.openclaw/.env。每一層都有它的位置混用就會(huì)出亂子。還有一個(gè)容易被忽略的點(diǎn)已存在的非空變量不會(huì)被低優(yōu)先級(jí)覆蓋。這意味著如果你在 shell 里export了一個(gè)空值它可能擋住后面.env的加載。這個(gè)坑我在驗(yàn)證環(huán)節(jié)會(huì)專門演示。2. 接入前的準(zhǔn)備TaoToken 統(tǒng)一 Key 與 OpenClaw 的對(duì)接位置在動(dòng).env之前先把“通行證”準(zhǔn)備好。OpenClaw 支持多家模型提供商每個(gè)提供商有自己的變量名比如OPENAI_API_KEY、ANTHROPIC_API_KEY。但如果你像我一樣不想在十幾個(gè)平臺(tái)之間來(lái)回切換可以用 TaoToken 的統(tǒng)一通道把 endpoint 和 Key 收斂到一處。TaoToken 的定位是統(tǒng)一模型接入層你拿一個(gè) Key 就能調(diào)不同模型。對(duì) OpenClaw 來(lái)說(shuō)關(guān)鍵是改兩個(gè)東西Base URLendpoint和API Key。OpenClaw 讀取模型配置時(shí)會(huì)優(yōu)先看環(huán)境變量里有沒(méi)有對(duì)應(yīng)的*_BASE_URL和*_API_KEY。所以我們要做的就是在.env里把這兩項(xiàng)指向 TaoToken。先拿 Key。訪問(wèn)https://taotoken.net/api-keys帶 utm 參數(shù)?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapikeys登錄后創(chuàng)建一個(gè)新 Key。建議命名帶上用途比如openclaw-dev方便后面輪換時(shí)辨認(rèn)。創(chuàng)建完復(fù)制那串sk-開(kāi)頭的字符串只顯示一次丟了就重新建。然后確認(rèn) endpoint。TaoToken 的 API 根地址是https://taotoken.net/api注意這個(gè)地址不加 UTM 參數(shù)直接用于程序請(qǐng)求。OpenClaw 里配置時(shí)通常填到/v1這一級(jí)具體看你用的提供商協(xié)議。比如走 OpenAI 兼容協(xié)議Base URL 就填https://taotoken.net/api/v1。這里有個(gè)細(xì)節(jié)OpenClaw 不同版本對(duì) Base URL 的變量名可能略有差異。常見(jiàn)的有OPENAI_BASE_URL、OPENAI_API_BASE以及針對(duì) Anthropic 的ANTHROPIC_BASE_URL。最穩(wěn)妥的辦法是先看項(xiàng)目自帶的.env.example里面列了當(dāng)前版本支持的變量名。我下面給的模板會(huì)同時(shí)覆蓋這兩種寫法你用的時(shí)候按實(shí)際生效的保留一個(gè)就行。另外如果你打算長(zhǎng)期跑編碼類任務(wù)或 Agent 工作流可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcodingplan它在額度使用上對(duì)高頻調(diào)用更友好。不過(guò)這篇重點(diǎn)在配置套餐選擇你按自己用量判斷。準(zhǔn)備好 Key 和 endpoint 后別急著寫進(jìn)全局配置。先在終端里用臨時(shí)變量驗(yàn)證一次確認(rèn)通道能通再落到.env文件。這樣出問(wèn)題能快速定位是 Key 的問(wèn)題還是配置文件的問(wèn)題。3. 可復(fù)制配置.env 模板與優(yōu)先級(jí)覆蓋寫法這一節(jié)給可直接復(fù)制的配置片段。分兩部分項(xiàng)目本地.env和用戶級(jí) shell 配置。路徑按你實(shí)際安裝位置調(diào)整我以~/OpenClaw作為項(xiàng)目根目錄舉例。先看項(xiàng)目根目錄的.env文件。在~/OpenClaw下創(chuàng)建.env內(nèi)容如下。注意set -a的用法在 shell 加載時(shí)才有意義.env文件本身只是鍵值對(duì)OpenClaw 讀取時(shí)會(huì)自己解析。# ~/OpenClaw/.env # TaoToken 統(tǒng)一通道 OPENAI_API_KEYsk-你的TaoTokenKey OPENAI_BASE_URLhttps://taotoken.net/api/v1 # 部分版本用下面這個(gè)變量名二選一保留生效的 # OPENAI_API_BASEhttps://taotoken.net/api/v1 # Anthropic 協(xié)議走同一通道 ANTHROPIC_API_KEYsk-你的TaoTokenKey ANTHROPIC_BASE_URLhttps://taotoken.net/api # OpenClaw 活動(dòng)范圍 OPENCLAW_HOME/home/你的用戶名 OPENCLAW_STATE_DIR/home/你的用戶名/OpenClaw OPENCLAW_CONFIG_PATH/home/你的用戶名/OpenClaw/openclaw.json OPENCLAW_WORKSPACE/home/你的用戶名/OpenClaw/workspace # 網(wǎng)關(guān)認(rèn)證 # 生成命令openssl rand -hex 32 OPENCLAW_GATEWAY_TOKEN替換成隨機(jī)長(zhǎng)字符串 # 渠道令牌按需保留 # TELEGRAM_BOT_TOKEN123456:ABC... # DISCORD_BOT_TOKENMTk4...這個(gè)文件里OPENAI_BASE_URL和ANTHROPIC_BASE_URL就是指向 TaoToken 的關(guān)鍵。Key 用同一個(gè)省去多平臺(tái)管理。OPENCLAW_STATE_DIR決定了助手把日志、緩存寫在哪等于它的活動(dòng)場(chǎng)地邊界別指向系統(tǒng)目錄。再看用戶級(jí) shell 配置。編輯~/.bashrc或~/.zshrc加入自動(dòng)加載邏輯和路徑設(shè)置# ~/.bashrc 片段 # 自動(dòng)加載項(xiàng)目 .envset -a 讓變量自動(dòng)導(dǎo)出 if [ -f $HOME/OpenClaw/.env ]; then set -a source $HOME/OpenClaw/.env set a fi # 路徑集中管理 export OPENCLAW_HOME$HOME export OPENCLAW_STATE_DIR$HOME/OpenClaw export OPENCLAW_CONFIG_PATH$OPENCLAW_STATE_DIR/openclaw.json # 別名簡(jiǎn)化啟動(dòng) alias openclawnode $HOME/.local/openclaw/openclaw.mjs保存后執(zhí)行source ~/.bashrc。這里的關(guān)鍵是set -a它讓source進(jìn)來(lái)的變量自動(dòng)成為環(huán)境變量否則.env里的值只在當(dāng)前 shell 有效子進(jìn)程讀不到?，F(xiàn)在講優(yōu)先級(jí)覆蓋的寫法。假設(shè)你想臨時(shí)用另一個(gè) Key 測(cè)試不改文件直接在命令前加變量OPENAI_API_KEYsk-臨時(shí)Key openclaw start這個(gè)進(jìn)程級(jí)變量?jī)?yōu)先級(jí)最高會(huì)蓋過(guò).env和.bashrc里的值。驗(yàn)證方法在下一節(jié)。如果你想讓某個(gè)變量在用戶級(jí)覆蓋.env直接在.bashrc里export同名變量即可因?yàn)橛脩艏?jí)優(yōu)先級(jí)高于項(xiàng)目.env。但注意前面說(shuō)的規(guī)則已存在的非空變量不會(huì)被低優(yōu)先級(jí)覆蓋。所以如果你在.bashrc里export OPENAI_API_KEY空值它可能擋住.env的加載導(dǎo)致 Key 為空。這個(gè)坑要避開(kāi)。對(duì)于用 Claude Code 或 Cline MCP 的朋友配置邏輯類似但變量名不同。Claude Code 的 settings 文件通常在~/.claude/settings.json里面配env塊{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoTokenKey, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }這三件套——Base URL、Key、Model ID——缺一不可。Cline MCP 的配置在cline_mcp_settings.jsonCodex 的 auth.json 則在~/.codex/auth.json結(jié)構(gòu)不同但核心字段一致。如果你用 CC Switch 管理多套配置記得每個(gè) profile 都填全這三項(xiàng)否則切換后會(huì)報(bào)認(rèn)證失敗。4. 驗(yàn)證請(qǐng)求與成功結(jié)果優(yōu)先級(jí)實(shí)測(cè)與通道連通配置寫完必須驗(yàn)證。分三步驗(yàn)證變量加載、驗(yàn)證優(yōu)先級(jí)覆蓋、驗(yàn)證 TaoToken 通道能通。第一步檢查變量是否加載成功。新開(kāi)一個(gè)終端執(zhí)行echo $OPENAI_API_KEY echo $OPENAI_BASE_URL echo $OPENCLAW_STATE_DIR如果OPENAI_API_KEY輸出的是你.env里的 Key說(shuō)明自動(dòng)加載生效。如果為空檢查.bashrc里的source路徑對(duì)不對(duì)以及有沒(méi)有被空值覆蓋。第二步驗(yàn)證優(yōu)先級(jí)。這是最容易出錯(cuò)的地方。我們做一組對(duì)照實(shí)驗(yàn)# 實(shí)驗(yàn)1進(jìn)程級(jí)覆蓋 OPENAI_API_KEYsk-test-override openclaw config check # 觀察輸出里 Key 是否變成 sk-test-override # 實(shí)驗(yàn)2確認(rèn) .env 值 openclaw config check # 觀察 Key 是否回到 .env 里的值openclaw config check會(huì)打印當(dāng)前生效的配置。如果實(shí)驗(yàn)1顯示覆蓋值、實(shí)驗(yàn)2顯示.env值說(shuō)明優(yōu)先級(jí)鏈正常。如果實(shí)驗(yàn)2還是顯示覆蓋值說(shuō)明你的 shell 會(huì)話里殘留了export執(zhí)行unset OPENAI_API_KEY再試。第三步驗(yàn)證 TaoToken 通道。用 curl 直接打 endpoint確認(rèn) Key 和地址都對(duì)curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $OPENAI_API_KEY | head -c 500如果返回模型列表的 JSON說(shuō)明通道通。如果返回 401說(shuō)明 Key 無(wú)效或沒(méi)帶上返回 404說(shuō)明 Base URL 路徑不對(duì)檢查是不是少了或多了/v1。然后啟動(dòng) OpenClaw 做一次真實(shí)調(diào)用openclaw start # 在助手界面里發(fā)一條測(cè)試消息比如“你好報(bào)一下你用的模型”成功的話助手會(huì)正?；貜?fù)日志里能看到請(qǐng)求打到了taotoken.net。如果日志顯示請(qǐng)求打到了api.openai.com說(shuō)明OPENAI_BASE_URL沒(méi)生效回去檢查變量名是否匹配當(dāng)前 OpenClaw 版本。我實(shí)測(cè)下來(lái)最容易卡住的是 Base URL 的/v1后綴。TaoToken 的根地址是https://taotoken.net/api但 OpenAI 兼容協(xié)議需要/v1所以填https://taotoken.net/api/v1。Anthropic 協(xié)議則通常不需要/v1填https://taotoken.net/api即可。這個(gè)差異導(dǎo)致很多人配完一個(gè)能通、另一個(gè)報(bào) 404。驗(yàn)證通過(guò)后建議把openclaw config check的輸出存一份作為基線。以后改配置出問(wèn)題對(duì)比一下就知道哪個(gè)變量變了。5. 常見(jiàn)報(bào)錯(cuò)排查401、local proxy failed 與 choices 讀取失敗配置過(guò)程中有幾類報(bào)錯(cuò)反復(fù)出現(xiàn)我按真實(shí)日志對(duì)照給你排查路徑。報(bào)錯(cuò)一401 Unauthorized。日志里通常是invalid api key或authentication failed。原因有三個(gè)Key 復(fù)制時(shí)帶了空格或換行Key 被低優(yōu)先級(jí)配置覆蓋成了舊值.env文件沒(méi)被加載。排查順序先echo $OPENAI_API_KEY看值對(duì)不對(duì)再openclaw config check看生效值最后檢查.env文件權(quán)限chmod 600 .env。如果 Key 里混入了【需替換】這種占位符沒(méi)刪干凈也會(huì) 401。報(bào)錯(cuò)二local proxy failed。這個(gè)通常出現(xiàn)在你配了本地代理或 Base URL 指向了localhost但服務(wù)沒(méi)起。如果你沒(méi)用本地代理檢查OPENAI_BASE_URL是不是誤填了http://127.0.0.1:xxxx。改成https://taotoken.net/api/v1即可。另外某些版本的 OpenClaw 會(huì)讀HTTP_PROXY環(huán)境變量如果你系統(tǒng)里設(shè)了代理但代理沒(méi)運(yùn)行也會(huì)報(bào)這個(gè)。執(zhí)行unset HTTP_PROXY HTTPS_PROXY再啟動(dòng)。報(bào)錯(cuò)三reading choices 失敗。日志類似cannot read property choices of undefined或response.choices is undefined。這說(shuō)明請(qǐng)求發(fā)出去了但返回結(jié)構(gòu)不是預(yù)期的 OpenAI 格式。常見(jiàn)原因是 Base URL 指向了非兼容端點(diǎn)或者模型名填錯(cuò)了。檢查OPENAI_BASE_URL是否以/v1結(jié)尾以及你請(qǐng)求的模型 ID 在 TaoToken 通道里是否可用。用第 4 節(jié)的 curl 命令先確認(rèn)/models返回正常。報(bào)錯(cuò)四OAuth 相關(guān)錯(cuò)誤。如果你用 Claude Code 或 Codex 的 OAuth 登錄方式又同時(shí)配了 API Key可能沖突。日志里會(huì)出現(xiàn)oauth token invalid或refresh failed。解決辦法是明確用哪種認(rèn)證用 Key 就把 OAuth 相關(guān)配置清掉用 OAuth 就別設(shè)ANTHROPIC_API_KEY。CC Switch 用戶注意每個(gè) profile 只保留一種認(rèn)證方式。報(bào)錯(cuò)五變量不生效但沒(méi)報(bào)錯(cuò)。助手正常跑但用的還是舊 Key。這幾乎都是優(yōu)先級(jí)問(wèn)題。按第 4 節(jié)的對(duì)照實(shí)驗(yàn)排查重點(diǎn)看 shell 里有沒(méi)有殘留export以及.bashrc和.env里是不是有同名變量互相打架。記住規(guī)則非空變量不會(huì)被覆蓋所以一個(gè)空的export反而會(huì)擋住后面的加載。排查時(shí)善用env | grep -i openclaw和env | grep -i api_key一眼看清當(dāng)前 shell 里所有相關(guān)變量。比逐個(gè)echo快得多。6. 把配置固化下來(lái)多環(huán)境切換與長(zhǎng)期維護(hù)配置調(diào)通只是開(kāi)始長(zhǎng)期維護(hù)才是省心的關(guān)鍵。我建議按環(huán)境拆文件本地開(kāi)發(fā)用~/OpenClaw/.env服務(wù)器部署用~/.openclaw/.env兩者內(nèi)容可以不同但結(jié)構(gòu)一致。切換時(shí)不用改代碼靠?jī)?yōu)先級(jí)自然覆蓋。多環(huán)境切換的一個(gè)實(shí)用技巧是用 shell 函數(shù)封裝# ~/.bashrc openclaw-dev() { export OPENCLAW_STATE_DIR$HOME/OpenClaw-dev export OPENAI_API_KEYsk-開(kāi)發(fā)Key openclaw start } openclaw-prod() { export OPENCLAW_STATE_DIR$HOME/OpenClaw-prod export OPENAI_API_KEYsk-生產(chǎn)Key openclaw start }這樣一條命令切一套環(huán)境狀態(tài)目錄和 Key 一起換不會(huì)串。Key 輪換也要提前想好。TaoToken 的 Key 如果泄露去控制臺(tái)吊銷重建然后更新.env里的值source一下即可。別把 Key 提交到 Git.gitignore里加上.env和*.env。團(tuán)隊(duì)協(xié)作時(shí)用.env.example做模板真實(shí)值各自填。最后定期跑一次openclaw config check把輸出和基線對(duì)比。配置漂移是慢性病早發(fā)現(xiàn)早治。如果你要接更多模型或渠道統(tǒng)一走 TaoToken 通道能少管一堆 Keyendpoint 和認(rèn)證都收斂到一處維護(hù)成本直線下降。需要查最新變量名和接入細(xì)節(jié)去接入文檔https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc對(duì)照。想先試試模型對(duì)話效果用https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat快速驗(yàn)證通道。Key 管理在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapikeys。長(zhǎng)期跑編碼任務(wù)的話Coding Plan 頁(yè)面有額度說(shuō)明按需選。