1. 為什么要在 Linux 上給 OpenClaw 接統(tǒng)一 Key 通道OpenClaw 是一個(gè)跑在本地或服務(wù)器上的 AI Agent 網(wǎng)關(guān)它本身不綁定某一家模型服務(wù)而是通過配置去調(diào)用外部大模型接口。你在 Linux 上把它部署起來之后真正決定它能不能干活、干活穩(wěn)不穩(wěn)的其實(shí)是后面那層模型通道。很多人卡在部署完成、Control UI 能打開但一發(fā)消息就報(bào)鑒權(quán)失敗或者超時(shí)問題基本都出在 Key 和 Base URL 這一層。這篇手冊(cè)面向的是已經(jīng)在 Linux 上折騰 OpenClaw 的開發(fā)者把常規(guī)安裝、Docker、Docker Compose 三條部署路徑都走一遍重點(diǎn)不是重復(fù)官方安裝步驟而是每一步之后怎么把 TaoToken 的統(tǒng)一 Key/API 通道接進(jìn)去。TaoToken 在這里扮演的角色是一個(gè)統(tǒng)一的模型調(diào)用入口你拿到一個(gè) Key配好 Base URLOpenClaw 就能通過它去請(qǐng)求背后的模型不用在多個(gè)廠商的 Key 之間來回切換。官網(wǎng)入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 這兩個(gè)地址后面配置里會(huì)反復(fù)用到。適合誰看已經(jīng)在 Ubuntu、Debian 或者 CentOS 上裝過 OpenClaw或者正準(zhǔn)備裝并且希望把模型調(diào)用收斂到一個(gè)統(tǒng)一通道的人。如果你還沒拿到 Key先去控制臺(tái)建一個(gè)后面所有配置都圍繞它展開。整篇的節(jié)奏是先講清楚三種部署方式各自怎么落地再給出可復(fù)制的 config.toml 和 settings.json 骨架最后用連通性命令驗(yàn)證調(diào)用真的生效了。2. 部署前的準(zhǔn)備TaoToken Key 與系統(tǒng)要求2.1 拿到統(tǒng)一 Key 和 API 地址在開始裝 OpenClaw 之前先把 TaoToken 這邊的信息準(zhǔn)備好。你需要兩樣?xùn)|西一個(gè) API Key一個(gè) Base URL。Key 在控制臺(tái)的 API Keys 頁面創(chuàng)建地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。創(chuàng)建的時(shí)候給它起個(gè)能認(rèn)出來的名字比如 openclaw-linux方便以后輪換或者吊銷。Base URL 統(tǒng)一用 https://taotoken.net/api 注意這個(gè)地址后面不要多加斜杠也不要在末尾拼 /v1OpenClaw 的配置里會(huì)自己處理路徑拼接。我見過有人手動(dòng)補(bǔ)成 /api/v1 結(jié)果 404這個(gè)坑后面排障章節(jié)會(huì)再提。注意Key 只在創(chuàng)建時(shí)完整顯示一次復(fù)制下來存到密碼管理器或者臨時(shí)環(huán)境變量里別直接寫進(jìn)會(huì)提交到 Git 的文件。2.2 系統(tǒng)與依賴要求三種部署方式對(duì)系統(tǒng)的要求不完全一樣先對(duì)照一下自己的機(jī)器項(xiàng)目常規(guī)安裝DockerDocker Compose操作系統(tǒng)Ubuntu 20.04 / Debian 11 / CentOS 等同左同左Node.js24 推薦22.19 可用不需要不需要Docker不需要Engine Compose v2Engine Compose v2內(nèi)存≥ 1 GB本地構(gòu)建鏡像 ≥ 2 GB本地構(gòu)建鏡像 ≥ 2 GB磁盤預(yù)留配置與日志空間預(yù)留鏡像空間預(yù)留鏡像與卷空間默認(rèn)端口記住兩個(gè)Gateway 是 18789Bridge 是 18790。后面健康檢查和 Control UI 都走 18789。2.3 環(huán)境變量先擺好不管走哪條路建議先把 Key 和地址放進(jìn)環(huán)境變量避免散落在各個(gè)配置文件里。在 ~/.bashrc 或者一個(gè)單獨(dú)的 env 文件里寫export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api改完執(zhí)行 source ~/.bashrc 讓它生效。Docker 和 Compose 場(chǎng)景下這些變量會(huì)通過 compose 的 environment 段傳進(jìn)容器所以命名保持一致能省很多事。3. 方式一常規(guī)安裝并接入 TaoToken3.1 安裝 OpenClaw常規(guī)安裝適合本機(jī)開發(fā)或者單機(jī)調(diào)試。一鍵腳本最省事curl -fsSL https://openclaw.ai/install.sh | bash如果你不想走交互式引導(dǎo)加個(gè)參數(shù)跳過curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard不想依賴系統(tǒng) Node 的話用本地 prefix 安裝OpenClaw 和 Node 都會(huì)裝到 ~/.openclaw 下面curl -fsSL https://openclaw.ai/install-cli.sh | bash也可以用 npm、pnpm 或 bun 全局裝npm install -g openclawlatest openclaw onboard --install-daemon裝完先確認(rèn)版本和健康狀態(tài)openclaw --version openclaw doctor openclaw gateway status3.2 配置 config.toml 接入統(tǒng)一通道OpenClaw 的模型通道配置集中在 config.toml 里。常規(guī)安裝下它一般在 ~/.openclaw/config.toml。下面是一個(gè)可以直接改的骨架把 provider 指向 TaoToken[gateway] mode local bind lan port 18789 [providers.taotoken] type openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} default_model claude-sonnet-4-20250514 [agents.default] provider taotoken model claude-sonnet-4-20250514幾個(gè)關(guān)鍵點(diǎn)解釋一下。type 用 openai-compatible因?yàn)?TaoToken 的接口是兼容 OpenAI 調(diào)用格式的OpenClaw 里選這個(gè)類型就能直接對(duì)接。base_url 寫 https://taotoken.net/api 不要帶尾斜杠。api_key 用 ${TAOTOKEN_API_KEY} 引用環(huán)境變量這樣配置文件本身可以安全地放進(jìn)版本管理。default_model 填你實(shí)際要用的模型名具體可用列表在模型對(duì)話頁面能看到地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。3.3 settings.json 補(bǔ)充運(yùn)行時(shí)參數(shù)有些運(yùn)行時(shí)參數(shù)放在 settings.json 里更順手路徑通常是 ~/.openclaw/settings.json。骨架如下{ gateway: { token: ${OPENCLAW_GATEWAY_TOKEN}, allowedOrigins: [ http://localhost:18789, http://127.0.0.1:18789 ] }, providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, timeoutMs: 60000, maxRetries: 2 } } }timeoutMs 給到 60 秒是因?yàn)橛行┠Ｐ褪?token 返回慢設(shè)太短會(huì)誤判成失敗。maxRetries 設(shè) 2 次網(wǎng)絡(luò)抖動(dòng)時(shí)能自動(dòng)重試但別設(shè)太大否則真出錯(cuò)時(shí)會(huì)等很久。3.4 啟動(dòng)守護(hù)進(jìn)程并驗(yàn)證配置寫好后裝守護(hù)進(jìn)程讓它開機(jī)自啟openclaw onboard --install-daemonLinux 和 WSL2 下會(huì)創(chuàng)建 systemd user service。然后跑連通性檢查curl -fsS http://127.0.0.1:18789/healthz返回 ok 之類的健康標(biāo)識(shí)就說明 Gateway 起來了。接著驗(yàn)證模型通道是否真的通用 OpenClaw 自帶的診斷openclaw doctor --provider taotoken如果這一步返回模型列表或者成功響應(yīng)說明 Key 和 Base URL 都對(duì)了。瀏覽器打開 http://127.0.0.1:18789/ 在 Settings 里粘貼 Gateway Token就能進(jìn) Control UI 發(fā)消息測(cè)試。4. 方式二Docker 部署并接入 TaoToken4.1 前置檢查Docker 方式適合不想污染宿主機(jī)環(huán)境或者在 VPS 上做隔離運(yùn)行的場(chǎng)景。先確認(rèn) Docker 和 Compose v2 都在docker --version docker compose version兩個(gè)命令都能輸出版本號(hào)再往下走。4.2 用官方 setup 腳本拉起克隆倉(cāng)庫(kù)后執(zhí)行官方腳本git clone https://github.com/openclaw/openclaw.git cd openclaw ./scripts/docker/setup.sh小內(nèi)存 VPS 強(qiáng)烈建議用預(yù)構(gòu)建鏡像避免本地構(gòu)建時(shí) OOMexport OPENCLAW_IMAGEghcr.io/openclaw/openclaw:latest ./scripts/docker/setup.sh腳本會(huì)自動(dòng)拉鏡像、跑交互式 onboarding、生成 .env 和 Gateway Token最后用 Compose 把 Gateway 啟動(dòng)起來。4.3 把 TaoToken 配置注入容器Docker 場(chǎng)景下配置目錄是 bind-mount 進(jìn)容器的所以你在宿主機(jī)改 ~/.openclaw/config.toml容器里立刻生效。config.toml 的內(nèi)容和 3.2 節(jié)一樣重點(diǎn)是環(huán)境變量要傳進(jìn)去。在倉(cāng)庫(kù)根目錄的 .env 文件里加TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api OPENCLAW_GATEWAY_TOKEN你生成的Token然后在 docker-compose.yml 的 openclaw-gateway 服務(wù) environment 段引用environment: HOME: /home/node OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN} TAOTOKEN_API_KEY: ${TAOTOKEN_API_KEY} TAOTOKEN_BASE_URL: ${TAOTOKEN_BASE_URL}這樣容器里的 config.toml 用 ${TAOTOKEN_API_KEY} 就能取到值。4.4 手動(dòng) Docker 流程可選如果你想完全手動(dòng)控制不用 setup 腳本可以這樣docker build -t openclaw:local -f Dockerfile . docker compose run --rm --no-deps --entrypoint node openclaw-gateway \ dist/index.js onboard --mode local --no-install-daemon docker compose up -d openclaw-gateway啟動(dòng)后拿 dashboard 鏈接docker compose run --rm openclaw-cli dashboard --no-open4.5 健康檢查Docker 下有兩個(gè)檢查端點(diǎn)liveness 和 readiness 分開curl -fsS http://127.0.0.1:18789/healthz curl -fsS http://127.0.0.1:18789/readyzhealthz 通說明進(jìn)程活著readyz 通說明依賴都就緒了。如果 healthz 通但 readyz 不通多半是模型通道沒配好回去檢查 config.toml 里的 base_url 和 Key。5. 方式三Docker Compose 生產(chǎn)部署與統(tǒng)一通道5.1 標(biāo)準(zhǔn) Compose 結(jié)構(gòu)官方 docker-compose.yml 里有兩個(gè)服務(wù)分工明確服務(wù)作用openclaw-gateway常駐 Gateway對(duì)外暴露 18789/18790openclaw-cli一次性 CLI 容器執(zhí)行管理命令核心結(jié)構(gòu)長(zhǎng)這樣services: openclaw-gateway: image: ${OPENCLAW_IMAGE:-openclaw:local} environment: HOME: /home/node OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN} TAOTOKEN_API_KEY: ${TAOTOKEN_API_KEY} TAOTOKEN_BASE_URL: ${TAOTOKEN_BASE_URL} volumes: - ${OPENCLAW_CONFIG_DIR:-~/.openclaw}:/home/node/.openclaw - ${OPENCLAW_WORKSPACE_DIR:-~/.openclaw/workspace}:/home/node/.openclaw/workspace ports: - ${OPENCLAW_GATEWAY_PORT:-18789}:18789 - ${OPENCLAW_BRIDGE_PORT:-18790}:18790 restart: unless-stopped command: [node, dist/index.js, gateway, --bind, lan, --port, 18789] openclaw-cli: image: ${OPENCLAW_IMAGE:-openclaw:local} network_mode: service:openclaw-gateway volumes: - ${OPENCLAW_CONFIG_DIR:-~/.openclaw}:/home/node/.openclaw - ${OPENCLAW_WORKSPACE_DIR:-~/.openclaw/workspace}:/home/node/.openclaw/workspace entrypoint: [node, dist/index.js]完整文件以官方倉(cāng)庫(kù)為準(zhǔn)這里只是把和 TaoToken 相關(guān)的環(huán)境變量標(biāo)出來。5.2 一鍵啟動(dòng)cd openclaw export OPENCLAW_IMAGEghcr.io/openclaw/openclaw:latest ./scripts/docker/setup.sh5.3 常用 Compose 命令docker compose up -d openclaw-gateway docker compose logs -f openclaw-gateway docker compose down docker compose run --rm openclaw-cli channels add --channel telegram --token token docker compose run --rm openclaw-cli devices list docker compose run --rm openclaw-cli devices approve requestId5.4 環(huán)境變量速查變量用途OPENCLAW_IMAGE使用遠(yuǎn)程預(yù)構(gòu)建鏡像OPENCLAW_GATEWAY_TOKENGateway 認(rèn)證 TokenOPENCLAW_CONFIG_DIR配置目錄掛載路徑OPENCLAW_WORKSPACE_DIR工作區(qū)掛載路徑TAOTOKEN_API_KEY統(tǒng)一通道 KeyTAOTOKEN_BASE_URL統(tǒng)一通道地址OPENCLAW_SANDBOX啟用 Agent Sandbox1/true5.5 持久化與權(quán)限容器 bind-mount 兩個(gè)路徑替換容器后數(shù)據(jù)保留~/.openclaw 存配置和 openclaw.json~/.openclaw/workspace 存 Agent 工作區(qū)。容器以 uid 1000node運(yùn)行宿主機(jī)掛載目錄權(quán)限要對(duì)sudo chown -R 1000:1000 ~/.openclaw權(quán)限不對(duì)會(huì)報(bào) EACCES這是 Compose 部署里最常見的坑之一。5.6 啟用 Agent Sandbox想讓 Agent 工具在獨(dú)立容器里執(zhí)行加個(gè)環(huán)境變量export OPENCLAW_SANDBOX1 ./scripts/docker/setup.shSandbox 在獨(dú)立 Docker 容器中跑 Agent 工具Gateway 仍在主容器里隔離性更好。6. 驗(yàn)證請(qǐng)求與成功結(jié)果配置寫完不算完得確認(rèn)調(diào)用真的生效。分三層驗(yàn)證。第一層Gateway 健康curl -fsS http://127.0.0.1:18789/healthz curl -fsS http://127.0.0.1:18789/readyz第二層直接打 TaoToken 的接口確認(rèn) Key 和地址本身沒問題curl -fsS https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY返回模型列表 JSON 就說明 Key 有效、地址正確。如果這里就失敗先別折騰 OpenClaw去控制臺(tái)確認(rèn) Key 狀態(tài)。第三層通過 OpenClaw 發(fā)一條測(cè)試消息。在 Control UI 里發(fā)一句簡(jiǎn)單的話或者在 CLI 容器里執(zhí)行docker compose run --rm openclaw-cli agents run --message ping成功的話你會(huì)看到模型返回的文本日志里也能看到請(qǐng)求打到了 https://taotoken.net/api 。實(shí)測(cè)下來三層都通之后OpenClaw 的模型調(diào)用就穩(wěn)定了。7. 本篇常見錯(cuò)誤排查7.1 構(gòu)建鏡像 OOMexit 1371 GB 內(nèi)存的 VPS 本地構(gòu)建鏡像會(huì)失敗。改用預(yù)構(gòu)建鏡像export OPENCLAW_IMAGEghcr.io/openclaw/openclaw:latest ./scripts/docker/setup.sh7.2 EACCES 權(quán)限錯(cuò)誤容器以 uid 1000 運(yùn)行宿主機(jī)目錄屬主不對(duì)就會(huì)報(bào)錯(cuò)sudo chown -R 1000:1000 ~/.openclaw7.3 Gateway 重啟循環(huán)檢查 gateway.bind 的值用 lan 或 loopback不要寫 0.0.0.0 作為 bind 值。寫錯(cuò)了 Gateway 起不來會(huì)一直重啟。7.4 模型調(diào)用 404 或鑒權(quán)失敗最常見的是 base_url 寫錯(cuò)。正確寫法是 https://taotoken.net/api 不要補(bǔ) /v1不要加尾斜杠。鑒權(quán)失敗則檢查環(huán)境變量有沒有真的傳進(jìn)容器用 docker compose exec openclaw-gateway env | grep TAOTOKEN 確認(rèn)。7.5 Docker 內(nèi)訪問宿主機(jī) Ollama/LM Studio如果你同時(shí)用本地模型容器內(nèi)不能用 127.0.0.1要換成 host.docker.internalProviderDocker 內(nèi) URLOllamahttp://host.docker.internal:11434LM Studiohttp://host.docker.internal:1234宿主機(jī)服務(wù)需監(jiān)聽 0.0.0.0。7.6 openclaw 命令找不到常規(guī)安裝npm 全局 bin 不在 PATH 里export PATH$(npm prefix -g)/bin:$PATH echo export PATH$(npm prefix -g)/bin:$PATH ~/.bashrc8. 按場(chǎng)景選路徑并接入統(tǒng)一通道三條路走下來選擇其實(shí)很清楚。本機(jī)開發(fā)調(diào)試用常規(guī)安裝curl install.sh 或者 npm 全局裝改 config.toml 最快。單容器驗(yàn)證或者 VPS 隔離用 Docker 加預(yù)構(gòu)建鏡像省內(nèi)存也省心。生產(chǎn)環(huán)境直接上 Docker Compose配合預(yù)構(gòu)建 GHCR 鏡像和持久化卷升級(jí)就是 compose pull 加 up。不管哪條路接入 TaoToken 的動(dòng)作是一樣的拿到 Key把 base_url 指向 https://taotoken.net/api 在 config.toml 里配好 provider環(huán)境變量傳進(jìn)容器最后用 healthz、readyz 和模型列表接口三層驗(yàn)證。Key 在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 建接入細(xì)節(jié)看文檔 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你后面要長(zhǎng)期跑編碼類 Agent可以了解下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 把通道和額度一起規(guī)劃好省得中途換 Key 打斷工作流。