1. 首页首页
  2. 科技前沿科技前沿

部署开源OpenClaw汉化中文版过程中常见问题排查手册

科技前沿 • • 阅读 0

部署开源OpenClaw汉化中文版过程中常见问题排查手册遇到问题 按错误消息搜索本页 或按场景分类查找解决方案 部署 OpenClaw 汉化版又双叒叕报错了 别慌 这份实战排查手册 专为 踩坑 而生 无论是 Docker 镜像拉取失败 容器启动闪退 还是 Dashboard 死活连不上 远程访问 502 报错 我们按错误场景分类整理 支持按错误关键词秒搜定位 每个解决方案均来自真实部署案例 附带紧急修复通道 和根因分析

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



遇到问题？按错误消息搜索本页，或按场景分类查找解决方案。

部署 OpenClaw 汉化版又双叒叕报错了？别慌！这份实战排查手册专为「踩坑」而生。

无论是 Docker 镜像拉取失败、容器启动闪退，还是 Dashboard 死活连不上、远程访问 502 报错——我们按错误场景分类整理，支持按错误关键词秒搜定位。每个解决方案均来自真实部署案例，附带紧急修复通道和根因分析，让你从「报错一脸懵」到「秒级排障」。

OpenClaw中文版

你会看到：

Error: Missing workspacetemplate: 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

如果使用 nightly 版

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 默认从国外源下载，中国大陆网络访问慢。

解决方案：

# 方法1：使用淘宝镜像源安装（推荐） npm install -g @qingchencloud/openclaw-zh@latest –registry=https://registry.npmmirror.com

方法2：先切换全局镜像源，再安装

npm configsetregistry https://registry.npmmirror.com npm install -g @qingchencloud/openclaw-zh@latest

如果是 Docker 镜像拉取慢，参考Docker 部署指南中的镜像加速方案。

你会看到：终端输出类似：

Control UI assetsnotfound. Build them with pnpm ui:build (auto-installs UI deps),orrun pnpm ui:dev during development.

原因：你可能安装了原版openclaw而不是汉化版，或者安装过程中断导致文件不完整。

解决方案：

# 第1步：卸载所有版本 npm uninstall -g openclaw npm uninstall -g @qingchencloud/openclaw-zh

第2步：清除 npm 缓存

npm cache clean –force

第3步：重新安装汉化版

npm install -g @qingchencloud/openclaw-zh@latest

第4步：验证安装

openclaw –version

如果仍然报错，检查你的 Node.js 版本是否 >= 22：node -v

你会看到：服务启动失败，日志显示：

Error: Cannot findmodule‘/home/xxx/.npm-global/lib/node_modules/openclaw/dist/index.js’

原因：systemd 服务配置文件中写的路径是原版openclaw的路径，但你安装的是汉化版@qingchencloud/openclaw-zh，两者的路径不同。

解决方案：

# 第1步：找到汉化版的实际安装路径 whichopenclaw

或者

npm list -g @qingchencloud/openclaw-zh –depth=0

第2步：重新安装守护进程（会自动修复路径）

openclaw onboard –install-daemon

第3步：检查服务状态

systemctl –user status openclaw-gateway

如果onboard –install-daemon不能修复，手动编辑 systemd 文件：

# 查看当前配置 systemctl –user cat openclaw-gateway

编辑，将 ExecStart 路径改为实际路径

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

验证（应显示汉化版版本号，如 2026.2.4-zh.1）

openclaw –version

你会看到：启动时终端输出：

Missing config. Run openclaw setuporsetgateway.mode=local (orpass –allow-unconfigured).

原因：首次运行没有执行初始化，或配置文件被删除。

解决方案：

npm 环境：

# 运行初始化向导 openclaw onboard

Docker 环境：

# 在容器内执行初始化 dockerexec-it openclaw openclaw setup

设置网关模式

dockerexecopenclaw openclaw configsetgateway.modelocal

重启容器

docker restart openclaw

如果是 docker-compose，将docker exec openclaw替换为docker-compose exec openclaw

你会看到：Doctor 诊断输出：

gateway.mode 未设置；网关启动将被阻止。

原因：配置中缺少gateway.mode字段。

解决方案：

# npm 环境 openclaw configsetgateway.modelocal

Docker 环境

dockerexecopenclaw openclaw configsetgateway.modelocal docker restart openclaw

你会看到：启动时报错：

Invalid config at /root/.openclaw/openclaw.json:

  • <root>: Unrecognized keys:“gatewayToken”,“port”, …

    原因：配置文件格式过旧，包含新版本不识别的字段（通常是从旧版升级后出现）。

    解决方案：

    # 方法1：用 doctor 自动修复 openclaw doctor

方法2：备份并重建配置

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak openclaw setup

