1. 为什么 Docker 部署 OpenClaw 后模型接不进来很多人第一次把 OpenClaw 跑进 Docker看到docker-compose ps里状态是 Up浏览器打开http://localhost:3000也能出界面就以为大功告成。结果一发起对话要么转圈半天没响应要么日志里刷401 Unauthorized、model not found、connection refused。问题基本不在 OpenClaw 本身而是容器里的模型通道没配通。OpenClaw 是一个自托管的 AI 代理平台它自己不生产模型能力需要外接一个兼容 OpenAI 协议的服务端。Docker 部署把运行环境隔离了容器内部的localhost指向的是容器自己不是你的宿主机所以配置文件里写http://127.0.0.1:xxxx必然连不上。同时模型服务商五花八门每换一个模型就要改一次 Key、改一次 base_url维护成本很高。这篇教程聚焦的场景就是容器已经跑起来了接下来用 TaoToken 的统一 Key 和统一 API 通道把模型接入一次性配好。TaoToken 在这里扮演的是「统一入口」的角色——你只需要在config.toml里填一个 base_url 和一个 Key后面换模型只改模型名不用再动通道配置。适合本地自托管 AI 工具的用户、喜欢用 Docker 管理服务、又不想被多家 Key 轮换折腾的人。下面从目录结构、compose 文件、config.toml 骨架、环境变量、连通性验证到排错一步步给可直接复制的配置。你跟着做最后能用一条 curl 命令确认容器内的模型通道是通的。2. TaoToken 前置准备拿到统一 Key 和 API 地址在写配置之前先把两样东西准备好API Key 和 base_url。TaoToken 的 API 地址是https://taotoken.net/api这个地址在容器里也能直接访问不需要额外处理网络。Key 需要你登录后在控制台生成。打开控制台页面进入 API Keys 管理新建一个 Key。建议给这个 Key 起个能识别的名字比如openclaw-docker方便以后区分是哪个服务在用。生成后立刻复制保存页面刷新后通常不再完整显示。如果你还没决定用哪个模型可以先到模型对话页面试跑一下确认账号下有哪些模型可用、响应是否正常。这一步不是必须的但能帮你提前排除「Key 没问题但模型名写错」的情况。对于长期跑编码类 Agent 的场景比如让 OpenClaw 持续做代码任务可以关注 Coding Plan 这类按周期计费的方式比按量调用更可控。具体入口在控制台的订阅区域按你的使用强度选就行。拿到 Key 之后记住两个值base_urlhttps://taotoken.net/apiapi_key控制台生成的那串字符接下来所有配置都围绕这两个值展开。注意 base_url 不要自己加/v1后缀OpenClaw 的客户端库通常会自己拼接路径多写一层反而会 404。这一点后面排错章节还会再提。3. 可复制的 Docker 与 config.toml 配置骨架先建目录把配置和数据分开挂载这样容器重建不会丢数据。mkdir -p openclaw-docker/{data,config} cd openclaw-docker3.1 docker-compose.ymlversion: 3.8 services: openclaw: image: openclaw/openclaw:latest container_name: openclaw ports: - 3000:3000 volumes: - ./data:/app/data - ./config:/app/config - /var/run/docker.sock:/var/run/docker.sock environment: - NODE_ENVproduction - TZAsia/Shanghai - OPENCLAW_PORT3000 - OPENCLAW_HOST0.0.0.0 - TAOTOKEN_API_KEY${TAOTOKEN_API_KEY} - TAOTOKEN_BASE_URLhttps://taotoken.net/api restart: unless-stopped networks: - openclaw-net networks: openclaw-net: driver: bridge这里把 Key 通过环境变量注入而不是硬编码在 compose 文件里。同目录建一个.env文件TAOTOKEN_API_KEYsk-你的实际Key.env记得加进.gitignore别提交到仓库。compose 启动时会自动读取同目录的.env。3.2 config.toml 配置骨架OpenClaw 的模型配置放在./config/config.toml。这个文件是核心容器启动时读取。下面给一份完整骨架字段按注释替换即可。# OpenClaw 主配置 [server] host 0.0.0.0 port 3000 # 模型通道统一走 TaoToken [model] provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model gpt-4o-mini timeout 120 max_retries 3 # 代理行为 [agent] name openclaw max_tokens 4096 temperature 0.7 # 日志 [log] level info几个关键点说明。provider填openai-compatible因为 TaoToken 的接口兼容 OpenAI 协议OpenClaw 用这个 provider 就能对接。base_url就是前面记的地址不要加/v1。api_key用${TAOTOKEN_API_KEY}引用环境变量这样 Key 不落盘到配置文件里容器重建时只要.env还在就能自动恢复。model字段填你要用的模型名。如果你不确定账号下有哪些模型先去模型对话页面确认把界面上能选到的模型名原样填进来。timeout给 120 秒长文本任务不容易被截断。3.3 启动容器docker-compose up -d docker-compose ps看到openclaw状态是Up就说明容器起来了。如果状态是Restarting或Exited先看日志docker logs --tail 50 openclaw日志里如果出现config.toml not found说明挂载路径不对检查./config目录下是否真的有config.toml。如果出现permission denied检查宿主机目录权限必要时chmod 755 ./config。4. 验证容器内 API 连通性容器起来不代表模型通道通了。最直接的验证方式是在容器内部发一个请求确认能拿到模型返回。4.1 进入容器docker exec -it openclaw bash4.2 用 curl 测通道在容器内执行curl -s -X POST 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 }如果返回一段 JSON里面有choices字段和模型回复内容说明通道是通的。如果返回401说明 Key 没读到或者写错了回到.env检查。如果返回404多半是 base_url 多写了/v1或者路径拼错。4.3 从宿主机验证 Web 与健康检查退出容器在宿主机执行curl -s http://localhost:3000/health返回ok或类似健康状态说明 Web 服务正常。再打开浏览器访问http://localhost:3000在界面里发起一次对话。如果界面能正常回复说明 config.toml 里的模型配置被正确加载了。4.4 看日志确认模型调用docker logs -f openclaw发起对话时日志里应该能看到模型请求的记录包括请求的模型名和响应状态。如果日志里出现model not found说明 config.toml 里的model字段填的模型名在账号下不存在去模型对话页面核对准确名称。5. 本篇常见错误排查5.1 401 Unauthorized最常见。原因有三个.env文件没被 compose 读到、环境变量名写错、Key 本身失效。先确认.env和docker-compose.yml在同一目录然后进容器echo $TAOTOKEN_API_KEY看有没有值。如果为空说明 compose 没注入成功检查 environment 段里的变量名是否和.env里一致。5.2 connection refused 或 timeout容器内访问外部地址超时通常是 DNS 或网络出口问题。先在容器内curl -I https://taotoken.net/api看能否建立连接。如果连不上检查宿主机的 Docker 网络配置确认容器能正常出网。注意不要在配置里写127.0.0.1或localhost作为 base_url容器里的 localhost 是容器自己。5.3 config.toml 不生效改了配置但行为没变多半是容器没重新加载。执行docker-compose up -d --force-recreate强制重建容器让新配置生效。如果还是不行进容器cat /app/config/config.toml确认挂载进去的文件内容是不是你改的那份。有时候宿主机编辑的是另一个路径的文件挂载的却是旧目录。5.4 模型名报错model not found或invalid model说明 config.toml 里的model值和账号下可用的模型名不匹配。去模型对话页面看实际可选列表把名称原样复制。注意大小写和连字符gpt-4o-mini和gpt-4o_mini是不同的。5.5 内存不足导致容器被杀OpenClaw 跑长任务时内存占用会上升。如果容器频繁重启在 compose 里加资源限制并适当调大deploy: resources: limits: memory: 4G reservations: memory: 1G同时确认宿主机至少有 4GB 可用内存。内存不够时容器会被 OOM killer 干掉日志里能看到Killed字样。5.6 数据丢失容器重建后对话历史没了检查./data挂载是否正确。docker-compose down不会删数据卷但如果你手动docker volume rm或者删了宿主机目录数据就没了。定期备份tar -czvf openclaw-backup-$(date %Y%m%d).tar.gz ./data/6. 接入方式选择与后续维护配置跑通之后日常维护其实很简单。换模型只改 config.toml 里的model字段然后docker-compose up -d --force-recreate重建容器base_url 和 Key 都不用动。这就是统一通道的好处——模型切换的成本被压到一行配置。如果你主要用 OpenClaw 做对话类任务验证模型是否可用时可以直接在模型对话页面测试确认响应正常再写进配置。如果是长期跑编码或 Agent 任务建议用 Coding Plan 的方式管理调用额度避免按量计费在长任务里失控。Key 的管理统一在 API Keys 页面定期轮换、删除不用的 Key减少泄露风险。接入文档里有更完整的参数说明和协议细节遇到配置字段不确定时可以去查。整个链路的核心就三样容器能出网、base_url 写对、Key 注入成功。这三样确认了剩下的都是模型名和参数微调。最后提醒一句/var/run/docker.sock挂载给了容器访问宿主机 Docker 的能力方便 OpenClaw 管理容器但也意味着容器权限较高。本地自托管环境问题不大如果暴露到公网务必限制访问来源别让 3000 端口裸奔。