openclaw 个人部署踩坑记录

在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 迁移麻烦。

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

#!/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 目录。

使用 LiteLLM 代理

总结：LiteLLM 把你的多个 API Key 伪装成一个统一的 OpenAI 接口，OpenClaw 只认这一个代理，就能自动轮询多个 Key，避免限流，配置简单、运行稳定。

LiteLLM 不需要放在 Docker 里，推荐直接在服务器宿主机（即 Linux 系统本身）上安装和运行。必须升级 Python 到 3.10 或 3.11（推荐 3.11，最稳定）。
安装好LiteLLM（1.81.11）后，建议在venv上运行。

mkdir -p ~/litellm && cd ~/litellm
python -m venv venv
source venv/bin/activate

1. 创建 LiteLLM 配置文件

vim litellm_config.yaml


litellm_settings:
  drop_params: true  # 过滤不兼容参数
model_list:
  - model_name: longcat-multi  # OpenClaw 中看到的模型别名，自定义
    litellm_params:
      model: openai/LongCat-Flash-Chat  # LongCat 的实际模型 ID（常见的是这个，或 LongCat-Pro-Chat 等，确认你的）
      api_base: https://api.longcat.chat/openai
      api_key: sk-your_first_longcat_key_here  # 第一个 Key
  - model_name: longcat-multi
    litellm_params:
      model: openai/LongCat-Flash-Chat
      api_base: https://api.longcat.chat/openai
      api_key: sk-your_second_longcat_key_here  # 第二个 Key
  - model_name: longcat-multi
    litellm_params:
      model: openai/LongCat-Flash-Chat
      api_base: https://api.longcat.chat/openai
      api_key: sk-your_third_longcat_key_here  # 可以继续加更多

# 可选：负载均衡策略（默认 random 随机轮询，很合适避限流）
router_settings:
  routing_strategy: simple-shuffle  # 选项：simple-shuffle（随机）、least-busy（最空闲）、usage-based-routing（根据用量智能）

说明：OpenClaw 发送的 store 参数不被 LongCat API 支持，导致 UnsupportedParamsError，所以drop_params一定要填，用于过滤参数

2. 运行 LiteLLM 代理（推荐用 screen，稳）

screen -S litellm  # 新开一个 screen 会话
litellm --config litellm_config.yaml --port 4000 # 运行

相关命令

按 Ctrl+A 然后 D 脱离 screen（代理继续后台运行）。
screen -r litellm 进入
Ctrl+C 停止