OpenClaw Docker 完整部署与排障总文档

一、文档说明

本文将最近两天围绕 Docker 方式部署 OpenClaw 的安装、配置、问题处理、依赖补齐、技能增强、重复部署方法与后续建议统一整理为一份完整文档，适合存档、交接、复盘和后续持续维护。

这个文档是openclaw小龙虾整理通过qq发我的

二、环境与基础信息

1. 部署方式：Docker / Docker Compose

2. 容器系统：Debian GNU/Linux 12 (bookworm)

3. OpenClaw 版本：2026.3.7

4. 当前主模型：codexzh/gpt-5.4

5. Gateway 地址：http://localhost:18789/

6. 工作区路径：/home/node/.openclaw/workspace

7. 配置文件路径：/home/node/.openclaw/openclaw.json

三、总体目标

本次折腾的目标并不是单纯把 OpenClaw 跑起来，而是实现以下几件事：

1. 在 Docker 环境中稳定运行 OpenClaw

2. 确认主模型可正常对话和执行常见任务

3. 补齐一批高价值基础依赖，提升 skills 可用性

4. 形成可重复部署的方法，避免以后重建容器重新踩坑

5. 整理出文档，方便后续长期使用

四、当前已确认的关键配置

根据本次过程，当前环境中已明确的重要配置思路包括：

1. 模型提供方：codexzh

2. baseUrl：https://api.codexzh.com/v1

3. 默认模型：codexzh/gpt-5.4

4. imageModel：codexzh/gpt-5.4

5. Gateway 端口：18789

6. Gateway 模式：local

7. Gateway 认证方式：token

8. Gateway bind：loopback

9. workspace：/home/node/.openclaw/workspace

10. tools.profile：coding

五、部署与排障过程回顾

（一）初始状态检查

最开始在容器内执行 openclaw skills check，结果显示：

1. Total: 51

2. Eligible: 3

3. 可用 skills 仅有 healthcheck、skill-creator、weather

这说明：

1. OpenClaw 主体已经能运行

2. 但当前镜像属于比较干净的最小依赖环境

3. 大量 skill 还缺少命令行依赖、配置项或外部 API key

（二）确认容器环境

进一步确认后，环境具备以下条件：

1. 操作系统是 Debian 12

2. 容器内可用 apt-get

3. 容器内可用 npm

这意味着后续可以直接通过 Debian 包管理器和 npm 安装所需工具。

（三）安装基础依赖

为了提升 skills 的可用性，先后补充了这一批高价值依赖：

1. jq

2. ripgrep

3. ffmpeg

4. tmux

5. git

6. curl

7. python3

8. python3-pip

9. python3-venv

10. python3-full

11. gh

12. unzip

13. zip

14. ca-certificates

15. procps

16. less

17. netcat-openbsd

18. dnsutils

19. pipx

20. clawhub（npm 全局安装）

21. uv

（四）apt-get 权限问题

第一次执行 apt-get 时出现权限错误，报错集中在：

1. /var/lib/apt/lists/partial 权限不足

原因是：

1. 当前进入容器的用户并不是 root

解决办法：

1. 使用 docker exec -u 0 -it 容器名 sh 进入容器

2. 再执行 apt-get update 和 apt-get install

这个坑说明：Docker 里很多问题并不是包本身有问题，而是用户权限不对。

（五）uv 安装问题

最初尝试通过 pip3 install uv 安装 uv，但在 Debian 12 环境下失败。

原因：

1. Debian 12 启用了 PEP 668 externally-managed-environment 保护

2. 不允许直接往系统 Python 环境中用 pip3 随便写包

最终采用的正确方案：

1. 先安装 pipx

2. 执行 pipx install uv

3. 再把 uv 和 uvx 链接到 /usr/local/bin

对应命令思路：

1. pipx install uv

2. ln -sf /home/node/.local/bin/uv /usr/local/bin/uv

3. ln -sf /home/node/.local/bin/uvx /usr/local/bin/uvx

最终验证结果：

1. uv 版本为 0.10.9

2. which uv 能正确输出 /usr/local/bin/uv

（六）skills 可用性提升结果

在补齐依赖后，skills 从最初的 3 个可用提升到 9 个可用。

最终确认可用的技能包括：

1. clawhub

2. gh-issues

3. github

4. healthcheck

5. session-logs

6. skill-creator

7. tmux

8. video-frames

9. weather

