Fork me on GitHub

openclaw 个人部署踩坑记录

Posted on | In | Views:

在linux服务器上部署openclaw-zh汉化版

有以下前置条件：

  1. linux上已有docker，所以我将按照docker的方式部署openclaw
  2. 飞书上已创建个人应用，链接：飞书对接指南
  3. 使用美团的longcat作为模型，链接： OpenClaw 配置

部署openclaw的完整必要步骤

OpenClaw（原 Clawdbot/Moltbot）是一个强大的开源个人 AI Agent 平台，支持接入 Claude/ChatGPT 等大模型、多平台聊天机器人（如 Telegram/WhatsApp），汉化版（openclaw-zh）界面全中文，更适合国内用户。

我在服务器（华为云 ECS，amd64 架构）上部署时，踩了无数坑：

  • 镜像架构不匹配导致 exec format error
  • 配置未生效，gateway 闪退（Missing config / no token）
  • 远程访问 disconnected (1008) 安全上下文错误
  • 端口冲突、防火墙、安全组、bind 配置遗漏
  • volume 挂载路径写错导致数据丢失或不生效

最终成功方案如下（已亲测稳定运行）。全文命令均基于 Docker + bind mount 宿主机目录方式（/root/lee/openclaw/.openclaw），避免 named volume 迁移麻烦。

完整部署脚本（复制粘贴即可）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
#!/bin/bash
# OpenClaw-zh Docker 部署脚本（bind mount 方式，2026 年版）
# 作者：你的名字/博客链接
# 使用前：确保 Docker 已安装，服务器有公网 IP，端口 13004 已开放安全组/防火墙

set -e  # 遇到错误立即退出

# ==================== 0. 前置检查 ====================
echo "=== 0. 前置检查 ==="
if ! command -v docker &> /dev/null; then
    echo "错误：Docker 未安装！请先安装 Docker。"
    exit 1
fi

# 检查镜像是否已拉取（可选加速器已配置）
docker images | grep 1186258278/openclaw-zh || {
    echo "拉取镜像（强制 amd64 平台）..."
    docker pull --platform linux/amd64 1186258278/openclaw-zh:latest
}

# ==================== 1. 准备宿主机目录 ====================
HOST_DIR="/root/lee/openclaw/.openclaw"
echo "=== 1. 创建并授权宿主机目录 ==="
mkdir -p "$HOST_DIR"
chmod 700 "$HOST_DIR"          # 严格权限，防止泄露 token/配置
chown root:root "$HOST_DIR"    # 确保 root 拥有（容器内以 root 运行）

# ==================== 2. 清理旧容器（避免名字冲突） ====================
echo "=== 2. 清理旧 openclaw 容器 ==="
docker stop openclaw 2>/dev/null || true
docker rm openclaw 2>/dev/null || true

# ==================== 3. 首次初始化 setup（必须） ====================
echo "=== 3. 执行 openclaw setup（交互式，耐心等待） ==="
docker run -it --rm \
  -v "$HOST_DIR":/root/.openclaw \
  --platform linux/amd64 \
  1186258278/openclaw-zh:latest \
  openclaw setup

# ==================== 4. 核心配置（顺序重要！） ====================
echo "=== 4. 设置必要配置 ==="

# gateway.mode 必须为 local（否则闪退）
docker run --rm \
  -v "$HOST_DIR":/root/.openclaw \
  1186258278/openclaw-zh:latest \
  openclaw config set gateway.mode local

# 允许远程访问（默认 loopback 只本地）
docker run --rm \
  -v "$HOST_DIR":/root/.openclaw \
  1186258278/openclaw-zh:latest \
  openclaw config set gateway.bind lan

# 解决 HTTP disconnected (1008) 错误（允许不安全认证，token-only）
docker run --rm \
  -v "$HOST_DIR":/root/.openclaw \
  1186258278/openclaw-zh:latest \
  openclaw config set gateway.controlUi.allowInsecureAuth true

# 自动修复常见问题 + 生成 token（强烈推荐！）
echo "运行 doctor --fix 生成 token（输出中会显示 token，请复制保存）"
docker run -it --rm \
  -v "$HOST_DIR":/root/.openclaw \
  1186258278/openclaw-zh:latest \
  openclaw doctor --fix

# 查看 token（备用）
echo "查看当前 gateway token（用于访问 URL）:"
docker run --rm \
  -v "$HOST_DIR":/root/.openclaw \
  1186258278/openclaw-zh:latest \
  openclaw config get gateway.auth.token

# ==================== 5. 正式启动 ====================
echo "=== 5. 启动 OpenClaw gateway ==="
docker run -d \
  --name openclaw \
  --restart unless-stopped \
  --platform linux/amd64 \
  -p 13004:18789 \
  -v "$HOST_DIR":/root/.openclaw \
  1186258278/openclaw-zh:latest \
  openclaw gateway run

# ==================== 6. 验证 ====================
echo "=== 6. 验证运行状态 ==="
sleep 5  # 等待启动
docker ps | grep openclaw || { echo "容器未运行！请检查 docker logs openclaw"; exit 1; }

echo "查看日志（按 Ctrl+C 退出）："
docker logs -f openclaw

常见踩坑 & 注意事项（博客核心内容）

  1. 镜像架构必须匹配
    服务器 amd64，但 nightly/latest 版有时默认拉 arm64 → exec format error。
    解决：始终加 --platform linux/amd64。

  2. volume 挂载路径写错最致命
    错误示例：-v ~/.openclaw:... 或多挂载 → 配置不生效、数据丢失。
    正确：用绝对路径 /root/xxx/...:/root/.openclaw，且只挂载一个。

  3. gateway.mode 未设 local → 闪退
    日志：Missing config…
    必须先 setup，再 set local。

  4. token 配置缺失 → Gateway auth error
    默认 token 模式但无值 → 启动失败。
    用 doctor --fix 自动生成，或手动 config set gateway.auth.token "xxx"。

  5. 远程访问 disconnected (1008)
    浏览器安全上下文要求 HTTPS 或 localhost。
    解决：

    • gateway.controlUi.allowInsecureAuth true（token-only，适合内网/测试）
    • 公网强烈推荐 Tailscale Serve / Nginx + HTTPS 反代（更安全）
    • 访问时必须带 token：http://IP:13004/?token=你的token

  6. 端口/防火墙/安全组

    • 服务器本地：ss -tuln | grep 13004 看到监听
    • 云控制台安全组 + firewalld/ufw 必须放行 13004/tcp
    • 否则 curl/telnet 超时，浏览器 Connection refused。

  7. 其他高频坑

    • 首次 dashboard 需 pairing：日志显示 request id，用 openclaw pairing approve <id> 批准（或用带 token 的 URL 自动）。
    • 配置不生效？删目录重 init（备份先！）。
    • 弱服务器：pull/setup 阶段 CPU/IO 高，耐心等，别 Ctrl+C 中断。
    • 升级镜像：先 docker pull 新版，再重启容器（数据在宿主机目录，不丢）。

安全提醒

  • 定期备份 /root/lee/openclaw/.openclaw 目录。
-------------The End-------------