1. 为什么我要把 OpenClaw 塞进 Docker 里跑OpenClaw 是一个能挂载多种技能skills的智能体运行框架你可以把它理解成一个「带工具箱的对话机器人」主模型负责思考skills 负责动手比如查 GitHub issue、抽视频帧、跑 tmux 会话。它适合谁适合想把 AI 助手真正落到本地运维、日志分析、文档整理这些脏活累活上的开发者。而 Docker 部署的价值在于环境隔离、可重复、迁移方便容器重建后一条命令就能拉起来。但真动手你会发现OpenClaw 的 Docker 部署并不是docker run一下就完事。我自己走了一遍完整链路踩的坑集中在三块容器内用户权限不对导致 apt 装不了包、Debian 12 的 PEP 668 保护让 pip 装 uv 直接失败、以及配置文件挂载后模型通道没接上导致对话报错。这篇就把从config.toml骨架到统一 Key 接入的完整流程拆开讲每一步都给可复制的命令和配置你照着做能复现出问题也能对着排障章节定位。先明确本文覆盖的链路拉镜像 → 挂载配置 → 启动容器 → 补依赖 → 接模型通道 → 验证连通性。其中模型通道这块我用 TaoToken 的统一 Key 来接入原因是它把多家模型的调用收敛到一个 API 地址和一把 Key 上省得在配置文件里塞一堆不同厂商的 base_url 和密钥。下面进入正题。2. TaoToken 前置准备拿到统一 Key 和 API 地址在动 Docker 之前先把模型通道准备好否则容器起来了也没法对话。TaoToken 的作用是提供统一的模型调用入口你只需要一个 API Key 和一个 base_url就能在 OpenClaw 里配置主模型不用为每个模型单独维护一套凭证。第一步打开官网注册并进入控制台。地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后进控制台面板。第二步在控制台里创建 API Key。直接访问 https://taotoken.net/console 找到 API Keys 管理页新建一把 Key 并复制保存。这把 Key 就是后面写进配置文件的核心凭证注意别泄露。第三步确认 API 接入地址。TaoToken 的 API 端点是 https://taotoken.net/api 这个地址会作为 OpenClaw 配置里的 baseUrl。注意这里不加任何 UTM 参数就是干净的 API 根路径。如果你还想先验证模型能不能正常对话可以打开模型对话页面 https://taotoken.net/chat 随便发一句测试确认 Key 有效、额度正常。这一步能帮你把「Key 本身有问题」和「OpenClaw 配置有问题」提前区分开省得后面排障时两头怀疑。对于长期跑编码任务或 Agent 场景的可以了解下 Coding Plan https://taotoken.net/coding-plan 它针对持续调用做了额度规划。接入文档在 https://taotoken.net/doc 配置项有疑问时对着文档核对字段名最稳妥。3. 可复制的 config.toml 骨架与 Docker 运行命令OpenClaw 的配置我建议用config.toml来管理结构清晰、注释友好比纯 JSON 好维护。下面这份骨架是我实测能跑通的最小可用版本你按自己的路径和 Key 替换即可。# OpenClaw 主配置骨架 [gateway] # 网关监听端口Control UI 通过这个端口访问 port 18789 # 本地模式仅监听回环地址避免暴露到公网 mode local bind loopback # 认证方式用 token auth token [model] # 模型提供方名称自定义即可 provider taotoken # TaoToken 统一 API 地址 base_url https://taotoken.net/api # 你的统一 Key建议通过环境变量注入而非硬编码 api_key ${TAOTOKEN_API_KEY} # 默认主模型 default gpt-5.4 # 图像模型 image_model gpt-5.4 [workspace] # 工作区路径容器内路径 path /home/node/.openclaw/workspace [tools] # 工具配置档coding 档位适合开发场景 profile coding关于api_key这一行我强烈建议用环境变量注入而不是把 Key 明文写进文件。Docker 运行时通过-e传入配置文件里只留占位符这样配置文件可以进版本库而不会泄露凭证。接下来是 Docker 运行命令。假设你已经把上面的config.toml放在宿主机的/opt/openclaw/config.toml工作区目录在/opt/openclaw/workspacedocker run -d \ --name openclaw \ -p 18789:18789 \ -e TAOTOKEN_API_KEY你的Key粘贴在这里 \ -v /opt/openclaw/config.toml:/home/node/.openclaw/config.toml \ -v /opt/openclaw/workspace:/home/node/.openclaw/workspace \ --restart unless-stopped \ openclaw/openclaw:latest几个参数说明一下。-p 18789:18789把网关端口映射出来Control UI 才能从宿主机访问。-e注入 Key对应配置文件里的${TAOTOKEN_API_KEY}。两个-v分别挂载配置和工作区工作区挂载出来是为了容器重建后你的文件不丢。--restart unless-stopped让容器在异常退出后自动拉起适合长期运行。如果你用 Docker Compose等价写法是这样version: 3.8 services: openclaw: image: openclaw/openclaw:latest container_name: openclaw ports: - 18789:18789 environment: - TAOTOKEN_API_KEY${TAOTOKEN_API_KEY} volumes: - /opt/openclaw/config.toml:/home/node/.openclaw/config.toml - /opt/openclaw/workspace:/home/node/.openclaw/workspace restart: unless-stoppedCompose 方式下Key 放在同目录的.env文件里写TAOTOKEN_API_KEY你的Key然后docker compose up -d启动。这样凭证和编排文件分离更干净。4. 启动后补依赖与连通性验证容器起来不代表 skills 就能用。OpenClaw 的很多技能依赖外部命令行工具干净镜像里默认只有极少数可用。我实测下来初始状态下openclaw skills check显示可用技能只有 3 个左右补齐依赖后能提到 9 个以上。先确认容器状态和日志docker compose ps docker logs openclaw --tail 50日志里如果看到网关在 18789 端口监听、没有报错堆栈说明主体启动正常。接着进容器补依赖。注意这里有个关键坑默认进入容器的用户不是 root直接跑 apt 会报/var/lib/apt/lists/partial权限不足。正确姿势是用 root 身份进入docker exec -u 0 -it openclaw sh进去之后依次执行apt-get update apt-get install -y jq ripgrep ffmpeg tmux git curl \ python3 python3-pip python3-venv python3-full \ gh unzip zip ca-certificates procps less \ netcat-openbsd dnsutils pipx这批工具覆盖了日志分析jq、ripgrep、媒体处理ffmpeg、终端协助tmux、GitHub 操作gh等高频场景。装完后处理 uv。Debian 12 启用了 PEP 668 保护直接pip3 install uv会失败报 externally-managed-environment。正确做法是走 pipxpipx install uv ln -sf /home/node/.local/bin/uv /usr/local/bin/uv ln -sf /home/node/.local/bin/uvx /usr/local/bin/uvx软链接这一步不能省否则 uv 装好了但 PATH 里找不到。验证一下which uv uv --version能输出/usr/local/bin/uv和版本号就对了。最后跑一次技能检查openclaw skills check可用技能数量应该明显上升。然后验证模型通道是否接通在容器内执行openclaw gateway status openclaw status如果状态显示网关运行中、模型 provider 为 taotoken、没有认证错误说明统一 Key 接入成功。你也可以直接打开 Control UI地址是http://localhost:18789/发一句测试对话能正常回复就说明整条链路通了。5. 本篇常见错误排查部署过程中最容易卡住的几个点我按现象、原因、处理列出来你对着查。apt-get 报权限错误。现象是/var/lib/apt/lists/partial权限不足。原因是当前用户不是 root。处理用docker exec -u 0 -it openclaw sh以 root 进入再装。pip3 install uv 失败。现象是 externally-managed-environment 报错。原因是 Debian 12 的 PEP 668 保护不允许直接往系统 Python 写包。处理改用pipx install uv再建软链接。uv 装好了但命令找不到。现象是which uv无输出。原因是安装路径不在 PATH。处理ln -sf /home/node/.local/bin/uv /usr/local/bin/uvuvx 同理。配置文件改了但没生效。现象是模型还是旧的或报认证失败。原因是挂载路径不对或者 Key 环境变量没传进去。处理确认-v的宿主机路径和容器内路径一致docker exec openclaw env | grep TAOTOKEN看变量在不在。对话报 401 或认证错误。现象是 Control UI 发消息返回认证失败。原因是 Key 无效或 base_url 写错。处理核对 base_url 是否为https://taotoken.net/apiKey 是否复制完整可以先去模型对话页面单独测一下 Key。npm 安装插件报 EACCES。现象是装第三方插件时权限拒绝。原因是 npm 缓存目录里有 root 属主的文件。处理修正/home/node/.npm的属主后重试。另外第三方插件安装前先看安全提示涉及 child_process、环境变量访问的要谨慎。clawhub search 被限流或服务端异常。现象是 Rate limit exceeded 或 InternalServerError。原因是公开搜索接口有频率限制或偶发故障。处理降低查询频率别连续猛试等一会儿再查或者直接用已知技能名。排障时如果怀疑是接入配置问题优先去接入文档 https://taotoken.net/doc 核对字段再去 API Keys 页面 https://taotoken.net/api-keys 确认 Key 状态和额度。6. 把配置固化下来下次重建不重踩手工进容器装包只能救急容器一重建就全没了。我的做法是把验证有效的依赖写进自定义 Dockerfile把配置固化到config.toml工作区文档单独保留。这样换机器或迁移环境时构建镜像、恢复配置、启动容器三步就能复原。自定义镜像的 Dockerfile 大致长这样FROM openclaw/openclaw:latest USER root RUN apt-get update apt-get install -y \ jq ripgrep ffmpeg tmux git curl \ python3 python3-pip python3-venv python3-full \ gh unzip zip ca-certificates procps less \ netcat-openbsd dnsutils pipx \ rm -rf /var/lib/apt/lists/* RUN pipx install uv \ ln -sf /home/node/.local/bin/uv /usr/local/bin/uv \ ln -sf /home/node/.local/bin/uvx /usr/local/bin/uvx USER node构建后替换掉原来的镜像名其余挂载和启动命令不变。这样每次重建都是「开箱即用」的状态不用再进容器一条条敲。验证清单我固定跑这几条docker compose ps看容器状态docker logs看启动日志openclaw gateway status看网关openclaw skills check看技能可用数再which一遍关键工具确认路径。模型通道这块确认 provider 指向 taotoken、base_url 正确、Key 有效然后去 Control UI 发一句测试对话收尾。如果你后面要跑长期的编码或 Agent 任务可以看下 Coding Plan https://taotoken.net/coding-plan 做额度规划日常调试模型直接去模型对话页面 https://taotoken.net/chat 最快。整套流程走下来OpenClaw 在 Docker 里就能稳定跑起来模型通道用统一 Key 收敛排障路径也清晰了。