这说明当前环境已经具备较强的：

1. 日志分析能力

2. GitHub 辅助能力

3. 视频帧处理能力

4. 终端与 tmux 协助能力

5. 健康检查与文档辅助能力

（七）为什么 openclaw.json 没怎么变化

后续查看 openclaw.json 时，发现其中关于 skills 的条目并不多。

这是正常现象，原因是：

1. apt、npm、pipx 安装的是环境依赖和二进制

2. OpenClaw 在执行 skills check 时会动态扫描当前环境

3. 它不会把"检测到某个二进制存在"自动回写到 openclaw.json

因此：

1. 安装依赖成功，不等于配置文件会自动新增记录

2. openclaw.json 更像"显式配置文件"，用于填 API key、env、enabled、额外参数

（八）ClawHub 相关情况

在使用 clawhub search 搜索技能时，遇到过两类问题：

1. Rate limit exceeded

2. InternalServerError

这说明：

1. 公开搜索接口可能存在限流

2. 服务端也可能存在偶发异常

结论：

1. 不适合短时间高频连续搜索

2. 后续应降低频率，或等服务恢复后再查

3. 也可以直接使用已知 skill 名称，或者优先围绕本地工具型能力建设

（九）关于主模型与特定 skill 的区别

当前主模型 codexzh/gpt-5.4 是正常可用的，这就解释了为什么聊天、代码协助、文档整理都能完成。

要区分两件事：

1. 主模型能不能用

2. 某个特定 skill 能不能用

很多特定 skill 还会额外依赖：

1. 某个 CLI

2. 某个平台 token

3. 某个第三方 API key

所以：

1. 主模型可用，并不代表所有 skill 都自动可用

2. 没有 OpenAI 或 Gemini key，也不会影响当前主模型已经正常工作

（十）为什么当前不优先走 OpenAI / Gemini 路线

从实际需求和环境出发，当前没有把重点放在 OPENAI_API_KEY、GEMINI_API_KEY 上，主要原因有：

1. 当前主模型 codexzh/gpt-5.4 已经可用

2. 中国大陆网络环境下，OpenAI / Gemini 注册、支付、连通性都更折腾

3. 当前更划算的路线是提升本地工具链与稳定运维能力

所以当前阶段的策略是：

1. 先把本地依赖补齐

2. 先提升 Docker、日志、GitHub、终端、文档能力

3. 以后再按需考虑外部 API 型 skill

（十一）Control UI 与 token / 设备状态问题

过程中还分析过一个现象：重启后网页侧像是需要重新 token 或重新配对设备。

最后更合理的判断是：

1. 单独重启 Gateway 通常不会造成大问题

2. 真正容易出问题的是服务器和浏览器同时关闭后再重新进入

3. 刷新网页本身一般不会导致异常

这更像是：

1. 冷启动后的浏览器站点数据、设备身份或本地状态变化

2. 不完全是网关本身的问题

建议：

1. 尽量固定从 http://localhost:18789/ 访问

2. 遇到 UI 状态异常，优先考虑浏览器侧缓存和设备状态，而不是直接怀疑模型配置损坏

（十二）QQ 插件安装问题

后续尝试安装 QQ 插件 @tencent-connect/openclaw-qqbot@latest。

安装过程里出现了两类值得注意的信息：

1. OpenClaw 对插件源码能力给出了安全风险提示，例如 child_process、环境变量访问和网络发送

2. 真正阻断安装的直接原因是 npm 缓存目录权限异常

具体表现为：

1. /home/node/.npm 中存在 root-owned 文件

2. 导致 npm 安装时触发 EACCES

处理建议：

1. 修正 npm 缓存目录属主

2. 再重新尝试安装

这个过程也说明：

1. 第三方插件安装前要先看风险提示

2. 失败时要分清"安全提示"和"真正的报错原因"

六、可重复部署标准方案

（一）总原则

不要依赖"进容器后手工一条条装包"的方式长期维护环境。

更好的方案是：

1. 把已验证有效的依赖固化到自定义镜像

2. 把关键配置固化到 openclaw.json

3. 把工作区说明文档保留好

这样以后不管是重建容器、换机器还是迁移环境，都能快速复原。

（二）建议保留的关键文件

1. /home/node/.openclaw/openclaw.json

2. /home/node/.openclaw/workspace/Dockerfile.openclaw-custom

3. /home/node/.openclaw/workspace/OPENCLAW-DAILY.md