Docker 环境：

dockerexecopenclaw openclaw doctor

或备份后重建

dockerexecopenclaw cp /root/.openclaw/openclaw.json /root/.openclaw/openclaw.json.bak dockerexec-it openclaw openclaw setup docker restart openclaw

你会看到：docker ps显示容器状态为Restarting，或docker logs反复输出错误。

原因：通常是配置未初始化。

解决方案：

# 第1步：查看日志找到具体错误 docker logs openclaw

第2步：根据日志中的错误消息，对照本文档找到对应解决方案

最常见情况：重新初始化配置

docker stop openclaw && docker rm openclaw

或安装守护进程（推荐，会开机自启）

openclaw onboard –install-daemon

Docker 环境：重启容器

docker restart openclaw

遇到 Dashboard 无法连接？按下面的流程图排查：

flowchart TD Start[“Dashboard 打不开或报错”] –> Q1{“页面能加载吗？”} Q1 –>|“完全打不开（空白/超时）”| A1[“检查网关是否启动”] Q1 –>|“页面加载了但报错”| Q2{“错误消息是什么？”}

A1 –> A1Fix[“npm: openclaw gateway start\nDocker: docker restart openclaw”]

Q2 –>|“token mismatch”| TokenFix[“用 openclaw dashboard 打开\n或手动加 ?token=xxx”] Q2 –>|“pairing required”| PairFix[“openclaw devices list\n然后 devices approve ID”] Q2 –>|“requires HTTPS”| HttpsFix[“设置 Token 认证\n或用 SSH 端口转发”] Q2 –>|“Proxy headers untrusted”| ProxyFix[“配置 trustedProxies”] Q2 –>|“token not configured”| ConfigFix[“设置 gateway.auth.token”]

你会看到：Dashboard 右下角红色提示：

disconnected (1008): unauthorized: gateway token mismatch

原因：你访问 Dashboard 时没有带正确的 Token，或 Token 不匹配。

解决方案：

# 方法1（推荐）：用命令自动打开带 Token 的 URL openclaw dashboard

Docker 环境：获取带 Token 的 URL

dockerexecopenclaw openclaw dashboard –print-url

复制输出的 URL 到浏览器打开

手动方法：

你会看到：Dashboard 显示：

disconnected (1008): pairing required

原因：这是 OpenClaw 的安全机制。每个浏览器首次连接都需要管理员批准。

解决方案：

# 第1步：查看待批准的设备 openclaw devices list

Docker: docker exec openclaw openclaw devices list –password ‘你的Token’

第2步：复制 Request ID，批准它

openclaw devices approve 693d5641-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Docker: docker exec openclaw openclaw devices approve 693d5641-xxxx-xxxx-xxxx-xxxxxxxxxxxx

第3步：回到 Dashboard，点击「连接」

注意：清除浏览器缓存、换浏览器、用无痕模式都会生成新的设备 ID，需要重新批准。

你会看到：Dashboard 显示安全限制提示。

原因：你通过 HTTP（非 localhost）访问 Dashboard，浏览器阻止了设备身份验证功能。

解决方案（任选一种）：

方案1：设置 Token 认证（最简单）

# npm 环境 openclaw configsetgateway.auth.token 你的密码 openclaw gateway restart

Docker 环境

dockerexecopenclaw openclaw configsetgateway.auth.token 你的密码 docker restart openclaw

然后在 Dashboard 的「网关令牌」输入框填入你的密码

方案2：SSH 端口转发（更安全）

ssh -L 18789:127.0.0.1:18789 user@服务器IP

然后访问 http://localhost:18789（走的是加密隧道）

方案3：配置 HTTPS 反向代理

参考Docker 部署指南 - Nginx 反代

你会看到：使用 Nginx 反向代理后，Dashboard 报此错误。

原因：OpenClaw 检测到反向代理的请求头，但代理的 IP 不在信任列表中。

解决方案：

# npm 环境 openclaw configsetgateway.trustedProxies‘[“127.0.0.1”, “::1”]’ openclaw gateway restart

Docker 环境

dockerexecopenclaw openclaw configsetgateway.trustedProxies‘[“127.0.0.1”, “::1”]’ docker restart openclaw

如果 Nginx 和 OpenClaw 不在同一台机器，把127.0.0.1换成 Nginx 服务器的 IP。

你会看到：启动日志中出现此警告。

原因：网关认证模式设为 Token，但没有配置 Token 值。

解决方案：

# npm 环境 openclaw configsetgateway.auth.token 你的密码

Docker 环境

dockerexecopenclaw openclaw configsetgateway.auth.token 你的密码 docker restart openclaw

或通过环境变量设置

exportOPENCLAW_GATEWAY_TOKEN=你的密码

