1. 为什么要在 Docker 里跑 OpenClaw：本地开发与小型团队的真实痛点
OpenClaw 是一个开源的 AI 执行式引擎，核心能力是把自然语言指令拆解成可执行的任务链，再调用模型完成自动化操作。它自带 WebUI、任务调度和渠道接入，适合做本地自动化助手、团队内部工具机器人，或者作为 Agent 类应用的后端。如果你正在搜「OpenClaw Docker 部署」，大概率已经遇到过下面这几类问题。
第一类是环境依赖冲突。OpenClaw 依赖 Node 运行时和一批系统库，直接装在宿主机上，很容易和你机器上已有的 Node 版本、Python 环境打架。我见过最典型的情况是：本机 Node 18 跑得好好的，装完 OpenClaw 之后某个老项目构建直接报错，回滚又麻烦。容器化之后，运行时被锁在镜像里，宿主机只负责提供 Docker，互不干扰。
第二类是「换台机器就重来一遍」。本地开发调通了，想搬到小团队的测试服务器上，结果发现配置文件散落在用户目录、日志路径写死、端口冲突。Docker 的价值在于把「环境 + 配置 + 数据」三件事显式声明出来，换机器只需要拉镜像、挂卷、起容器。
第三类是模型接入的 Key 管理混乱。OpenClaw 本身不绑定某一家模型，它需要你填 Base URL、API Key、Model ID。团队里几个人各自申请 Key、各自填配置，最后没人说得清哪个 Key 对应哪个环境。这篇会统一走 TaoToken 的 API 通道，用一套 Key 覆盖多个模型，配置集中管理。
三种部署方案对应三种场景：单容器docker run适合五分钟快速体验；Docker Compose 适合需要持久化、健康检查、日志轮转的小型自托管；Nginx 反向代理前置适合要暴露到公网、需要 HTTPS 和域名访问的团队。下面按「先跑起来、再跑稳、最后跑安全」的顺序展开，每一步都给可复制的命令和配置。
需要提前说明的是，本文所有模型侧接入都通过 TaoToken 完成，官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end ，API 地址统一用 https://taotoken.net/api 。你不需要在容器里装任何额外的网络工具，OpenClaw 通过标准 HTTP 请求访问这个 API 地址即可。
2. TaoToken 前置准备：统一 Key 与 API 通道怎么配
在动 Docker 之前，先把模型侧的「通行证」准备好，否则容器起来了也调不通模型。TaoToken 在这里扮演的角色是统一的 API 网关：你拿到一个 Key，配一个 Base URL，就能在 OpenClaw 里切换不同模型，不用为每个模型单独维护一套凭证。
第一步是获取 API Key。打开 https://taotoken.net/api-keys ，登录后创建一个新的 Key。建议按用途命名，比如openclaw-dev、openclaw-prod，这样后面排查问题时能一眼看出是哪个环境在用。创建完成后立刻复制保存，页面刷新后完整 Key 不会再显示。
第二步是确认 Base URL。TaoToken 的 API 根地址是https://taotoken.net/api，注意这里不带任何查询参数。OpenClaw 在配置模型时通常需要填两个东西：一个是 API Base（有些版本叫 Endpoint），填https://taotoken.net/api；另一个是 API Key，填上一步复制的值。Model ID 按你实际要用的模型填，比如claude-sonnet-4-5、gpt-4o这类标识，具体可用列表可以在模型对话页面里查看。
第三步是验证 Key 是否可用。在宿主机上先用 curl 打一发，确认网络和凭证都没问题，再去配容器：
curl -s https://taotoken.net/api/v1/models \ -H "Authorization: Bearer sk-你的Key" \ | head -c 500如果返回一段 JSON，里面能看到模型列表，说明 Key 和通道都正常。如果返回 401，检查 Key 是否复制完整、有没有多余空格；如果超时，检查宿主机出网是否正常。这一步在容器外做，能把「网络问题」和「容器配置问题」提前分开。
第四步是决定配置注入方式。单容器方案里，我建议用环境变量传入，启动时-e OPENCLAW_API_BASE=... -e OPENCLAW_API_KEY=...；Compose 方案里，写进.env文件再由 compose 读取，避免 Key 硬编码进 YAML；生产方案里，Key 只放在服务器本地的.env，权限设成 600，不进 Git。
这里有个容易踩的坑：OpenClaw 不同版本读取配置的字段名可能不一样，有的版本在 WebUI 里填，有的版本读环境变量。稳妥做法是先把容器跑起来，进 WebUI 的「设置」页面看它实际要求哪些字段，再回头补环境变量。如果你用的是 Claude Code 这类需要settings.json的工具做周边集成，配置结构是另一套，但 Base URL 和 Key 的来源是一样的。
关于 Coding Plan：如果你打算把 OpenClaw 长期用于编码类 Agent 任务，可以了解 https://taotoken.net/coding-plan ，它面向的是持续性的编码调用场景。短期验证模型连通性，直接用模型对话页面 https://taotoken.net/chat 就够了。
3. 三种 Docker 部署方案的可复制配置
3.1 方案一：单容器快速启动（docker run）
适合场景：本地开发、五分钟体验、临时演示。核心是一条docker run，把端口、数据卷、模型配置三件事说清楚。
先创建数据卷，保证容器删了配置还在：
docker volume create openclaw-data然后拉镜像并启动。下面这条命令把容器内 18789 端口映射到宿主机 18700，挂载数据卷，并通过环境变量注入 TaoToken 的 API 配置：
docker run -d \ --name openclaw \ -p 18700:18789 \ -v openclaw-data:/root/.openclaw \ -e OPENCLAW_API_BASE="https://taotoken.net/api" \ -e OPENCLAW_API_KEY="sk-你的Key" \ -e OPENCLAW_MODEL="claude-sonnet-4-5" \ --restart unless-stopped \ ghcr.io/openclaw/openclaw:latest启动后查看日志，找到自动生成的访问令牌：
docker logs openclaw 2>&1 | grep -i token日志里会出现类似"token": "xxxxx"的字段，复制下来。浏览器打开http://127.0.0.1:18700，粘贴令牌登录。进「设置」页面确认 API Base 和 Key 已经带进去了，如果没有，手动补填一次并保存。
这个方案的优点是快，缺点是所有配置都在命令行里，改一次要重建容器。如果你要频繁调整模型参数，直接跳到方案二。
3.2 方案二：Docker Compose 多服务编排
适合场景：小型团队自托管、需要持久化 + 健康检查 + 日志轮转。Compose 把配置写成文件，改完up -d就生效，不用记一长串参数。
先建目录结构：
mkdir -p /opt/openclaw/{config,logs,data} cd /opt/openclaw创建.env文件存放敏感信息，权限收紧：
cat > .env <<'EOF' OPENCLAW_API_BASE=https://taotoken.net/api OPENCLAW_API_KEY=sk-你的Key OPENCLAW_MODEL=claude-sonnet-4-5 EOF chmod 600 .env创建docker-compose.yml：
services: openclaw: image: ghcr.io/openclaw/openclaw:latest container_name: openclaw-gateway restart: unless-stopped env_file: - .env environment: - NODE_ENV=production volumes: - openclaw_home:/root/.openclaw - ./config:/root/.openclaw/config:ro - ./logs:/root/.openclaw/logs:rw ports: - "127.0.0.1:18789:18789" healthcheck: test: ["CMD-SHELL", "wget -qO- http://localhost:18789/health || exit 1"] interval: 30s timeout: 5s retries: 3 start_period: 20s logging: driver: json-file options: max-size: "100m" max-file: "5" volumes: openclaw_home:注意端口绑定写的是127.0.0.1:18789:18789，只监听本机，公网访问交给方案三的 Nginx。启动：
docker compose up -d docker compose psps输出里 STATUS 显示healthy才算真正就绪。如果一直是starting，等 30 秒再看；如果变成unhealthy，直接看日志：
docker compose logs --tail=100 openclaw健康检查失败最常见的原因是容器内 18789 没起来，或者/health路径不对。先确认容器内进程在监听：
docker compose exec openclaw wget -qO- http://localhost:18789/health3.3 方案三：Nginx 反向代理前置 + HTTPS
适合场景：公网访问、域名、多服务共用 443。核心原则是 OpenClaw 容器只监听 127.0.0.1，Nginx 负责 TLS 终止和转发。
安装 Nginx（以 Ubuntu 为例）：
sudo apt update && sudo apt install nginx -y创建/etc/nginx/sites-available/openclaw：
server { listen 443 ssl http2; server_name openclaw.example.com; ssl_certificate /etc/letsencrypt/live/openclaw.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/openclaw.example.com/privkey.pem; location / { proxy_pass http://127.0.0.1:18789; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 300s; } } server { listen 80; server_name openclaw.example.com; return 301 https://$server_name$request_uri; }Upgrade和Connection两行是给 WebSocket 用的，OpenClaw 的实时任务流依赖长连接，漏了这两行会出现页面能开但任务状态不刷新。启用配置并测试：
sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx防火墙只放 80 和 443，18789 不要对公网开放：
sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw reload证书可以用 Let's Encrypt 免费签发，签发前确保域名已经解析到这台服务器。如果你在容器里跑 Nginx 而不是宿主机，proxy_pass要指向 compose 网络里的服务名，比如http://openclaw:18789，而不是127.0.0.1。
4. 验证请求与成功结果：从容器健康到模型连通
部署完成不等于能用，要分三层验证：容器活着、服务响应、模型调通。
第一层，容器状态。Compose 方案下：
docker compose ps期望看到openclaw-gateway的 STATUS 是Up ... (healthy)。单容器方案下：
docker inspect --format='{{.State.Health.Status}}' openclaw如果输出healthy，第一层通过。
第二层，HTTP 接口连通。在宿主机上直接打健康检查端点：
curl -i http://127.0.0.1:18789/health期望返回HTTP/1.1 200 OK，body 里带{"status":"ok"}之类的字段。如果走 Nginx，换成域名再打一次：
curl -i https://openclaw.example.com/health这一步能验证 Nginx 转发链路是否通。如果 502，说明 Nginx 连不上后端，检查proxy_pass地址和容器端口绑定；如果 301 循环，检查 HTTP 跳 HTTPS 的配置。
第三层，模型调用。登录 WebUI，在「设置」里确认 API Base 是https://taotoken.net/api，Key 已填，Model ID 正确。然后新建一个最简单的任务，比如让它「列出当前目录文件」或「回复一句测试文本」。观察任务日志，成功时能看到模型返回的内容；失败时日志里会有 HTTP 状态码。
如果不想开浏览器，也可以直接在宿主机上用 curl 验证 TaoToken 通道：
curl -s https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "ping"}] }' | head -c 300返回里带choices字段就说明模型侧通了。这一步和容器无关，但能帮你快速定位问题出在「容器到 TaoToken」还是「TaoToken 到模型」。
三层都通过后，建议做一次重启验证，确认配置持久化生效：
docker compose restart openclaw sleep 30 docker compose ps重启后仍然是healthy，且 WebUI 里模型配置还在，说明数据卷挂载正确。
5. 本篇常见错误排查：401、proxy failed、choices 为空、OAuth 报错
这一节按真实报错来对，每条给出定位方法和修复动作。
401 Unauthorized。出现在模型调用日志或 curl 返回里。原因通常是 Key 不对、Key 前后有空格、或者用了别的环境的 Key。先在宿主机上单独 curl TaoToken 的/v1/models验证 Key 本身有效；如果宿主机通、容器不通，检查环境变量有没有正确注入：
docker compose exec openclaw env | grep OPENCLAW如果输出里OPENCLAW_API_KEY是空的，说明.env没被读到，检查env_file路径和文件权限。注意.env里不要给值加引号，除非值本身含空格。
local proxy failed / connection refused。容器内访问https://taotoken.net/api失败。先在容器内测出网：
docker compose exec openclaw wget -qO- https://taotoken.net/api/v1/models如果容器内不通、宿主机通，检查 Docker 的 DNS 配置，或者容器是否被限制出网。Compose 默认网络是通的，除非你手动加了internal: true。另外确认没有在容器里配什么奇怪的代理环境变量，env | grep -i proxy看一下，有就删掉。
reading choices 报错 / choices 为空。这类报错通常出现在解析模型响应时，说明请求发出去了但返回结构不符合预期。常见原因有三个：Model ID 写错，TaoToken 返回了错误对象而不是正常响应；请求体格式不对，比如messages字段拼错；或者模型名在当前 Key 的权限范围外。先用第 4 节的 curl 命令确认返回结构，再对照 OpenClaw 日志里实际发出的请求体。如果日志里能看到"error"字段，按错误信息调整。
OAuth 相关报错。如果你在 OpenClaw 里配置了需要 OAuth 的渠道（比如某些消息平台），报错可能和模型接入无关。先确认模型侧已经通了，再单独排查渠道授权。OAuth 回调地址要和你实际访问的域名一致，走 Nginx 的话，回调地址填https://openclaw.example.com/...，不要填127.0.0.1。
健康检查一直 unhealthy。除了前面说的/health路径问题，还有一种情况是start_period太短，容器还没初始化完就被判定失败。把start_period调到 60s 试试。另外检查挂载的config目录权限，只读挂载如果文件属主不对，容器内进程可能读不到配置直接退出。
Nginx 502 Bad Gateway。按顺序查：容器是否在跑（docker compose ps）、端口是否监听（ss -lntp | grep 18789）、proxy_pass地址是否正确、SELinux 是否拦截（setsebool -P httpd_can_network_connect 1）。如果是容器化 Nginx，确认两个容器在同一个 Docker 网络里。
CC Switch / Cline MCP / Codex auth.json 场景。如果你在 OpenClaw 之外还用这些工具做周边集成，配置三件套是固定的：Base URL 填https://taotoken.net/api，Key 填 TaoToken 的 Key，Model ID 填你要用的模型。auth.json这类文件注意不要提交到 Git，权限设 600。MCP 直连生产库这种操作不要做，OpenClaw 的任务执行范围要限制在可控目录内。
6. 长期使用建议与接入入口
跑通之后，有几件事值得固化下来。第一，把.env和docker-compose.yml放进版本控制时，.env一定要进.gitignore，只提交.env.example。第二，日志轮转参数别省，max-size: 100m和max-file: 5能防止磁盘被日志写满。第三，定期docker compose pull更新镜像，更新前先备份数据卷。
如果你要把 OpenClaw 用于持续性的编码或 Agent 任务，建议走 Coding Plan，入口在 https://taotoken.net/coding-plan ，它面向的是长期、高频的调用场景。日常验证模型是否可用，直接用模型对话页面 https://taotoken.net/chat 最快。API Key 的创建和管理在 https://taotoken.net/api-keys ，接入文档在 https://taotoken.net/doc ，遇到配置字段不确定的时候以文档为准。
最后提醒一点：OpenClaw 容器只监听 127.0.0.1，公网访问一律走 Nginx 反代加 HTTPS，18789 端口不要直接暴露。模型侧的 Key 只放在服务器本地.env，不要写进镜像、不要写进 compose 文件、不要贴到聊天记录里。按这三条守住，这套容器化部署就能稳定跑下去。
