把 openclaw 小龙虾装进 Docker：从 ghcr.io 拉取到 openclaw doctor 自检的安装日记（新手向）

1. 为什么新手值得把 openclaw 小龙虾塞进 Dockeropenclaw 小龙虾是一个能挂载到飞书、钉钉等聊天通道上的 AI 助手你可以把它理解成一个「住在容器里的私人助理」它自己跑一个 gateway 网关服务对外暴露端口接收消息、调用模型、执行任务。对新手来说它最吸引人的地方是能直接在你熟悉的聊天软件里对话不用折腾前端界面。但直接装在宿主机上风险也很实在。我见过最惨的情况是它误删了工作目录里的文件因为 AI 执行 shell 命令时权限和宿主机完全一样。另一个顾虑是信息泄露配置文件里往往躺着 API Key、通道凭证裸装在系统里等于把这些东西摊在桌面上。Docker 的价值就在这里把 openclaw 关进一个隔离的盒子文件系统、网络、进程都跟宿主机隔开删掉容器不留痕迹重建也只要一条命令。这篇日记面向零基础读者聚焦一条完整链路从 ghcr.io 拉取镜像、配置 gateway 端口与数据卷、跑起来再用 openclaw doctor 自检排错。我会给出可以直接复制的 docker run 和 compose 配置、环境变量清单以及 doctor 输出逐项怎么读、常见报错怎么验证。热词里的 openclaw、docker、ghcr.io、gateway、openclaw doctor 都会落到具体操作上不空谈概念。适合谁看如果你满足下面任意一条这篇就是写给你的第一次接触 Docker想拿一个真实项目练手已经在用 openclaw 但想搬到容器里图个安心被 ghcr.io 拉取慢、端口连不上、doctor 报错卡住过。全程假设你用的是 Windows Docker DesktopLinux 和 macOS 命令基本一致差异我会点出来。先说清楚一个前提openclaw 的官方文档在 docs.openclaw.ai 有 Docker 安装章节社区也维护了中文汉化镜像。我踩过的坑大多集中在网络和配置监听地址上所以这篇的重点不是「怎么点下一步」而是「为什么这一步会失败、失败后看哪里」。下面从准备 TaoToken 的模型接入开始一步步来。2. 前置准备TaoToken 接入与 Docker 环境自检openclaw 本身是个壳真正干活的是背后的大模型。所以装容器之前先把模型接入这块理清楚否则容器跑起来了对话还是报错。我用的是 TaoToken 的 API 接入方式它兼容 OpenAI 风格的接口配置起来对新手友好。你需要准备三样东西Base URL、API Key、Model ID。Base URL 填https://taotoken.net/api这是接口地址注意不要带多余的路径后缀。API Key 到控制台生成路径是 API Keys 页面生成后复制保存它只显示一次。Model ID 按你实际要用的模型填比如对话场景常用的通用模型标识。这三件套在后面的环境变量里会用到先记在记事本里。TaoToken 的接入文档在 doc 页面有详细说明模型对话可以在线验证 Key 是否可用长期编码或 Agent 场景可以看 Coding Plan。建议你先在模型对话里发一句话确认 Key 通了再往下走。这一步能省掉后面一半的排错时间因为容器里的报错往往分不清是网络问题还是 Key 问题。Docker 环境自检。Windows 用户装 Docker Desktop装完在 PowerShell 里跑docker --version docker infodocker info能正常输出 Server 信息说明 Docker 引擎起来了。如果报Cannot connect to the Docker daemon去 Docker Desktop 界面看引擎是不是在启动中或者 WSL2 后端有没有异常。macOS 和 Linux 用户同理确认 daemon 在跑。再确认一下端口占用。openclaw 默认用 18789 作为 gateway 端口18791 是浏览器控制端口。先查这两个端口有没有被占netstat -ano | findstr 18789 netstat -ano | findstr 18791Windows 用netstat -anoLinux/macOS 用lsof -i:18789。有输出就说明被占了要么换端口要么把占用进程停掉。我建议新手直接换端口比如映射成 28789省得跟系统里其他服务打架。最后提醒一个容易忽略的点数据卷。openclaw 的配置和数据默认存在容器内的/root/.openclaw目录如果不挂载出来容器一删配置全没。所以从一开始就要规划好卷名比如openclaw-data后面所有命令都带上它。这一步做对后面迁移、备份、重建都轻松。3. 可复制配置docker run 与 compose 双方案这一节给你两套能直接抄的配置一套是docker run单命令适合快速验证一套是docker-compose.yml适合长期使用。两套都包含 ghcr.io 镜像地址、gateway 端口映射、数据卷挂载和环境变量。先说镜像地址。社区中文汉化版在 ghcr.io 上完整地址是ghcr.io/1186258278/openclaw-zh。标签有两个常用选择nightly是每夜构建的最新测试版功能最全latest是最新稳定版。新手建议先用nightly界面全中文遇到问题社区讨论也多。docker run方案Windows PowerShell 里一行搞定docker run -d --name openclaw -p 18789:18789 -p 18791:18791 -v openclaw-data:/root/.openclaw -e TZAsia/Shanghai -e OPENAI_BASE_URLhttps://taotoken.net/api -e OPENAI_API_KEY你的Key -e OPENAI_MODEL你的模型ID --restart unless-stopped ghcr.io/1186258278/openclaw-zh:nightly openclaw gateway run逐段拆解-d后台运行--name openclaw容器名后面 doctor、logs 都用它-p 18789:18789把 gateway 端口映射出来-p 18791:18791映射浏览器控制端口-v openclaw-data:/root/.openclaw挂载数据卷配置持久化-e TZAsia/Shanghai指定时区不然定时任务按 UTC 跑触发时间会差 8 小时三个OPENAI_*环境变量就是上一节的 TaoToken 三件套--restart unless-stopped让容器开机自启、崩溃重试最后openclaw gateway run是必须显式加的子命令少了它容器会打印帮助菜单然后退出。docker-compose.yml方案适合放进项目目录长期维护services: openclaw: image: ghcr.io/1186258278/openclaw-zh:nightly container_name: openclaw command: openclaw gateway run ports: - 18789:18789 - 18791:18791 volumes: - openclaw-data:/root/.openclaw environment: - TZAsia/Shanghai - OPENAI_BASE_URLhttps://taotoken.net/api - OPENAI_API_KEY你的Key - OPENAI_MODEL你的模型ID restart: unless-stopped volumes: openclaw-data:启动命令是docker compose up -d停止是docker compose down。注意down不会删卷数据还在要彻底清空得加-v。compose 的好处是配置即代码改环境变量不用重敲长命令团队协作也方便。环境变量清单对照表方便你核对变量名作用示例值TZ时区影响定时任务Asia/ShanghaiOPENAI_BASE_URL模型接口地址https://taotoken.net/apiOPENAI_API_KEY接口密钥控制台生成OPENAI_MODEL模型标识按实际填写注意PowerShell 里直接粘贴 Linux 风格命令时引号和转义符处理不同容易报template parsing error。如果遇到把命令里的单引号换成双引号或者改用 compose 方案绕开。配置写好后先别急着启动下一节讲怎么验证请求真的通了。4. 启动验证与 openclaw doctor 自检逐项解读容器起来后第一件事是看它到底有没有在干活。执行docker ps看到openclaw状态是Up才算启动成功。如果状态是Exited直接看日志docker logs openclaw日志里如果出现帮助菜单Help Menu然后退出八成是启动命令少了openclaw gateway run子命令。补上再重建容器即可。确认容器在跑接着验证 gateway 端口。浏览器访问http://localhost:18789或者用 curlcurl http://localhost:18789有响应就说明网关活着。如果拒绝连接先别慌往下看 doctor。openclaw doctor 是官方自检工具能一次性检查配置、依赖、网络。在容器里跑docker exec -it openclaw openclaw doctor输出会分几块我按常见顺序解读。第一块是配置检查如果看到Config invalid说明配置文件有问题通常跟着一句Run openclaw doctor --fix。这时候直接跑修复docker exec -it openclaw openclaw doctor --fix修复过程会提示Config overwrite确认后它会把配置改成合法值并生成备份文件openclaw.json.bak。我遇到过一次监听地址被写成0.0.0.0导致无效doctor 自动改成了lan问题就没了。第二块是网络检查。如果日志里反复出现[browser/server] Browser control listening on http://127.0.0.1:18791/说明服务只绑定了容器内的 localhost外部访问不了。这是新手最容易卡的点环境变量没传进去或者该版本不支持用环境变量改监听地址。验证方法是进容器看配置docker exec -it openclaw cat /root/.openclaw/openclaw.json看监听地址字段是不是127.0.0.1。如果是手动改成0.0.0.0或lan保存后重启容器。改之前先备份改完再跑一次 doctor 确认。第三块是依赖检查。日志里可能出现WSL2 needs systemd enabled这是 WSL2 环境的提示不一定阻断基础运行但会影响高级插件。要处理的话编辑/etc/wsl.conf加上 systemd 配置然后重启 WSL。新手可以先跳过等基础功能跑通再回头弄。doctor 全绿之后再访问http://localhost:18789应该能看到界面或正常响应。到这一步容器、网关、模型接入三件事都通了。接下来把飞书、钉钉通道打通网络层面的小问题可以让 openclaw 自己修它的自愈能力比手动排查快。5. 常见报错排查401、端口占用、拉取慢与配置循环这一节按真实报错来每条给出验证动作和修复方向。新手遇到报错别急着删容器先看日志定位。报错一401 Unauthorized。模型对话时报 401基本是 Key 或 Base URL 的问题。验证动作先在 TaoToken 的模型对话页面用同一个 Key 发一句话如果那边也 401说明 Key 本身无效或过期去 API Keys 页面重新生成。如果那边正常说明容器里的环境变量没生效。检查方法docker exec -it openclaw env | findstr OPENAIWindows 用findstrLinux/macOS 用grep。看OPENAI_API_KEY和OPENAI_BASE_URL是不是你填的值。如果为空说明docker run时-e没写对或者 compose 里 environment 缩进错了。改完重建容器。报错二Port already in use。启动时报Error: Port already in use说明 18789 或 18791 被占。验证动作netstat -ano | findstr 18789找到占用进程的 PID去任务管理器结束它或者干脆换映射端口比如-p 28789:18789。换端口后访问地址也要跟着改。报错三ghcr.io 拉取慢或卡住。这是国内直连 ghcr.io 的常见现象。有个细节值得说第一次跑nightly很快是因为本地已经缓存了镜像层第二次跑latest很慢是因为 Docker 默认会去远程检查更新网络不好时这个检查会卡很久而且latest和nightly不是同一个镜像需要下载新层。验证动作docker images看本地有没有ghcr.io/1186258278/openclaw-zh的对应标签。如果已经有nightly就继续用nightly别切latest。如果必须拉新镜像挑网络空闲时段或者从中文论坛找镜像加速方案。拉取时加--pullmissing可以跳过不必要的更新检查。报错四Config invalid 循环。日志反复刷Config invalid和Run openclaw doctor --fix服务起不来。这是配置文件损坏或字段非法。修复流程先停容器docker stop openclaw再跑docker exec -it openclaw openclaw doctor --fix容器停了 exec 会失败所以要么在运行状态下修要么用临时容器挂载卷修。修完确认openclaw.json.bak生成了再重启。如果重启后问题依旧说明配置没物理写入磁盘检查卷挂载是否正确。报错五Cannot find module /app/gateway。这是把gateway当成文件路径了。正确用法是openclaw gateway rungateway是 CLI 子命令不是路径。检查启动命令有没有写错。报错六localhost 拒绝连接但日志正常。日志显示Browser control listening on http://127.0.0.1:18791/浏览器却连不上。原因是服务只监听容器内 localhost。验证动作进容器curl http://127.0.0.1:18791能通但宿主机访问不了。修复方向是改配置里的监听地址为0.0.0.0或lan重启容器。如果该版本不支持环境变量改监听就手动改配置文件。排查顺序建议先看docker ps状态再看docker logs再跑openclaw doctor最后进容器看配置。这个顺序能覆盖九成问题。6. 数据持久化、备份与后续接入建议容器跑通只是开始长期用下去要解决数据安全和运维便利。这一节讲卷挂载、备份、以及通道接入的收尾。数据卷是重中之重。如果你启动时忘了-v openclaw-data:/root/.openclaw容器一删配置全丢。已经跑起来才发现没挂载的补救办法是用docker cp把文件拷出来docker cp openclaw:/root/.openclaw/openclaw.json C:\Users\你的用户名\Desktop\openclaw_backup.json数据库文件同理假设在容器内/app/data/openclaw.dbdocker cp openclaw:/app/data/openclaw.db C:\Users\你的用户名\Desktop\openclaw_backup.db拷出来后重建容器时带上卷挂载再把文件拷回去。虽然麻烦但比丢数据强。我建议一开始就规划好卷别等出问题再补。备份策略很简单定期把卷里的配置和数据库拷到宿主机或云盘。Docker 卷的位置在 Docker Desktop 的设置里能查到Windows 下通常在 WSL2 的虚拟磁盘里直接拷不方便用docker cp最稳。也可以写个脚本定时执行。故障恢复的标准流程记一下停容器docker stop openclaw删容器docker rm openclaw跑修复openclaw doctor --fix用临时容器挂载卷验证配置重新docker run或docker compose up -d最后docker logs -f openclaw盯日志。这套流程走一遍大部分问题能自愈。通道接入方面建议先把飞书、钉钉打通。openclaw 的网络自愈能力不错通道通了之后很多小问题可以让它自己修比手动排查快。接入时注意凭证别硬编码在命令里用环境变量或配置文件配合卷挂载持久化。最后给个长期使用的建议把docker-compose.yml和.env文件放进版本控制Key 用占位符换机器时拉下来改 Key 就能跑。模型接入这块TaoToken 的 API 兼容性好Base URL 填https://taotoken.net/apiKey 到控制台生成模型对话可以随时验证连通性。长期编码或 Agent 场景可以看 Coding Plan接入文档在 doc 页面有完整说明。容器、网关、模型、通道四件事都通了openclaw 小龙虾才算真正住进你的 Docker 里。