你会看到：在服务器上安装后，本机localhost:18789能打开，但内网其他电脑访问http://服务器IP:18789失败。

原因：默认情况下，网关只监听127.0.0.1（本机回环），不接受来自外部的连接。

解决方案：

# 第1步：配置网关监听局域网 openclaw configsetgateway.bind lan

第2步：设置访问密码（必须，否则外部访问会被拒绝）

openclaw configsetgateway.auth.token 你的密码

第3步：重启网关

openclaw gateway restart

第4步（可选）：安装守护进程，让 OpenClaw 开机自启

openclaw onboard –install-daemon

然后在其他电脑**问http://服务器IP:18789，在「网关令牌」输入你设的密码。

还是访问不了？检查防火墙：

# Ubuntu / Debian sudo ufw allow 18789

CentOS / RHEL

sudo firewall-cmd –add-port=18789/tcp –permanent && sudo firewall-cmd –reload

Windows

netsh advfirewall firewall add rule name=“OpenClaw”dir=inaction=allow protocol=TCP localport=18789

你会看到：Docker 容器启动成功，但从其他机器访问http://服务器IP:18789没反应。

检查清单：

  1. 容器是否在运行？docker ps | grep openclaw
  2. 端口是否映射了？确认-p 18789:18789参数
  3. 网关模式是否设置了？docker exec openclaw openclaw config get gateway.mode
  4. 是否绑定了局域网？docker exec openclaw openclaw config get gateway.bind
  5. 防火墙是否放行了？参考上面的防火墙命令

一次性修复：

dockerexecopenclaw openclaw configsetgateway.modelocal dockerexecopenclaw openclaw configsetgateway.bind lan dockerexecopenclaw openclaw configsetgateway.auth.token 你的密码 docker restart openclaw

不是必须的。设置 Token 认证就可以通过 HTTP 远程访问。

dockerexecopenclaw openclaw configsetgateway.auth.token 你的密码 docker restart openclaw

然后在 Dashboard 的「网关令牌」输入框填入密码即可。

只有在不设 Token 的情况下，浏览器才会因为安全策略（Web Crypto API 需要 HTTPS）阻止连接。

你会看到：在 Dashboard 的对话界面输入消息后，没有任何回复，也没有报错。

排查步骤：

配置 Ollama：

Docker 环境中localhost指的是容器内部。如果 Ollama 在宿主机运行，请用host.docker.internal替代localhost：

dockerexecopenclaw openclaw configsetauth.openai.baseURL http://host.docker.internal:11434/v1

适用于：OneAPI、New API、各种中转站、国产模型 API 等。

baseURL末尾通常需要加/v1，但具体取决于你的 API 服务。

对话语言取决于你使用的 AI 模型，与本汉化项目无关。

  • Claude、GPT-4 等主流模型都支持中文对话
  • 你可以在系统提示中设置“请用中文回复”
  • 本项目只汉化界面（CLI + Dashboard），不影响对话内容

你会看到：Dashboard 左上角的 OpenClaw Logo 显示为空白或破损图标。

原因：旧版本使用了外部 CDN 图标链接，网络不通导致加载失败。新版已修复。

解决方案：

npm update -g @qingchencloud/openclaw-zh
# npm 用户 npm update -g @qingchencloud/openclaw-zh

Docker 用户

如果必须用 bind mount，修复权限

sudo chown -R 1000:1000 /你的目录路径

# 清理登录缓存后重试 dockerlogoutghcr.io docker pull ghcr.io//openclaw-zh:latest

可以使用 Docker 方式部署，参考Docker 部署指南。

核心步骤：

  1. 在 NAS 的 Docker 管理界面中拉取镜像ghcr.io//openclaw-zh:latest
  2. 创建容器，端口映射18789:18789，挂载数据卷
  3. 进入容器终端执行openclaw setup初始化
  4. 设置openclaw config set gateway.mode local
  5. 重启容器

✅排障完成！希望这份手册帮你顺利解决了 OpenClaw 部署路上的各种「拦路虎」。

从安装阶段的镜像问题，到启动时的环境配置，再到 Dashboard 连接和内网穿透——我们覆盖了全生命周期的常见故障点。如果按手册操作后问题仍未解决


共建完善：OpenClaw 汉化版持续迭代，如果你遇到手册未覆盖的新问题并找到了解决方案，欢迎提交 PR 补充到本排查手册，帮助更多后来者少走弯路！

祝你部署顺利，AI 助手稳定运行！



GPT plus 代充 只需 145

小讯
上一篇 2026-03-11 21:46
下一篇 2026-03-11 21:48

相关推荐

版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容，请联系我们，一经查实，本站将立刻删除。
如需转载请保留出处：https://51itzy.com/kjqy/213754.html