1. OpenClaw Docker 手工部署到底难在哪OpenClaw 是一个面向 Agent 场景的开源框架能对接大模型完成对话、工具调用和自动化任务适合想自己掌控运行环境、又不想被托管平台绑死的开发者。它支持 Docker 手工部署也支持本地源码运行但真正动手的人会发现镜像能拉下来只是第一步容器网络、环境变量、配置文件三处任意一个没对齐调用链路就会在某个环节静默失败。我见过最多的三类翻车现场一是容器里localhost指向容器自身宿主机上的服务根本连不上二是环境变量写进了.env但没通过--env-file传进容器进程读到的还是空值三是settings.json和config.toml两份配置各写一半模型通道和 API Key 对不上日志里只报一个模糊的 401。这篇就按「部署 → 配置 → 验证 → 排障」的顺序把每个坑点对应的可复制片段和逐条自检动作写清楚你照着做能少走两小时弯路。核心检索词先明确OpenClaw Docker 手工部署、容器网络配置、环境变量注入、settings.json 骨架、config.toml 骨架、统一 Key 接入、调用链路自检。适合已经会基本 Docker 命令、想自己搭一套 Agent 运行环境的读者。2. TaoToken 前置统一 Key 与 API 通道准备在动 Docker 之前先把模型通道这块准备好否则后面配置验证会卡在「Key 从哪来」上。TaoToken 提供统一的 API 通道一个 Key 可以对接多种模型省去在多个平台之间来回切换的麻烦。你需要做两件事拿到 Key确认接入地址。访问控制台创建 API Key入口在这里https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite创建完成后Key 只在生成时完整显示一次复制到安全的地方。接着确认 API 基础地址OpenClaw 的模型请求会打到这个地址https://taotoken.net/api注意这个地址不带任何查询参数配置里直接写基址即可路径部分由 OpenClaw 的 provider 配置拼接。如果你用的是 Anthropic 兼容协议接入文档里有对应的路径说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteKey 的管理页面在 API Keys 里后续要轮换或吊销都从这里操作https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite这一步做完你手里应该有一个sk-开头的 Key 和一个基址。先别急着写进配置文件下一节会讲怎么通过环境变量安全地传进容器而不是硬编码在 JSON 里。3. 可复制配置Docker 网络、环境变量与配置文件骨架3.1 容器网络别让 localhost 骗了你Docker 默认的 bridge 网络里容器有自己的网络命名空间容器内的localhost是容器自己不是宿主机。如果你的 OpenClaw 需要访问宿主机上的其他服务比如本地数据库或另一个容器有两种正确姿势。第一种用自定义 bridge 网络让多个容器通过服务名互相访问docker network create openclaw-net docker run -d \ --name openclaw \ --network openclaw-net \ -p 8080:8080 \ --env-file .env \ -v $(pwd)/config:/app/config \ openclaw/openclaw:latest第二种如果确实要访问宿主机服务用host.docker.internalDocker Desktop 环境或宿主机的实际内网 IP不要写127.0.0.1。实测下来把127.0.0.1换成host.docker.internal能解决一大半「容器里连不上」的问题。端口映射也要注意-p 8080:8080左边是宿主机端口右边是容器内端口。如果你改了 OpenClaw 的监听端口右边要跟着改否则映射了个寂寞。3.2 环境变量.env 文件与注入方式环境变量是 Key 和通道地址的入口。建一个.env文件放在项目根目录# .env OPENCLAW_API_KEYsk-你的Key OPENCLAW_API_BASEhttps://taotoken.net/api OPENCLAW_MODELclaude-sonnet-4-20250514 OPENCLAW_LOG_LEVELinfo关键点.env文件不会自动进容器必须用--env-file .env显式传入。很多人写了.env却用docker run不带这个参数容器里读到的全是空字符串然后报一个看不懂的认证错误。如果你用docker compose写法是services: openclaw: image: openclaw/openclaw:latest env_file: - .env ports: - 8080:8080 volumes: - ./config:/app/config networks: - openclaw-net networks: openclaw-net: driver: bridgeenv_file和environment可以共存但同名变量后者优先级更高。建议 Key 这类敏感值只放env_file别写进 compose 文件提交到仓库。3.3 settings.json 骨架OpenClaw 的settings.json管运行时行为放在挂载的config目录里。骨架如下{ server: { host: 0.0.0.0, port: 8080 }, provider: { type: anthropic, base_url: https://taotoken.net/api, api_key_env: OPENCLAW_API_KEY, model: claude-sonnet-4-20250514, timeout: 60 }, logging: { level: info, format: json } }注意api_key_env写的是环境变量名不是 Key 本身。这样 Key 通过.env注入配置文件可以安全地进版本库。host必须是0.0.0.0写127.0.0.1的话容器外访问不到。3.4 config.toml 骨架如果你的 OpenClaw 版本用config.toml作为主配置对应骨架[server] host 0.0.0.0 port 8080 [provider] type anthropic base_url https://taotoken.net/api api_key_env OPENCLAW_API_KEY model claude-sonnet-4-20250514 timeout 60 [logging] level info format json两份配置的字段名要对齐别一个写base_url另一个写api_base。我踩过的坑就是settings.json里改了模型config.toml里还是旧的结果容器启动时读的是 toml验证半天没发现。4. 验证请求从容器内到调用链路的逐条自检配置写完别急着跑业务按下面顺序逐条验证。第一步确认容器起来了docker ps --filter nameopenclaw看到状态是Up且端口映射正确再进下一步。第二步进容器看环境变量有没有进去docker exec -it openclaw env | grep OPENCLAW应该能看到OPENCLAW_API_KEY和OPENCLAW_API_BASE。如果 Key 显示为空或不存在回去检查--env-file参数。第三步在容器内测网络连通性docker exec -it openclaw curl -s -o /dev/null -w %{http_code} https://taotoken.net/api返回 200 或 401 都说明网络通401 是没带 Key 的正常响应返回 000 就是网络不通检查 DNS 或出站规则。第四步发一个真实的模型请求。用 curl 在容器内直接打docker exec -it openclaw curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $OPENCLAW_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }如果返回里能看到模型输出说明 Key、通道、模型名三者都对上了。这一步是整个链路自检的核心过了这关OpenClaw 内部的调用基本不会再有认证问题。第五步通过 OpenClaw 自己的接口验证。假设它暴露了/health和/v1/chatcurl -s http://localhost:8080/health curl -s http://localhost:8080/v1/chat \ -H content-type: application/json \ -d {message: 你好}/health返回正常但/v1/chat报错问题就在 OpenClaw 的 provider 配置不在网络层。这时候去看容器日志docker logs --tail 100 openclaw日志里通常会指出是配置字段没读到还是模型名不匹配。5. 本篇常见错排查报错一connection refused或ECONNREFUSED。九成是地址写了127.0.0.1。容器内访问宿主机用host.docker.internal访问其他容器用服务名。检查base_url和任何回调地址。报错二401 Unauthorized。先确认docker exec进去echo $OPENCLAW_API_KEY有值。有值还 401检查 Key 是否被吊销、是否复制时带了空格。TaoToken 的 Key 在控制台可以重新生成别用旧的。报错三model not found。模型名要和通道支持的名称完全一致大小写、日期后缀都不能错。不确定的话用模型对话页面先手动试一次确认名称可用https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite报错四配置文件改了不生效。检查挂载路径对不对。-v $(pwd)/config:/app/config要求宿主机的config目录里有配置文件且容器内进程读的是这个路径。改完配置要重启容器docker restart openclaw。报错五端口映射了但访问不到。settings.json里host必须是0.0.0.0。另外确认-p的宿主机端口没被占用lsof -i :8080查一下。报错六日志里中文乱码或 JSON 解析失败。检查logging.format如果设成json但输出不是合法 JSON可能是版本不匹配。临时改成text看原始日志更快定位。6. 长期编码与 Agent 场景的接入建议如果你打算把 OpenClaw 长期跑在编码或 Agent 自动化场景里单次请求的 Key 管理会变得很烦。TaoToken 的 Coding Plan 适合这种持续调用的场景额度模型和按次调用不一样长期跑下来更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite接入方式不变还是base_url加 Key只是 Key 换成 Coding Plan 对应的凭证。配置骨架和上面完全一致改.env里的OPENCLAW_API_KEY即可不用动settings.json。最后给一个实用技巧把验证脚本存成verify.sh每次改完配置跑一遍五条命令覆盖环境变量、网络、Key、模型、服务健康比人肉排查快得多。部署这件事能自动化的自检就别靠记忆。