1. 为什么要在 Docker 里跑 OpenClaw以及 Key 管理为什么会卡住OpenClaw社区里也有人叫它 Clawdbot、Moltbot是一个可以常驻运行、能接消息平台、能调工具、能跑 Agent 流程的开源助手框架。它开箱支持 Docker官方仓库里就带了docker-compose.yml和docker-setup.sh所以把它塞进容器并不难。真正容易让人卡住的是模型 API 通道和 Key 的管理容器内的进程读不到你宿主机 shell 里的环境变量配置目录又是卷挂载的一旦 Key 写错位置表现就是「容器起来了、Web UI 能开、但一发消息就报鉴权失败或超时」。这篇面向的是本地容器化部署 AI 工具的开发者目标很明确给你一份可以直接复制的config.toml与settings.json骨架把 OpenClaw 的模型出口统一指向 TaoToken 的 API 通道再给出容器内验证连通性的具体命令和排查动作。适合谁适合已经会用docker compose、想让 OpenClaw 在容器里稳定跑起来、又不想把一堆厂商 Key 散落在各个配置文件里的人。我试过把 Key 直接塞进docker-compose.yml的environment结果每次改 Key 都要重建容器而且docker inspect就能看到明文很不优雅。后来改成「统一 Key 卷挂载配置」的结构改配置只需要重启容器宿主机和容器内的路径也清晰了。下面按这个思路走。TaoToken 在这里的角色是统一的 API 通道你只需要一个 Key就能通过兼容 OpenAI 的接口去调用不同模型OpenClaw 侧只认一个base_url和一个api_key配置骨架因此变得很干净。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。2. 前置准备目录结构、卷挂载与 TaoToken Key先把目录约定好后面所有配置都围绕它展开。OpenClaw 官方脚本默认会在宿主机创建两个目录~/.openclaw作为配置目录记忆、配置、第三方 API Key 都在这~/openclaw/workspace作为工作区目录Agent 运行时能直接读写的文件。这两个目录会以卷的形式挂进容器。我建议在项目根目录下自己建一套方便和docker-compose.yml放一起管理mkdir -p ./openclaw-data/config mkdir -p ./openclaw-data/workspace然后在docker-compose.yml里把这两个路径挂进去。下面是一份精简后的骨架重点是volumes和environment两段services: openclaw-gateway: image: openclaw:local container_name: openclaw-openclaw-gateway-1 restart: unless-stopped ports: - 18789:18789 volumes: - ./openclaw-data/config:/home/node/.openclaw - ./openclaw-data/workspace:/home/node/openclaw/workspace environment: - TAOTOKEN_API_KEY${TAOTOKEN_API_KEY} - TAOTOKEN_BASE_URLhttps://taotoken.net/api注意这里用了${TAOTOKEN_API_KEY}值从同目录的.env文件读取这样 Key 不会写死在 compose 文件里# .env TAOTOKEN_API_KEYsk-你的TaoToken密钥Key 从哪来登录 TaoToken 控制台在 API Keys 页面创建即可入口是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建 Key 的具体页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到sk-开头的字符串后填进.env别提交到 Git。注意容器内进程读的是environment注入的变量而 OpenClaw 自己的配置文件读的是卷里的config.toml。两者要指向同一个 Key否则会出现「环境变量对了但 OpenClaw 还在用旧 Key」的错位。3. 可复制的 config.toml 与 settings.json 骨架OpenClaw 的模型出口配置主要落在配置目录下的config.toml部分运行时偏好放在settings.json。下面这份骨架把模型通道统一指向 TaoToken你可以直接复制到./openclaw-data/config/config.toml# ./openclaw-data/config/config.toml [gateway] host 0.0.0.0 port 18789 [model] # 统一走 TaoToken 的 OpenAI 兼容通道 provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY # 具体模型名按你在 TaoToken 侧开通的填写 default_model gpt-4o-mini timeout_seconds 120 [model.params] temperature 0.7 max_tokens 4096 [logging] level info关键点解释一下provider用openai-compatible因为 TaoToken 的 API 通道兼容 OpenAI 的请求格式base_url填https://taotoken.net/api注意不要多加/v1之类的后缀具体路径由客户端拼接api_key_env指向环境变量名而不是把 Key 明文写进 toml这样容器重建时 Key 从.env注入配置本身可以安全地放进版本库。settings.json放运行时偏好路径同样是配置目录{ gateway: { auth: { requireToken: true } }, agent: { workspace: /home/node/openclaw/workspace, maxConcurrentTasks: 2 }, model: { fallbackModel: gpt-4o-mini, retry: { maxAttempts: 3, backoffMs: 800 } } }requireToken: true对应 Web UI 那个?token参数鉴权别关掉否则局域网里谁都能连。workspace要和 compose 里的挂载路径一致否则 Agent 写文件会写到容器临时层容器一删就没了。改完配置后重启容器让卷内容生效docker compose down docker compose up -d docker psdocker ps应该能看到openclaw-openclaw-gateway-1在跑镜像名是openclaw:local。4. 容器内验证 API 连通性从 curl 到 OpenClaw 状态配置写完不代表通道通了。最稳的验证顺序是先在容器内用curl直接打 TaoToken 的接口确认网络和 Key 没问题再看 OpenClaw 自己的状态命令。第一步进容器打一次模型列表或对话请求。用exec进 gateway 容器docker compose exec openclaw-gateway sh进去后先确认环境变量在不在echo $TAOTOKEN_API_KEY | head -c 8 echo $TAOTOKEN_BASE_URL应该能看到 Key 的前几位和https://taotoken.net/api。然后直接发一个最小请求curl -sS https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}], max_tokens: 16 }返回里如果带choices字段说明通道和 Key 都正常。如果返回 401是 Key 问题返回 404多半是base_url拼错一直挂起是容器出网被限制。第二步用 OpenClaw 自己的 CLI 看状态。官方 compose 里还有一个openclaw-cli容器专门跑管理命令注意必须在和docker-compose.yml同级的目录下执行docker compose run --rm openclaw-cli status这个命令会打印网关运行状态、已加载的模型配置。如果这里显示模型 provider 是openai-compatible且 base_url 正确说明config.toml被读到了。第三步验证 Web UI 鉴权链路。默认 UI 在 18789 端口直接访问会提示需要鉴权得带?token参数。token 丢了可以重新生成docker compose run --rm openclaw-cli dashboard --no-open把输出里的 URL 复制到浏览器打开。如果看到disconnected (1008): pairing required说明设备还没配对走下一节的排查。5. 本篇常见错排查401、pairing required 与卷路径错位错误一401 Unauthorized / invalid api key。九成是 Key 没注入进容器。先在容器内echo $TAOTOKEN_API_KEY确认非空如果为空检查.env是否和docker-compose.yml同目录、变量名是否拼对。还有一种情况是config.toml里把 Key 写成了明文但写错了而api_key_env又指向了环境变量两者冲突。统一用api_key_env别混用。错误二disconnected (1008): pairing required。这是 Web UI 设备没批准。有时openclaw-cli容器执行配对命令不生效可以换成直接进 gateway 容器跑docker compose exec openclaw-gateway \ node dist/index.js devices list输出里会有一个Pending列表记下Request那一列的 UUID然后批准docker compose exec openclaw-gateway \ node dist/index.js devices approve 6f9db1bd-a1cc-4d3f-b643-2c195262464e把 UUID 换成你自己的。批准后刷新 UI 就能进。错误三配置改了但没生效。卷挂载的路径如果和 OpenClaw 期望的不一致容器读的是镜像里的默认配置你改的宿主机文件根本没被加载。确认 compose 里挂的是/home/node/.openclaw并且config.toml确实在这个目录下。可以用docker compose exec openclaw-gateway ls -la /home/node/.openclaw看一眼。错误四容器内装包权限不足。OpenClaw 主进程以非 root 用户运行想装ripgrep之类的工具会失败。用 root 进 shelldocker compose exec -u root openclaw-gateway bash apt-get update apt-get install -y ripgrep装完退出即可注意这种改动在容器重建后会丢要持久化就写进自定义 Dockerfile。错误五模型名对不上。default_model填的模型名必须是 TaoToken 侧实际可用的。如果报model not found去模型对话页面确认可用模型清单入口是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 在那里能直接试跑并看到模型标识。6. 把通道固定下来长期编码与 Agent 场景的接入建议如果你只是偶尔跑一下 OpenClaw上面这套配置够用了。但如果你打算让它长期挂着跑编码任务或 Agent 流程建议把两件事固定下来一是 Key 的轮换方式二是接入文档的对照。Key 轮换很简单改.env里的TAOTOKEN_API_KEY然后docker compose up -d重建容器环境变量会重新注入config.toml不用动。这就是把 Key 放环境变量、配置放卷的好处。长期编码或 Agent 场景对额度和并发更敏感可以了解一下 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 按用量规划比按次调用更可控。接入细节和参数对照看官方文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你用的是 Claude Code 这类工具链对应的接入说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 思路和本文一致统一 base_urlKey 走环境变量。最后留一个我踩过的坑config.toml里base_url千万别手滑写成带/v1的地址OpenClaw 的 openai-compatible 客户端会自己拼路径多一层就 404。改完配置先docker compose exec openclaw-gateway sh进去 curl 一次比在 UI 上瞎点快得多。
