本文是我在 Linux 系统下，使用 Docker 方式安装和配置 OpenClaw 的实践记录，这样既不影响当前工作环境，又避免了误操作和数据泄露的风险。相对宿主机安装，Docker安装操作在浏览器时会稍微麻烦一点（使用CDP协议），但不用买新机器，又能保证数据安全，还挺重要的。

文中详细列出了从环境准备、安装步骤到实际使用中遇到的关键问题（如用户权限、服务配对和网络连接）及其解决方案，旨在为有类似需求的开发者提供一份可直接参考的避坑指南。

1 项目资源

  • 官方网站：https://clawd.bot/
  • 代码仓库： https://github.com/openclaw/openclaw (注：项目曾用名 Moltbot)

2 项目概况

OpenClaw 是一个以 TypeScript 为主的大型项目，代码量超过 50 万行。其运行环境要求 Node.js ≥ 22，同时官方也提供了 Docker 安装方式，便于部署。

项目配置主要涉及两个文件：

  • 源码目录中的 .env 文件，用于设置环境变量。
  • 根据用户配置生成的 $HOME/.openclaw/openclaw.json 文件。

3 模型选择与成本

如果主要目的是测试 OpenClaw 的功能，在模型成本上有一个高性价比的选择：Kimi 2.5。

获取试用与 Token：

  • 访问 Kimi Code (https://www.kimi.com/code) 可开通 4.99 元/7 天 的试用。请注意，此试用为自动续费，若后续不需使用，请务必在微信支付管理中及时关闭。
  • 开通后，可在控制台 (https://www.kimi.com/code/console) 查看用量并获取 API Token。

4 Docker 安装指南

官方 Docker 安装文档：https://github.com/openclaw/openclaw/blob/main/docs/install/docker.md

4.1 获取与构建代码

项目迭代迅速，建议拉取最新代码。生产环境建议切换到稳定版本。以下以获取 v2026.2.2 版本为例。

1
2
3
4
5
6
git clone https://github.com/openclaw/openclaw
cd openclaw
git tag
git checkout -b v2026.3.23-2 v2026.3.23-2 # 切到一个相对稳定的分支
./docker-setup.sh

可以手动调整 DockerBuild时可加几个参数： - OPENCLAW_INSTALL_BROWSER=1
作用：构建时安装 Chromium 和 Xvfb，还会把 Playwright 的浏览器依赖装好，形如：--build-arg OPENCLAW_INSTALL_BROWSER=1 - OPENCLAW_DOCKER_APT_PACKAGES="python3 wget …"
作用：构建时顺手把你要的系统包一起装进去，运行时默认用户确实是 node，Dockerfile 最后明确切到了非 root 用户运行，也就是 USER node。聊天过程中基本不能安装系统级命令行工具，如果需要什么工具，可以在这里指定。至少python3-pip python3-venv 在我使用的版本里没有，并且是肯定需要的

安装脚本说明：

  • 如果因网络问题导致下载缓慢或失败，可在docker build构建镜像时，通过 --build-arg 参数指定代理，形如：--build-arg HTTP_PROXY=http://192.168.10.168:12346 --build-arg HTTPS_PROXY=http://192.168.10.168:12346
  • 该脚本会先执行 docker build 构建镜像（构建后约 3.22GB，包含浏览器的 4.13G），这里本身带基本的python和Node.js环境。
  • 随后进入交互式引导配置，选择：Manual->Local gateway->Moonshot AI->Kimi Coding API key->Keep current->Gateway bind: 0.0.0.0->Token，其余非必要步骤均可跳过以简化流程。
  • 设置中如果提示的 Workspace directory 指镜像内的目录，一般不改，是容器中用户数据存储的目录，建议不改动。
  • 默认的登录用户是node，没有系统权限，安装工具不太方便，但有些 node.js 工具可以安装当前用户下面。后面还是要把安装位置映射出来，以免重打镜像后都要重新安装

提示：如果安装引导过程卡住，可按 Ctrl+C 中断。随后检查 $HOME/.openclaw/ 目录下的配置文件openclaw.json是否已正确生成。若文件正常，可直接手动启动服务：

1
2
docker compose up -d openclaw-gateway

如果一开始没有登录，后面也可以运行后再登录 

1
openclaw models auth login --provider github-copilot

4.2 访问管理面板

安装并启动成功后，即可通过浏览器访问 OpenClaw 的管理面板。

  • 访问地址：http://localhost:18789?token=<你的Token>
  • Token 获取：安装过程中 docker-setup.sh 脚本会显示用于认证的 Token（有的版本token是自己输入的），请妥善保存。

正常打开网页后，就可以在此和 openclaw 聊天了。

5 常见问题与解决方案

5.1 登录错误提示1

在web登录时提示： origin not allowed (open the Control UI from the gateway host or allow it in gateway.controlUi.allowedOrigins)

在非本机的环境下安装常会遇到这个问题，把访问它的网址加入就行，比如“http://192.168.10.168:18789”

按提示修改$HOME/.openclaw/openclaw.json中的allowedOrigins。 改完后重启容器docker restart openclaw-openclaw-gateway-1

5.2 登录错误提示2

在web登录时提示： control ui requires device identity (use HTTPS or localhost secure context)

出于安全因素，用 http://局域网IP:端口，通常不满足。 临时解决方案是修改 $HOME/.openclaw/openclaw.json 中的 controlUi 部分，加入：

1
"dangerouslyDisableDeviceAuth": true

但这样不安全，不建议这么做。

5.3 登录错误提示3

浏览器访问提示 “Pairing Required”

原因：这个设备当时在待审批列表里，还没批准，所以即使 token 对了，也会被拒绝。

解决方法：

1
2
3
4
5
cd /exports/git/openclaw

docker compose run --rm openclaw-cli devices list
# 如果看到 `Pending`，就批准：
docker compose run --rm openclaw-cli devices approve <requestId>

5.4 用户 ID 不一致导致的权限问题

问题描述：在已存在常规用户（如 linux，UID=1000）的系统上新建 node 用户，其 UID 通常为 1001。而 OpenClaw 的 Docker 镜像内默认 node 用户的 UID 为 1000。这种 UID 不匹配会导致容器无法读写宿主机上由“真 node 用户”创建的数据目录。

解决方案：调整宿主机上配置目录的权限，使其对所有用户可读写（适用于测试环境）。

1
2
sudo chmod 777 /home/node/.openclaw -R

注意：更规范的长期解决方案是在构建 Docker 镜像时指定与宿主机 node 用户一致的 UID/GID，或创建用户时直接指定 UID=1000。

5.5 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方法安装也并没有想象中那么危险和不可控，后续会单开文章聊聊使用体验以及那些令人惊艳的使用场景。