4. /home/node/.openclaw/workspace/OPENCLAW-USE-CASES.md

5. 当前这份总文档

（三）自定义镜像内容建议

自定义镜像里至少建议包含：

1. jq

2. ripgrep

3. ffmpeg

4. tmux

5. git

6. curl

7. python3

8. python3-pip

9. python3-venv

10. python3-full

11. gh

12. unzip

13. zip

14. ca-certificates

15. procps

16. less

17. netcat-openbsd

18. dnsutils

19. pipx

20. clawhub

21. uv

（四）推荐部署流程

每次重建或迁移时，推荐按以下顺序执行：

1. 准备 Dockerfile.openclaw-custom

2. 构建自定义镜像

3. 准备或恢复 openclaw.json

4. 启动 docker compose

5. 访问 Control UI

6. 执行 openclaw skills check

7. 验证主模型对话

8. 验证至少一个已知可用 skill

（五）如果必须临时进入容器补依赖

临时方案可以这样做：

1. 用 docker exec -u 0 -it 进入容器

2. 执行 apt-get update

3. 执行 apt-get install 安装基础工具

4. 执行 npm i -g clawhub

5. 使用 pipx install uv

6. 建立 uv / uvx 的软链接

7. 用 which 和 openclaw skills check 验证

但要明确：

1. 这是应急方法

2. 容器重建后可能丢失

3. 最终还是应该写回 Dockerfile

七、推荐的验证命令

部署完成后，推荐固定执行以下检查：

1. docker compose ps

2. docker logs 网关容器

3. openclaw gateway status

4. openclaw status

5. openclaw skills check

6. which jq

7. which rg

8. which ffmpeg

9. which tmux

10. which gh

11. which clawhub

12. which uv

13. uv --version

八、常见问题与对应处理

（一）apt-get 报权限错误

原因：当前不是 root

处理：docker exec -u 0 -it 进入容器

（二）pip3 install uv 失败

原因：Debian 12 的 PEP 668 保护

处理：改用 pipx install uv

（三）uv 安装成功但找不到命令

原因：安装路径不在 PATH

处理：建立到 /usr/local/bin 的软链接

（四）openclaw.json 没自动新增 skills

原因：依赖安装与配置文件写入是两回事

处理：只在需要显式配置时手动编辑 openclaw.json

（五）clawhub search 被限流

原因：搜索过频或公共出口额度受限

处理：降低查询频率，稍后再试

（六）clawhub search 服务端异常

原因：服务端偶发问题

处理：等待恢复，不要连续猛试

（七）插件安装遇到 EACCES

原因：npm 缓存目录属主不正确

处理：修复 /home/node/.npm 权限后重试

九、当前环境适合怎么用

当前这套环境已经不只是"能聊天"，更适合做这些事：

1. Docker 与 Linux 运维副手

2. 日志排障和问题归纳

3. GitHub issue / PR 辅助

4. 配置文件整理与文档生成

5. tmux 终端协助

6. 视频帧提取与基础媒体处理

7. 健康检查与持续维护

十、当前阶段最合理的策略

综合本次过程，当前最合理的使用与维护策略是：

1. 先以稳定为主，不追求一次性点亮全部 skill

2. 优先使用已经验证可用的 9 个核心 skill

3. 优先强化本地工具型能力，而不是马上堆外部 API 集成

4. 对第三方插件保持谨慎，先看风险提示再装

5. 把当前有效经验沉淀为 Dockerfile、配置文件和文档

十一、当前已产出的配套文件

本次过程中已经整理出的配套文件包括：

1. OpenClaw_Docker_安装与问题处理纪要.docx

2. OpenClaw_Docker_可重复部署操作手册.docx

3. OPENCLAW-DAILY.md

4. OPENCLAW-USE-CASES.md

5. Dockerfile.openclaw-custom

6. 当前这份 OpenClaw_Docker_完整部署与排障总文档.docx

十二、结论

截至目前，可以认为这套 OpenClaw Docker 环境已经达到：

1. 主体可稳定运行

2. 主模型可正常工作

3. 一批高价值 skills 已完成可用化

4. 排障路径已经清楚

5. 重复部署方法已经明确

6. 后续扩展方向也已经清晰

如果后续继续增强，建议仍然保持一个原则：

先固化已经验证有效的东西，再扩展新能力；先重稳定与复用，再追求功能数量。

整理时间：2026-03-11 00:58 UTC