1. 为什么要在本地用 Docker 跑 OpenClaw
OpenClaw 是一个开源的 AI Agent 网关，能把你常用的模型、工具、会话记忆统一到一个可访问的 Web 控制台里。它本身不训练模型，而是扮演“调度中枢”的角色：你给它一个模型通道，它就能把对话、Agent 任务、插件调用串起来。适合谁？适合想自己掌控数据、又不想被单一平台绑死的开发者，也适合想低成本体验 Agent 工作流的技术爱好者。
我试过直接在裸机上装 OpenClaw，依赖 Node、Python、系统库，版本一冲突就卡住。后来换成 Docker 方案，环境隔离干净，迁移也方便。这篇就按“从零到可用”的闭环来写：先准备 Docker 环境，再拉取 HuggingFace 上的模型配置，最后通过 TaoToken 统一 Key/API 通道接入，让 OpenClaw 能稳定调用模型。
核心检索词先明确：OpenClaw 部署、Docker 环境准备、HuggingFace 模型接入、TaoToken 统一通道。这几个词会贯穿全文，你照着做就能跑通。
先说整体架构。OpenClaw 跑在容器里，对外暴露一个端口（默认 7860）。容器内通过openclaw.json读取模型配置，配置里的baseUrl和apiKey指向模型服务。模型服务这块，你可以用 HuggingFace 上的推理端点，也可以走 TaoToken 的统一 API 通道。TaoToken 的作用是把多家模型的 Key 收敛成一个入口，省得你到处注册、到处换 Key。
为什么推荐 Docker + TaoToken 组合？Docker 解决“环境一致性”，TaoToken 解决“Key 管理混乱”。两者叠加，你换模型时只改一个baseUrl和model id，不用重装环境。下面进入前置准备。
2. TaoToken 前置准备与统一 Key 申请
在动手写docker-compose.yml之前，先把模型通道准备好。OpenClaw 需要一个兼容 OpenAI 协议的baseUrl和apiKey。TaoToken 提供的就是这个统一入口，官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 根地址是 https://taotoken.net/api 。
第一步，注册并登录。打开官网，完成账号注册。登录后进入控制台，找到 API Keys 页面。这个页面就是生成 Key 的地方，路径是 https://taotoken.net/console/api-keys 。点“创建新 Key”，复制保存。注意：Key 只显示一次，丢了只能重建。
第二步，确认你要用的模型 ID。TaoToken 的模型列表在文档里有，路径是 https://taotoken.net/doc 。常见的有gpt-4o、claude-3-5-sonnet这类。你选一个记下来，后面写进openclaw.json的models[].id字段。
第三步，理解 Base URL 的写法。TaoToken 的 API 根是https://taotoken.net/api，但 OpenClaw 配置里通常要写到/v1这一层。所以baseUrl填https://taotoken.net/api/v1。如果你用的是 OpenAI 兼容的 completions 接口，这个地址就能直接用。
这里有个坑要提前说：有些教程让你填https://taotoken.net/api不带/v1，结果 OpenClaw 请求时拼成/chat/completions就 404。正确做法是baseUrl写到/v1，OpenClaw 内部会拼/chat/completions。这个细节在排障章节还会展开。
第四步，验证 Key 是否可用。在终端里跑一条 curl，确认通道通：
curl -s https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 16 }'如果返回里有choices字段，说明 Key 和通道都正常。如果返回 401，检查 Key 是否复制完整；如果返回 404，检查baseUrl是否漏了/v1。
第五步，把 Key 存成环境变量。不要硬编码进配置文件，用.env文件管理：
TAOTOKEN_API_KEY=sk-你的key TAOTOKEN_BASE_URL=https://taotoken.net/api/v1 OPENCLAW_MODEL=gpt-4o OPENCLAW_GATEWAY_PASSWORD=你自己设的密码这个.env文件放在项目根目录，和docker-compose.yml同级。Docker Compose 会自动读取。注意.env要加进.gitignore，别提交到仓库。
前置准备到这里就齐了：一个 Key、一个 Base URL、一个模型 ID、一个网关密码。接下来写可复制的配置。
3. 可复制配置：docker-compose 与 openclaw.json
这一节是全文的核心，所有配置都给你完整片段，复制就能用。先建目录结构：
mkdir -p openclaw-docker/data cd openclaw-docker目录里放三个文件：docker-compose.yml、.env、openclaw.json。data目录用来挂载持久化数据。
先写docker-compose.yml：
version: "3.9" services: openclaw: image: node:22-slim container_name: openclaw working_dir: /app ports: - "7860:7860" env_file: - .env environment: - PORT=7860 - HOME=/root - OPENCLAW_CONFIG=/root/.openclaw/openclaw.json volumes: - ./data:/root/.openclaw - ./openclaw.json:/root/.openclaw/openclaw.json:ro command: > bash -c " apt-get update && apt-get install -y --no-install-recommends git python3 python3-pip build-essential && pip3 install --no-cache-dir huggingface_hub --break-system-packages && npm install -g openclaw@latest --unsafe-perm && openclaw doctor --fix && exec openclaw gateway run --port 7860 " restart: unless-stopped这段配置做了几件事：用node:22-slim做基础镜像，装 Python 和构建工具，装huggingface_hub用于拉模型配置，全局装openclaw，跑doctor --fix修依赖，最后启动网关。volumes把data目录挂到容器内/root/.openclaw，这样会话和配置能持久化。
接着写openclaw.json，这是模型接入的关键：
{ "models": { "providers": { "taotoken": { "baseUrl": "https://taotoken.net/api/v1", "apiKey": "${TAOTOKEN_API_KEY}", "api": "openai-completions", "models": [ { "id": "gpt-4o", "name": "gpt-4o", "contextWindow": 128000 } ] } } }, "agents": { "defaults": { "model": { "primary": "taotoken/gpt-4o" } } }, "commands": { "restart": true }, "gateway": { "mode": "local", "bind": "lan", "port": 7860, "trustedProxies": ["0.0.0.0/0"], "auth": { "mode": "token", "token": "${OPENCLAW_GATEWAY_PASSWORD}" }, "controlUi": { "allowInsecureAuth": true } } }注意几个字段：baseUrl写到/v1，apiKey用${TAOTOKEN_API_KEY}引用环境变量，api固定openai-completions，models[].id填你在 TaoToken 文档里选的模型 ID。agents.defaults.model.primary的格式是provider名/模型id，这里就是taotoken/gpt-4o。
如果你要接 HuggingFace 上的模型，把baseUrl换成 HuggingFace 推理端点，apiKey换成 HF Token，models[].id换成对应模型名。但 HuggingFace 免费端点有冷启动和限流，生产用还是走 TaoToken 更稳。
.env文件内容：
TAOTOKEN_API_KEY=sk-你的key OPENCLAW_GATEWAY_PASSWORD=你的网关密码三个文件齐了，启动：
docker compose up -d第一次启动会拉镜像、装依赖，大概三到五分钟。看日志：
docker compose logs -f openclaw看到Gateway connection和heartbeat started就说明起来了。访问http://localhost:7860，输入你设的网关密码，状态变 Connected 就能用。
这里补一个 HuggingFace 模型拉取的场景。如果你想把模型配置从 HF Dataset 恢复，可以在容器里跑：
python3 -c " from huggingface_hub import hf_hub_download path = hf_hub_download( repo_id='你的用户名/你的数据集', filename='latest_backup.tar.gz', repo_type='dataset', token='你的HF_TOKEN' ) print(path) "这段代码把备份文件下载到本地，再解压到/root/.openclaw/。适合迁移场景，不适合首次部署。
4. 验证请求与成功结果
配置写完，必须验证。分三层：容器层、网关层、模型层。
容器层先看进程：
docker compose ps状态是Up就正常。如果Exit，看日志找报错。
网关层验证端口：
curl -s -o /dev/null -w "%{http_code}" http://localhost:7860返回200或302都算通。返回000说明端口没起来。
模型层验证最关键的，直接打 TaoToken 通道：
curl -s https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o", "messages": [{"role": "user", "content": "用一句话介绍你自己"}], "max_tokens": 64 }' | python3 -m json.tool成功返回长这样：
{ "id": "chatcmpl-xxx", "object": "chat.completion", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "我是一个 AI 助手..." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 12, "completion_tokens": 20, "total_tokens": 32 } }看到choices[0].message.content有内容，说明模型通道完全通。如果choices是空数组，检查model字段是否拼错。
再验证 OpenClaw 内部调用。进容器：
docker compose exec openclaw bash在容器里跑：
openclaw doctor输出里会列出配置检查项，models和gateway都打勾就对了。然后跑一次实际对话：
openclaw chat --message "你好，测试一下"如果返回模型回复，说明 OpenClaw 到 TaoToken 的链路完整。
最后在 Web UI 里测。打开http://localhost:7860，输入网关密码，进 Chat 页面，发一条消息。看到回复就闭环了。
成功结果的特征：日志里出现[heartbeat] started，UI 状态 Connected，Chat 有回复，usage字段有 token 计数。四个都对上，部署就算完成。
5. 本篇常见错排查
部署过程最容易卡在几个报错上，逐个拆。
401 Unauthorized。这是 Key 问题。先确认.env里TAOTOKEN_API_KEY没有多余空格和引号。然后确认openclaw.json里apiKey写的是${TAOTOKEN_API_KEY}，不是硬编码。如果都对了还 401，去 TaoToken 控制台看 Key 是否被禁用或额度耗尽。路径是 https://taotoken.net/console/api-keys 。
local proxy failed。这个报错通常出现在容器网络配置上。OpenClaw 尝试走本地代理但连不上。检查docker-compose.yml里有没有多余的HTTP_PROXY环境变量。如果有，删掉。容器内不需要代理，直接走宿主网络。另外确认trustedProxies设成["0.0.0.0/0"]，否则网关会拒绝转发。
reading choices 报错。典型信息是error reading choices: unexpected end of JSON input。这说明返回体不是合法 JSON，多半是baseUrl拼错导致返回了 HTML 错误页。检查baseUrl是不是https://taotoken.net/api/v1，末尾不要多斜杠。如果填成https://taotoken.net/api，请求会打到错误路径，返回 404 HTML，解析就崩。
OAuth 相关报错。如果你在配置里启用了 OAuth 模式但没配回调地址，会报OAuth callback mismatch。本地部署建议直接用 token 模式，gateway.auth.mode设成token，别开 OAuth。如果非要 OAuth，回调地址填http://localhost:7860/auth/callback。
模型 ID 不识别。报错model not found。去 TaoToken 文档确认模型 ID 拼写，路径 https://taotoken.net/doc 。注意大小写，gpt-4o和GPT-4O不一样。另外agents.defaults.model.primary的格式必须是provider名/模型id，少一段就找不到。
容器启动后立即退出。看日志docker compose logs openclaw。常见原因是npm install -g openclaw失败，网络超时。重试一次，或者换国内 npm 镜像。另一个原因是openclaw doctor --fix报错，把command里的doctor --fix去掉，先让容器起来，再手动进容器修。
端口占用。7860被别的服务占了。改docker-compose.yml的ports映射，比如"7861:7860"，然后访问http://localhost:7861。
HuggingFace 模型拉取超时。HF 免费端点冷启动慢，第一次请求可能等 30 秒以上。如果一直超时，换 TaoToken 通道。TaoToken 的响应稳定得多，适合生产。
排障的核心思路：先确认 Key 和 Base URL，再确认模型 ID，最后看网络和端口。三层逐层排除，基本都能定位。
6. 长期使用与 CTA 分流
部署跑通只是开始，长期用要考虑几件事。
第一，Key 轮换。TaoToken 的 Key 建议定期换，换完只改.env里的TAOTOKEN_API_KEY，然后docker compose restart openclaw。不用动openclaw.json，因为配置里引用的是环境变量。
第二，模型切换。想换模型，改openclaw.json里models[].id和agents.defaults.model.primary，重启容器。TaoToken 支持多模型，你可以在models数组里加多个，用的时候在 UI 里选。
第三，数据备份。data目录挂载在宿主机，定期打包就行：
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz data/第四，监控。OpenClaw 自带 heartbeat 日志，配合docker compose logs看运行状态。如果要做长期 Agent 任务，建议上 Coding Plan，路径是 https://taotoken.net/coding-plan ，适合持续编码和自动化场景。
如果你在排障阶段卡住，优先看接入文档，路径是 https://taotoken.net/doc 。文档里有完整的错误码对照和配置示例。验证模型是否可用，直接去模型对话页面试，路径是 https://taotoken.net/chat 。需要管理 Key 就去 API Keys 页面，路径是 https://taotoken.net/console/api-keys 。
最后说个实用技巧：把openclaw.json里的contextWindow设成模型实际支持的值。设大了会浪费 token，设小了会截断上下文。TaoToken 文档里每个模型都标了上下文长度，照着填就行。这个细节不影响启动，但影响长期使用成本。
 与 P2P 双信令架构、HTTP API 与 [rtc] 配置全解)
