1. 从源码到容器OpenClaw 部署到底卡在哪OpenClaw 是一个把大模型能力封装成网关服务的开源项目你可以把它理解成一个“模型路由器”对外暴露统一的 HTTP 接口和 Control UI对内对接不同的模型通道。它适合谁适合那些不想在每个脚本里硬编码 API Key、希望把模型调用集中管理、并且需要多设备访问同一套配置的开发者。而 Docker 部署 OpenClaw 的核心价值就是让这套网关服务从“本机能跑”变成“换台机器也能跑”。但真正动手时问题往往不在“会不会敲 docker 命令”而在三个环节第一源码编译阶段依赖装不全dist 目录出不来第二迁移时只搬了镜像忘了配置目录和环境变量结果 Token 全丢第三容器起来了但模型通道没配通请求一直报错。我试过在一台干净的 Ubuntu 上从零走一遍光是编译那步就踩了两次坑——一次是 pnpm 版本不对一次是构建缓存污染。这篇内容就围绕这三个环节展开先讲清楚 OpenClaw 容器化落地的完整链路再给出可复制的 Dockerfile 和 compose 骨架然后重点说迁移前后目录怎么对照最后落到 config.toml 里 TaoToken 通道的配置片段以及容器内怎么验证连通性。你跟着做能拿到一个可迁移、可复现、Key 统一管理的 OpenClaw 容器实例。需要提前说明的是OpenClaw 的网关默认监听 18789 端口Control UI 需要 Token 登录。如果你打算多设备访问要么配 HTTPS要么在可信网络里开 allowInsecureAuth。这些安全细节后面会展开先建立整体认知。2. TaoToken 前置准备统一 Key 接入 OpenClaw 的模型通道在讲 Docker 配置之前得先把 TaoToken 这条通道说清楚。OpenClaw 本身不生产模型能力它需要对接一个上游通道。TaoToken 在这里扮演的角色就是提供统一的 API 入口让你在 OpenClaw 的 config.toml 里只配一份 Base URL 和 Key就能调用多个模型。你需要先拿到两样东西API Key 和 Base URL。API Key 在控制台生成Base URL 固定为https://taotoken.net/api。注意这里不要加任何多余路径OpenClaw 的通道配置会自己拼接/v1/chat/completions这类端点。具体操作路径打开https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite登录后创建一个新 Key复制保存。这个 Key 只显示一次丢了就得重新生成。然后确认你的账户里有可用额度否则后面验证请求会返回 401 或余额不足。为什么要在 Docker 部署前先准备这个因为 OpenClaw 的 config.toml 是挂载进容器的如果你在容器启动后才改配置要么重启容器要么进容器手动改都麻烦。提前把 Key 和 Base URL 准备好写进配置文件容器一启动就能直接连通。这里有个细节OpenClaw 的配置目录默认在/root/.openclaw容器里也是这个路径。你可以在宿主机上先建好这个目录把 config.toml 放进去然后用 volume 挂载。这样迁移的时候直接打包这个目录就行不用进容器翻文件。另外TaoToken 的通道配置在 OpenClaw 里属于 provider 级别。你需要在 config.toml 里定义一个 provider类型填 openai 兼容格式base_url 填https://taotoken.net/apiapi_key 填你生成的 Key。模型 ID 可以填gpt-4o或claude-3-5-sonnet这类具体看你账户支持的模型列表。如果不确定可以先在模型对话页面测试一下https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite。3. 可复制配置Dockerfile、compose 与 config.toml 片段这一节直接给可复制的配置。先看 Dockerfile它的作用是把 TypeScript 源码编译成 JavaScript然后打包成镜像。注意基础镜像选 node:20-bookworm因为 OpenClaw 依赖的一些原生模块需要较新的 glibc。FROM node:20-bookworm AS builder WORKDIR /app RUN corepack enable corepack prepare pnpm9.1.0 --activate COPY package.json pnpm-lock.yaml ./ RUN pnpm install --frozen-lockfile COPY . . RUN pnpm build FROM node:20-bookworm-slim WORKDIR /app RUN corepack enable corepack prepare pnpm9.1.0 --activate COPY --frombuilder /app/dist ./dist COPY --frombuilder /app/node_modules ./node_modules COPY --frombuilder /app/package.json ./ EXPOSE 18789 CMD [node, dist/index.js, gateway, --config, /root/.openclaw/config.toml]这个 Dockerfile 分两阶段builder 阶段装依赖并编译runtime 阶段只拷贝 dist 和 node_modules镜像体积能小一半。编译命令是pnpm build对应源码里的docker-setup.sh脚本做的事。如果你直接跑./docker-setup.sh它内部也是调 pnpm 编译再 docker build但手动写 Dockerfile 更可控。接下来是 docker-compose.yml它负责启动网关和 CLI 两个服务并挂载配置目录。version: 3.8 services: openclaw-gateway: image: openclaw:local container_name: openclaw-gateway ports: - 18789:18789 volumes: - /root/.openclaw:/root/.openclaw environment: - OPENCLAW_CONFIG/root/.openclaw/config.toml restart: unless-stopped openclaw-cli: image: openclaw:local container_name: openclaw-cli volumes: - /root/.openclaw:/root/.openclaw entrypoint: [node, dist/index.js, cli] profiles: - cli注意 CLI 服务用了 profiles默认不启动需要时用docker-compose --profile cli run openclaw-cli进入。网关服务挂载了/root/.openclaw这样宿主机上的配置直接进容器。然后是 config.toml 里的 TaoToken 通道片段。这个文件放在/root/.openclaw/config.toml容器启动时读取。[gateway] port 18789 host 0.0.0.0 [gateway.controlUi] allowInsecureAuth false allowedOrigins [http://localhost:18789, http://127.0.0.1:18789] [[providers]] name taotoken type openai baseUrl https://taotoken.net/api apiKey sk-你的TaoToken密钥 models [gpt-4o, claude-3-5-sonnet] [agents.default] provider taotoken model gpt-4o这里的关键字段baseUrl填https://taotoken.net/api不要加/v1apiKey填你生成的 Keymodels列出你要用的模型 ID。agents.default指定默认走哪个 provider 和模型。如果你需要多设备访问把allowedOrigins改成你的实际访问地址比如http://172.244.44.35:18789。但注意开allowInsecureAuth true只适合可信内网公网环境建议配 HTTPS。4. 验证请求容器内连通性测试与成功结果配置写完后先构建镜像再启动容器。构建命令docker build -t openclaw:local .构建完成后检查镜像docker images | grep openclaw你应该看到openclaw:local这一行。然后启动网关docker-compose up -d openclaw-gateway启动后确认容器状态docker-compose ps如果状态是 Up说明网关进程没崩。接下来进容器验证 TaoToken 通道是否连通。最直接的方式是用 CLI 发一条测试请求docker-compose exec openclaw-gateway node dist/index.js cli chat --provider taotoken --model gpt-4o --message 你好测试连通性如果配置正确你会看到模型返回的文本。如果报错先看错误类型401 说明 Key 不对或没额度连接超时说明 Base URL 写错或网络不通reading choices报错说明返回格式不是 OpenAI 兼容格式检查 baseUrl 是否多了/v1。另一种验证方式是直接 curl 网关的 HTTP 接口docker-compose exec openclaw-gateway curl -s http://127.0.0.1:18789/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -d {model:gpt-4o,messages:[{role:user,content:ping}]}如果返回 JSON 里有choices字段说明整条链路通了。注意这里的 Authorization 头用的是 TaoToken 的 Key不是 OpenClaw 自己的 Dashboard Token两者不要混淆。最后验证 Control UI 的 Dashboard Token 生成docker-compose exec openclaw-gateway node dist/index.js dashboard --no-open输出类似Dashboard URL: http://127.0.0.1:18789/#tokenxxxx。把 URL 拷到浏览器能打开 Control UI 并登录说明网关和 UI 都正常。5. 本篇常见错排查401、local proxy failed 与 OAuth 报错部署过程中最容易撞上的几类报错这里逐个对照。第一类401 Unauthorized。这个通常出现在两个位置一是 TaoToken 通道的 Key 填错或过期二是 OpenClaw 的 Dashboard Token 没带对。区分方法看报错来源如果是 CLI chat 报 401检查 config.toml 里的apiKey是否和 TaoToken 控制台一致如果是浏览器访问 Control UI 报 401检查 URL 里的 token 参数是否完整。还有一种情况是 Key 有额度但模型 ID 不在账户支持列表里也会返回 401 或 403这时候去模型对话页面确认可用模型。第二类local proxy failed或连接超时。这个报错说明容器内访问https://taotoken.net/api不通。先确认容器能出网docker-compose exec openclaw-gateway curl -I https://taotoken.net/api。如果 curl 也超时检查宿主机的 DNS 和防火墙规则。注意不要在容器里配任何代理环境变量OpenClaw 的通道配置本身不需要代理。第三类reading choices或unexpected response format。这个报错说明上游返回的不是标准 OpenAI 格式。最常见原因是 baseUrl 写成了https://taotoken.net/api/v1多了一层路径。正确写法是https://taotoken.net/apiOpenClaw 会自己拼/v1/chat/completions。改完配置后重启容器docker-compose restart openclaw-gateway。第四类OAuth 相关报错比如OAuth token exchange failed。OpenClaw 某些版本支持 OAuth 登录上游但 TaoToken 通道用的是 API Key 模式不需要 OAuth。如果你在 config.toml 里误配了authType oauth改成authType apiKey或直接删掉这行。另外Codex 的 auth.json 如果被挂载进容器也可能干扰 OpenClaw 的认证流程建议迁移时不要把无关的 auth.json 放进/root/.openclaw。第五类control ui requires device identity。这是 Control UI 的设备身份校验默认开启。如果你在 HTTP 环境下访问浏览器会拒绝。解决办法是在 config.toml 里加allowInsecureAuth true但仅限可信网络。公网环境建议用 HTTPS 反向代理或者用 Tailscale Serve 这类内网穿透方案。第六类unauthorized: too many failed authentication attempts。这是 Token 登录失败次数过多触发的临时锁定。等几分钟再试或者重新生成 Dashboard Tokendocker-compose exec openclaw-gateway node dist/index.js dashboard --no-open。如果多设备共用同一个 Token也容易触发这个限制建议每个用户生成独立 Token。6. 迁移与长期使用镜像打包、目录对照与 Coding Plan迁移到另一台机器时只docker save镜像是不够的。镜像里只有代码和依赖配置、Token、Workspace 数据都在/root/.openclaw目录里。完整的迁移分三步。第一步在源机器上保存镜像docker save openclaw:local -o openclaw.tar第二步打包配置目录和 compose 文件tar -czf openclaw-config.tar.gz /root/.openclaw docker-compose.yml .env注意.env文件如果存在里面可能有环境变量一起打包。然后传到目标机器scp openclaw.tar openclaw-config.tar.gz usertarget:/home/user/openclaw/第三步在目标机器上加载镜像并恢复配置docker load -i openclaw.tar tar -xzf openclaw-config.tar.gz -C / cd /home/user/openclaw docker-compose up -d迁移前后目录对照源机器/root/.openclaw/config.toml对应目标机器同路径源机器docker-compose.yml里的 volume 挂载路径要保持一致否则容器读不到配置。如果目标机器的用户目录不同改 compose 文件里的挂载路径同时改 config.toml 里的路径引用。长期使用的话如果你需要频繁调用模型做编码或 Agent 任务可以关注 Coding Plan 这类长期方案https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite。它适合把 OpenClaw 作为日常开发网关的场景Key 统一管理不用每次换机器都重新配。最后提醒一点迁移后第一次启动先跑一遍连通性验证命令确认 TaoToken 通道正常。如果报 401检查目标机器上的 config.toml 里的 Key 是否完整拷贝有时候 scp 会漏掉隐藏文件。确认无误后OpenClaw 就可以在目标机器上稳定运行了。