1. 为什么我把 OpenClaw 塞进 Docker一次本地 AI 工具链的踩坑复盘OpenClaw 是一个可以本地运行、支持多渠道接入的 AI 助手网关能对接飞书、Slack 等聊天工具也能挂载各种模型后端。它适合谁适合想把 AI 助手私有化部署、又不想被环境依赖折磨的开发者。我最早是在宿主机上直接跑 OpenClaw 的Node.js 版本、Git 依赖、端口冲突轮番上阵换一台机器就得重来一遍。后来改成 Docker 容器部署才算真正实现零配置启动——镜像里该装的都装好了我只需要挂载配置、映射端口、改一下 API 端点。这篇要解决的核心问题有三个第一用 docker-compose 把 OpenClaw 跑起来配置可复制、可版本管理第二把模型 API 端点从默认地址改到 TaoToken 统一通道让请求走一个入口第三用一次真实的对话请求验证服务连通性确认不是容器起来了但模型调不通。我试过在三种环境里部署本地 Mac、Ubuntu 服务器、以及一台低配云主机。结论是 Docker 方案在迁移成本上碾压本地安装——镜像即服务配置即代码。下面从环境准备讲到验证请求每一步都给完整命令和参数说明你可以直接抄。2. TaoToken 前置准备API Key、Base URL 与模型 ID 三件套在把 OpenClaw 接进 TaoToken 之前你得先拿到三样东西API Key、Base URL、Model ID。这三件套缺一不可后面配置文件里全都要填。先说 Base URL。TaoToken 的 API 端点是https://taotoken.net/api注意这里不带任何查询参数就是干净的 API 根路径。OpenClaw 里配置模型端点时填的就是这个地址。官网入口是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册和查看文档都从这里进。再说 API Key。登录后进控制台在 API Keys 页面创建一个新 Key。创建时建议给 Key 起个能认出来的名字比如openclaw-docker方便以后排查是哪个服务在用。Key 只在创建时完整显示一次复制下来存好后面写进环境变量或配置文件。最后是 Model ID。TaoToken 支持多种模型你在模型列表里选一个适合编码或对话的把它的 ID 记下来。OpenClaw 的配置里model字段填的就是这个 ID。如果你不确定选哪个先用一个通用的对话模型跑通链路再按需换。注意API Key 属于敏感信息不要直接硬编码进 docker-compose.yml 提交到 Git。推荐用.env文件管理或者用环境变量注入。下面配置示例里我会用${TAOTOKEN_API_KEY}这种占位写法。拿到三件套后建议先在宿主机上用 curl 测一下 Key 是否有效避免容器里报错时还要分辨是网络问题还是 Key 问题curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer ${TAOTOKEN_API_KEY} \ -H Content-Type: application/json \ -d { model: 你的模型ID, messages: [{role: user, content: ping}] }如果返回里有choices字段说明 Key 和端点都没问题可以进下一步了。如果返回 401检查 Key 是否复制完整如果连接超时检查网络出口。3. 可复制配置docker-compose.yml 与环境变量模板这一节是全文的核心给你一份可以直接用的 docker-compose 配置。我把它拆成两部分.env文件管敏感变量docker-compose.yml管服务定义。这样配置可以进 GitKey 不会泄露。先建目录结构mkdir -p ~/openclaw-docker/workspace cd ~/openclaw-docker创建.env文件填入你的三件套# .env TAOTOKEN_API_KEYsk-你的实际Key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODEL你的模型ID OPENCLAW_GATEWAY_PORT18789创建docker-compose.ymlversion: 3.8 services: openclaw: image: openclaw/openclaw:latest container_name: openclaw ports: - ${OPENCLAW_GATEWAY_PORT}:18789 volumes: - openclaw-data:/root/.openclaw - ./workspace:/workspace environment: - OPENCLAW_GATEWAY_PORT18789 - NODE_ENVproduction - OPENCLAW_MODEL${TAOTOKEN_MODEL} - OPENCLAW_API_BASE${TAOTOKEN_BASE_URL} - OPENCLAW_API_KEY${TAOTOKEN_API_KEY} restart: unless-stopped healthcheck: test: [CMD, curl, -f, http://localhost:18789/] interval: 30s timeout: 10s retries: 3 start_period: 40s logging: driver: json-file options: max-size: 100m max-file: 3 volumes: openclaw-data:这里有几个关键点要说明。OPENCLAW_API_BASE指向 TaoToken 的 API 根路径OpenClaw 会基于这个地址拼接具体的请求路径。OPENCLAW_API_KEY从.env注入容器内进程能读到。volumes里openclaw-data是命名卷持久化 OpenClaw 的内部状态./workspace是绑定挂载方便你在宿主机直接看工作区文件。如果你更习惯用配置文件而不是环境变量OpenClaw 也支持挂载openclaw.json。在宿主机创建~/.openclaw/openclaw.json{ model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的实际Key, modelId: 你的模型ID }, gateway: { port: 18789 } }然后把 compose 里的 environment 段换成挂载volumes: - ~/.openclaw:/root/.openclaw - ./workspace:/workspace两种方式二选一即可。环境变量方式适合 CI/CD 自动化配置文件方式适合手动维护、需要版本管理的场景。我实测下来环境变量优先级高于配置文件混用时以环境变量为准。启动服务docker-compose up -d查看状态docker-compose ps预期看到openclaw状态是Up (healthy)。如果还是starting等 40 秒健康检查的start_period过去再看。4. 验证请求从容器日志到一次真实对话容器起来不等于服务可用必须做一次端到端验证。我分三步走看日志、查网关状态、发对话请求。第一步看启动日志docker-compose logs -f openclaw预期输出里能看到网关监听端口、模型加载、工具注册等信息。如果看到Gateway is running on port 18789说明网关起来了。按 CtrlC 退出日志跟随。第二步检查网关健康状态curl http://localhost:18789/返回一个 JSON 或简单文本说明 HTTP 服务在响应。如果连接被拒绝检查端口映射和容器状态。第三步发一次真实对话请求。OpenClaw 的网关通常提供兼容 OpenAI 的接口你可以直接打curl -X POST http://localhost:18789/v1/chat/completions \ -H Content-Type: application/json \ -d { model: ${TAOTOKEN_MODEL}, messages: [{role: user, content: 用一句话介绍你自己}] }如果返回里有choices[0].message.content说明整条链路通了请求从宿主机进容器网关网关转发到 TaoToken 的 API 端点模型返回结果再原路回来。你也可以进容器内部验证配置是否生效docker exec -it openclaw env | grep OPENCLAW预期看到OPENCLAW_API_BASEhttps://taotoken.net/api和你的模型 ID。如果这里显示的是默认值说明.env没被 compose 读到检查.env和docker-compose.yml是否在同一目录。提示验证阶段建议把日志级别调高方便看请求转发细节。可以在 environment 里加LOG_LEVELdebug验证完再改回info。5. 常见报错排查401、local proxy failed 与 reading choices这一节列几个我实际遇到过的报错以及对应的排查路径。你大概率会碰到其中一两个。报错一401 Unauthorized{error:{message:Invalid API key,type:invalid_request_error}}原因通常是 API Key 没传对。排查顺序先docker exec -it openclaw env | grep API_KEY确认容器内读到的 Key 和你预期一致再检查.env里有没有多余空格或引号最后用第 2 节的 curl 命令在宿主机直接测 Key排除 Key 本身失效。如果宿主机 curl 能通、容器内不通那就是环境变量注入的问题。报错二local proxy failedError: local proxy failed: dial tcp: connection refused这个报错说明 OpenClaw 尝试连接某个本地代理或上游地址失败了。常见原因是OPENCLAW_API_BASE填错比如填成了http://localhost:xxxx而不是 TaoToken 的地址。检查配置里的 Base URL 是不是https://taotoken.net/api。另一个可能是容器网络模式问题如果你用了network_mode: host又和宿主机端口冲突也会出现类似错误。默认 bridge 模式即可。报错三reading choicesError: reading choices: unexpected end of JSON input这个报错通常出现在解析上游响应时。原因可能是上游返回了非 JSON 内容比如 HTML 错误页或者响应被截断。排查先用 curl 直接打 TaoToken 端点看返回是不是合法 JSON再检查 OpenClaw 日志里有没有记录原始响应体。如果上游返回 200 但内容为空可能是模型 ID 填错导致上游返回了空结果。报错四OAuth 相关错误Error: OAuth token exchange failed如果你在 OpenClaw 里配了需要 OAuth 的渠道比如某些聊天平台而 OAuth 回调地址没配对会报这个。Docker 环境下回调地址要填宿主机可访问的地址不能填localhost因为 OAuth 服务端是从外部回调的。用你的服务器公网 IP 或域名。报错五容器启动后立即退出docker-compose ps # 状态显示 Exit (1)先看日志docker-compose logs openclaw。常见原因是配置文件 JSON 语法错误比如多了个逗号。用python -m json.tool ~/.openclaw/openclaw.json校验一下。另一个原因是端口被占用lsof -i :18789查一下换个端口映射即可。排查通用思路先确认容器内环境变量再确认宿主机到容器的网络最后确认容器到 TaoToken 的出网。三层都通问题基本就定位了。6. 把链路固定下来接入文档、模型对话与 Coding Plan 的分工配置跑通之后建议把这条链路固定成日常工具。我的做法是OpenClaw 容器常驻配置进 GitKey 用.env管理换机器时git clonedocker-compose up -d两分钟恢复。如果你在接入过程中卡在某个报错优先查接入文档里面有针对不同错误码的说明。文档入口在 TaoToken 官网的文档区从https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content进去后找接入文档。想先验证模型效果、不急着写代码的可以直接用模型对话页面把同样的模型 ID 和 Key 填进去发几条消息看看返回质量确认模型选型没问题再回容器里配。如果你打算长期用 OpenClaw 做编码助手或 Agent 任务Coding Plan 更划算它针对高频调用做了额度优化。API Keys 管理页面则用来轮换 Key、查看用量建议定期检查避免 Key 泄露后还在被消耗。最后给一个实用技巧把docker-compose.yml和.env.example不含真实 Key一起提交到仓库.env加进.gitignore。新同事拉下来只需复制.env.example为.env、填上自己的 Key就能跑起一套一模一样的环境。这才是零配置启动的真正含义——配置标准化而不是没有配置。
