本文是我在 Linux 系统下，使用 Docker 方式安装和配置 OpenClaw 的实践记录，这样既不影响当前工作环境，又避免了误操作和数据泄露的风险。相对宿主机安装，Docker安装操作在浏览器时会稍微麻烦一点（使用CDP协议），但不用买新机器，又能保证数据安全，还挺重要的。
文中详细列出了从环境准备、安装步骤到实际使用中遇到的关键问题（如用户权限、服务配对和网络连接）及其解决方案，旨在为有类似需求的开发者提供一份可直接参考的避坑指南。
1 项目资源
- 官方网站：https://clawd.bot/
- 代码仓库：https://www.xplaza.cn/xppplaza/op…
2 项目概况
OpenClaw 是一个以 TypeScript 为主的大型项目，代码量超过 50 万行。其运行环境要求 Node.js ≥ 22，同时官方也提供了 Docker 安装方式，便于部署。
项目配置主要涉及两个文件：
- 源码目录中的
.env文件，用于设置环境变量。 - 根据用户配置生成的
/home/node/.openclaw/openclaw.json文件。
3 模型选择与成本
如果主要目的是测试 OpenClaw 的功能，在模型成本上有一个高性价比的选择：Kimi 2.5。
获取试用与 Token：
- 访问 Kimi Code (https://www.kimi.com/code) 可开通 4.99 元/7 天 的试用。请注意，此试用为自动续费，若后续不需使用，请务必在微信支付管理中及时关闭。
- 开通后，可在控制台 (https://www.kimi.com/code/consol…) 查看用量并获取 API Token。
4 Docker 安装指南
官方 Docker 安装文档：https://github.com/openclaw/op…nclaw/blob/main/docs/install/docker.md
4.1 准备工作：创建专用用户
为避免权限混乱并实现数据隔离，建议创建一个专用的 node 用户来运行 OpenClaw。
4.2 获取与构建代码
项目迭代迅速，建议拉取最新代码。生产环境建议切换到稳定版本。以下以获取 v2026.2.2 版本为例。
安装脚本说明：
- 如果因网络问题导致下载缓慢或失败，可在构建时通过
--build-arg参数指定代理，形如：--build-arg HTTP_PROXY=http://192.168.10.168:12346 --build-arg HTTPS_PROXY=http://192.168.10.168:12346 - 该脚本会先执行
docker build构建镜像（构建后约 4.2GB，请注意磁盘空间）。 - 随后进入交互式引导配置，选择：Manual->Local gateway->Moonshot AI->Kimi Coding API key->Keep current->Gateway bind: 0.0.0.0->Token，其余非必要步骤均可跳过以简化流程。
- 设置中如果提示：
/home/node/.openclaw/，请参考后面的“常见问题与解决方案”部分。
提示：如果安装引导过程卡住，可按 Ctrl+C 中断。随后检查 /home/node/.openclaw/ 目录下的配置文件openclaw.json是否已正确生成。若文件正常，可直接手动启动服务：
4.3 访问管理面板
安装并启动成功后，即可通过浏览器访问 OpenClaw 的管理面板。
- 访问地址：
http://localhost:18789?token=<你的Token> - Token 获取：安装过程中
docker-setup.sh脚本会显示用于认证的 Token（有的版本token是自己输入的），请妥善保存。
正常打开网页后，就可以在此和 openclaw 聊天了。
5 常见问题与解决方案
5.1 用户 ID 不一致导致的权限问题
问题描述：在已存在常规用户（如 linux，UID=1000）的系统上新建 node 用户，其 UID 通常为 1001。而 OpenClaw 的 Docker 镜像内默认 node 用户的 UID 为 1000。这种 UID 不匹配会导致容器无法读写宿主机上由“真 node 用户”创建的数据目录。
解决方案：调整宿主机上配置目录的权限，使其对所有用户可读写（适用于测试环境）。
注意：更规范的长期解决方案是在构建 Docker 镜像时指定与宿主机 node 用户一致的 UID/GID，或创建用户时直接指定 UID=1000。
5.2 浏览器访问提示 “Pairing Required”
问题描述：在浏览器中使用 Token 访问管理面板时，连接被拒绝，并提示 pairing required (1008)。按照官方文档的配对流程可能无法解决。
解决方案：此问题通常由严格的安全校验导致。可通过修改配置，允许不安全的认证方式来绕过初始配对。编辑配置文件：
在 gateway 配置段中，确保 controlUi.allowInsecureAuth 设置为 true。一个完整的配置示例如下（主要是 controlUi 部分）：
修改后，重启网关服务以使配置生效
5.3 CLI 客户端无法连接网关
问题描述：openclaw-cli 客户端容器无法连接到 openclaw-gateway 网关容器。
解决方案：此问题通常是因为 CLI 容器内部无法正确解析网关地址。需在 openclaw.json 的 gateway 部分明确指定网关的可访问 URL（如宿主机局域网 IP，如：ws://192.168.10.165:18789）。
补充说明：openclaw-cli 客户端的主要用途是在初始安装阶段生成配置。日常管理和操作完全可以通过直接 exec 进入 openclaw-gateway 容器内执行命令来完成，因此 CLI 与 Gateway 的网络连通性并非必需。
6 参考文档
- OpenClaw+Kimi K2.5+Moltbook保姆级部署指南，确实可以封神了！
https://blog.csdn.net/qq_43270074/article/details/157669461
7 后记
实话说，安装起来确实有点麻烦。作者也提到他完全依赖大模型生成代码，自己并不 review。当代码量变得庞大且复杂时，即使有大模型的辅助，也很难在每次修改时全面考虑到层层调用逻辑的关联。所以这次安装的时候，即使完全按照界面提示操作，某些设置还是会引发“找不到变量xxx”、卡住等问题，也可能是我用的环境比较小众。
这个迭代速度实在太快了。上周项目的名字还叫“小龙虾”时，对应的 Docker 镜像大小是1.88G，这周就已经增加到4.2G了（增加了playwright, python等工具）；两次安装过程中遇到的问题也完全不一样。上周 TypeScript 的有效代码量是45万行，本周已经增长到了50万行；我试用了核心功能后感觉，有很大精简余地。随着项目变得越来越复杂和庞大，重构可能会影响功能，不重构慢慢就驾驭不了了。也许是我OUT了，AI时代没有这个问题？拭目以待吧。
尽管安装过程让人头秃，但用起来是真香，而且我觉得 token 的用量目前也是可控且可以接受的，使用Docker方法安装也并没有想象中那么危险和不可控，后续会单开文章聊聊使用体验以及那些令人惊艳的使用场景。
信创、开源、人工智能资源，尽在XPlaza信创开源广场！
