跳到主要内容
OpenClaw 汉化版部署与常见问题排查指南 | 极客日志
JavaScript Node.js AI 大前端
OpenClaw 汉化版部署与常见问题排查指南 综述由AI生成 OpenClaw 汉化版部署涉及 npm 安装、Docker 容器化及网关配置等多个环节,常因网络源、权限、环境变量或 Token 认证导致失败。档梳理了从镜像拉取慢、模块找不到、配置未初始化到 Dashboard 连接异常的全流程排查路径。重点解决 gateway.mode 设置、trustedProxies 信任代理、HTTPS 安全限制及 Ollama 模型对接问题,提供具体的命令行修复指令与配置修改示例,帮助用户快速恢复服务并实现内网或远程访问。
云间运维 发布于 2026/3/21 更新于 2026/4/25 2 浏览OpenClaw 汉化版部署与常见问题排查指南
遇到部署问题?建议按错误消息搜索本页,或根据场景分类查找解决方案。
快速修复
Missing workspace template: AGENTS.md
现象 :
Error: Missing workspace template : AGENTS.md (C:\Users\xxx\docs\reference\templates\AGENTS.md). Ensure docs/reference/templates are packaged.
影响版本 :2026.2.4-zh.1 及更早版本
原因 :汉化版构建时修改了包名为 @qingchencloud/openclaw-zh,但上游代码中有一处硬编码只识别 openclaw 包名,导致运行时无法定位模板文件、Dashboard 资源等关键路径。
处理建议 :
npm install -g @qingchencloud/openclaw-zh@latest
npm install -g @qingchencloud/openclaw-zh@nightly
此 Bug 已在 2026.2.4-zh.2 版本修复。如果升级后仍有问题,请尝试完全重装:
npm uninstall -g @qingchencloud/openclaw-zh
npm install -g @qingchencloud/openclaw-zh@latest
安装问题
安装卡住不动 / 下载很慢
现象 :运行安装脚本后长时间没有反应,或 npm install 进度条不动。
原因 :npm 默认从国外源下载,中国大陆网络访问慢。
处理建议 :
npm install -g @qingchencloud/openclaw-zh@latest --registry=https://registry.npmmirror.com
npm config set registry https://registry.npmmirror.com
npm install -g @qingchencloud/openclaw-zh@latest
如果是 Docker 镜像拉取慢,参考 Docker 部署指南中的镜像加速方案。
Control UI assets not found
现象 :终端输出类似:
Control UI assets not found. Build them with `pnpm ui:build` (auto-installs UI deps), or run `pnpm ui:dev` during development.
原因 :可能安装了原版 openclaw 而不是汉化版,或者安装过程中断导致文件不完整。
npm uninstall -g openclaw
npm uninstall -g @qingchencloud/openclaw-zh
npm cache clean --force
npm install -g @qingchencloud/openclaw-zh@latest
openclaw --version
如果仍然报错,检查你的 Node.js 版本是否 >= 22:node -v
MODULE_NOT_FOUND / systemd 服务路径错误 Error : Cannot find module '/home/ xxx/.npm-global/ lib/node_modules/ openclaw/dist/ index.js'
原因 :systemd 服务配置文件中写的路径是原版 openclaw 的路径,但你安装的是汉化版 @qingchencloud/openclaw-zh,两者的路径不同。
which openclaw
npm list -g @qingchencloud/openclaw-zh --depth=0
openclaw onboard --install-daemon
systemctl --user status openclaw-gateway
如果 onboard --install-daemon 不能修复,手动编辑 systemd 文件:
systemctl --user cat openclaw-gateway
systemctl --user edit openclaw-gateway --force
systemctl --user daemon-reload
systemctl --user restart openclaw-gateway
安装后运行还是英文 现象 :运行 openclaw --help 或打开 Dashboard,界面仍然是英文。
原因 :系统中同时存在原版 openclaw 和汉化版,命令调用的是原版。
npm uninstall -g openclaw
npm install -g @qingchencloud/openclaw-zh@latest
openclaw --version
启动问题
Missing config. Run openclaw setup Missing config. Run `openclaw setup` or set gateway.mode=local(or pass --allow-unconfigured).
docker exec -it openclaw openclaw setup
docker exec openclaw openclaw config set gateway.mode local
docker restart openclaw
如果是 docker-compose,将 docker exec openclaw 替换为 docker-compose exec openclaw
gateway.mode is unset gateway.mode 未设置;网关启动将被阻止。
原因 :配置中缺少 gateway.mode 字段。
openclaw config set gateway.mode local
docker exec openclaw openclaw config set gateway.mode local
docker restart openclaw
Invalid config / Unrecognized keys Invalid config at /root/.openclaw/openclaw.json:-<root>: Unrecognized keys:"gatewayToken" ,"port" ,...
原因 :配置文件格式过旧,包含新版本不识别的字段(通常是从旧版升级后出现)。
openclaw doctor
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
openclaw setup
docker exec openclaw openclaw doctor
docker exec openclaw cp /root/.openclaw/openclaw.json /root/.openclaw/openclaw.json.bak
docker exec -it openclaw openclaw setup
docker restart openclaw
Docker 容器一直重启 现象 :docker ps 显示容器状态为 Restarting,或 docker logs 反复输出错误。
docker logs openclaw
docker stop openclaw && docker rm openclaw
docker run --rm -v openclaw-data:/root/.openclaw ghcr.io/1186258278/openclaw-zh:latest openclaw setup
docker run --rm -v openclaw-data:/root/.openclaw ghcr.io/1186258278/openclaw-zh:latest openclaw config set gateway.mode local
docker run -d --name openclaw -p 18789:18789 -v openclaw-data:/root/.openclaw --restart unless-stopped ghcr.io/1186258278/openclaw-zh:latest openclaw gateway run
Gateway not running / 网关未运行 现象 :运行 openclaw doctor 提示"网关未运行",或 Dashboard 无法访问。
openclaw gateway start
openclaw onboard --install-daemon
docker restart openclaw
Dashboard 连不上 遇到 Dashboard 无法连接?可按以下逻辑排查:
完全打不开(空白/超时) :检查网关是否启动。npm 环境运行 openclaw gateway start,Docker 环境运行 docker restart openclaw。
页面加载了但报错 :查看错误消息是什么。
token mismatch :用 openclaw dashboard 打开,或手动加 ?token=xxx。
pairing required :运行 openclaw devices list 然后 devices approve ID。
requires HTTPS :设置 Token 认证,或用 SSH 端口转发。
Proxy headers untrusted :配置 trustedProxies。
token not configured :设置 gateway.auth.token。
gateway token mismatch / unauthorized disconnected (1008 ): unauthorized: gateway token mismatch
原因 :访问 Dashboard 时没有带正确的 Token,或 Token 不匹配。
openclaw dashboard
docker exec openclaw openclaw dashboard --print-url
openclaw config get gateway.auth.token
pairing required / 设备配对 disconnected (1008 ): pairing required
原因 :这是 OpenClaw 的安全机制。每个浏览器首次连接都需要管理员批准。
openclaw devices list
openclaw devices approve 693d5641-xxxx-xxxx-xxxx-xxxxxxxxxxxx
注意:清除浏览器缓存、换浏览器、用无痕模式都会生成新的设备 ID,需要重新批准。
control ui requires HTTPS or localhost 原因 :通过 HTTP(非 localhost)访问 Dashboard,浏览器阻止了设备身份验证功能。
openclaw config set gateway.auth.token 你的密码
openclaw gateway restart
docker exec openclaw openclaw config set gateway.auth.token 你的密码
docker restart openclaw
ssh -L 18789:127.0.0.1:18789 user@服务器 IP
方案 3:配置 HTTPS 反向代理
参考 Docker 部署指南 - Nginx 反代。
现象 :使用 Nginx 反向代理后,Dashboard 报此错误。
原因 :OpenClaw 检测到反向代理的请求头,但代理的 IP 不在信任列表中。
openclaw config set gateway.trustedProxies '["127.0.0.1", "::1"]'
openclaw gateway restart
docker exec openclaw openclaw config set gateway.trustedProxies '["127.0.0.1", "::1"]'
docker restart openclaw
如果 Nginx 和 OpenClaw 不在同一台机器,把 127.0.0.1 换成 Nginx 服务器的 IP。
Gateway auth is set to token, but no token is configured 原因 :网关认证模式设为 Token,但没有配置 Token 值。
openclaw config set gateway.auth.token 你的密码
docker exec openclaw openclaw config set gateway.auth.token 你的密码
docker restart openclaw
export OPENCLAW_GATEWAY_TOKEN=你的密码
内网 / 远程访问
npm 安装后,内网其他电脑无法访问 现象 :在服务器上安装后,本机 localhost:18789 能打开,但内网其他电脑访问 http://服务器 IP:18789 失败。
原因 :默认情况下,网关只监听 127.0.0.1(本机回环),不接受来自外部的连接。
openclaw config set gateway.bind lan
openclaw config set gateway.auth.token 你的密码
openclaw gateway restart
openclaw onboard --install-daemon
然后在其他电脑上访问 http://服务器 IP:18789,在「网关令牌」输入你设的密码。
sudo ufw allow 18789
sudo firewall-cmd --add-port=18789/tcp --permanent && sudo firewall-cmd --reload
netsh advfirewall firewall add rule name="OpenClaw" dir =in action=allow protocol=TCP localport=18789
Docker 远程部署后访问不了 现象 :Docker 容器启动成功,但从其他机器访问 http://服务器 IP:18789 没反应。
容器是否在运行?docker ps | grep openclaw
端口是否映射了?确认 -p 18789:18789 参数
网关模式是否设置了?docker exec openclaw openclaw config get gateway.mode
是否绑定了局域网?docker exec openclaw openclaw config get gateway.bind
防火墙是否放行了?参考上面的防火墙命令
docker exec openclaw openclaw config set gateway.mode local
docker exec openclaw openclaw config set gateway.bind lan
docker exec openclaw openclaw config set gateway.auth.token 你的密码
docker restart openclaw
Docker 远程访问是否必须用 HTTPS? 不是必须的。设置 Token 认证就可以通过 HTTP 远程访问。
docker exec openclaw openclaw config set gateway.auth.token 你的密码
docker restart openclaw
然后在 Dashboard 的「网关令牌」输入框填入密码即可。
只有在不设 Token 的情况下,浏览器才会因为安全策略(Web Crypto API 需要 HTTPS)阻止连接。
模型和对话
本地 Ollama 模型调用无响应 现象 :在 Dashboard 的对话界面输入消息后,没有任何回复,也没有报错。
curl http://localhost:11434/api/tags
openclaw config get agents.defaults.model
openclaw config get auth.openai.baseURL
openclaw config set agents.defaults.model openai/llama3.2
openclaw config set auth.openai.baseURL http://localhost:11434/v1
openclaw config set auth.openai.apiKey ollama
Docker 环境中 localhost 指的是容器内部。如果 Ollama 在宿主机运行,请用 host.docker.internal 替代 localhost:
如何使用自定义的 OpenAI 兼容接口 适用于 :OneAPI、New API、各种中转站、国产模型 API 等。
openclaw config set agents.defaults.model openai/gpt-4o
openclaw config set auth.openai.baseURL https://your-api.example.com/v1
openclaw config set auth.openai.apiKey sk-your-api-key
baseURL 末尾通常需要加 /v1,但具体取决于你的 API 服务。
对话语言是中文吗? 对话语言取决于你使用的 AI 模型,与本汉化项目无关。
Claude、GPT-4 等主流模型都支持中文对话
你可以在系统提示中设置"请用中文回复"
本项目只汉化界面(CLI + Dashboard),不影响对话内容
其他问题
左上角图标不显示 现象 :Dashboard 左上角的 OpenClaw Logo 显示为空白或破损图标。
原因 :旧版本使用了外部 CDN 图标链接,网络不通导致加载失败。新版已修复。
npm update -g @qingchencloud/openclaw-zh
如何更新到最新版
npm update -g @qingchencloud/openclaw-zh
docker pull ghcr.io/1186258278/openclaw-zh:latest
docker stop openclaw && docker rm openclaw
docker run -d --name openclaw -p 18789:18789 -v openclaw-data:/root/.openclaw --restart unless-stopped ghcr.io/1186258278/openclaw-zh:latest openclaw gateway run
查看当前版本:openclaw --version
如何切换回原版 npm uninstall -g @qingchencloud/openclaw-zh
npm install -g openclaw
如何彻底卸载 npm uninstall -g @qingchencloud/openclaw-zh
npm uninstall -g openclaw
Remove-Item-Recurse -Force "$env :USERPROFILE\.openclaw"
npm uninstall -g @qingchencloud/openclaw-zh
npm uninstall -g openclaw
rm -rf ~/.openclaw
注意:npm uninstall openclaw 不会卸载汉化版,必须用完整包名 @qingchencloud/openclaw-zh
Docker 权限问题 EACCES: permission denied 原因 :使用了 bind mount(绑定宿主机目录)时,容器内用户没有写入权限。
docker run -d --name openclaw -p 18789:18789 -v openclaw-data:/root/.openclaw ghcr.io/1186258278/openclaw-zh:latest openclaw gateway run
sudo chown -R 1000:1000 /你的目录路径
Docker 拉取镜像报 denied 或 unauthorized
docker logout ghcr.io
docker pull ghcr.io/1186258278/openclaw-zh:latest
飞牛 NAS / 群晖等设备如何部署 可以使用 Docker 方式部署,参考 Docker 部署指南。
核心步骤:
在 NAS 的 Docker 管理界面中拉取镜像 ghcr.io/1186258278/openclaw-zh:latest
创建容器,端口映射 18789:18789,挂载数据卷
进入容器终端执行 openclaw setup 初始化
设置 openclaw config set gateway.mode local
重启容器
相关免费在线工具 RSA密钥对生成器 生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
Mermaid 预览与可视化编辑 基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
随机西班牙地址生成器 随机生成西班牙地址(支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选),支持数量快捷选择、显示全部与下载。 在线工具,随机西班牙地址生成器在线工具,online
Keycode 信息 查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具,Keycode 信息在线工具,online
Escape 与 Native 编解码 JavaScript 字符串转义/反转义;Java 风格 \uXXXX(Native2Ascii)编码与解码。 在线工具,Escape 与 Native 编解码在线工具,online
JavaScript / HTML 格式化 使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具,JavaScript / HTML 格式化在线工具,online