在 Windows(WSL2)中从 Clawbot 迁移到 OpenClaw:可复现完整指南

0 阅读9分钟

在 Windows(WSL2)中从 Clawbot 迁移到 OpenClaw:可复现完整指南

作者:数字卢语 环境:Windows 10 + WSL2 (Ubuntu)
日期:2026 年 3 月
版本:OpenClaw 2026.3.2


一句话介绍

这是一份基于真实踩坑复盘的迁移指南,帮你在 WSL2 下把 Clawbot 平滑迁移到 OpenClaw,并快速达到“可用且稳定”的状态。


📋 背景说明

如果你也遇到过 Health OffLine、WebSocket 断连、systemd 启动失败,这篇就是给你的实战迁移手册。

我之前在 WSL2 中安装了旧版 Clawbot,但遇到了以下问题:

  • Web 界面显示 Health OffLine,无法连接后端
  • WebSocket 连接失败 (disconnected 1006)
  • 配置文件格式过时(gateway.bind 使用旧格式)
  • 服务无法通过 systemd 正常启动

经过排查,我选择彻底卸载旧版本,再安装最新的 OpenClaw 2026.3.2。本文按“先清理、再安装、再排错”的顺序记录,步骤可直接复现。

你将拿到什么

  • 一套从旧版 Clawbot 到 OpenClaw 的完整迁移流程
  • WSL2 场景下最常见坑位(bind、token、代理、模型)的一次性排查方案
  • QQ 机器人、Brave Search、百炼模型的可落地配置模板

建议阅读路径

  • 想快速上线:重点看第 3、4、5、6、13 部分
  • 想配模型:重点看第 7、11、12 部分
  • 想接入渠道和搜索:重点看第 9、10 部分

🔧 第一部分:彻底卸载旧版 Clawbot

1.1 停止并删除系统服务

# 停止服务(如果正在运行)
sudo systemctl stop clawdbot-gateway.service

# 禁用开机自启
sudo systemctl disable clawdbot-gateway.service

# 删除 systemd 服务文件
sudo rm /etc/systemd/system/clawdbot-gateway.service 2>/dev/null

# 重载 systemd 配置
sudo systemctl daemon-reload

1.2 删除配置和数据文件

⚠️ 警告:这将删除所有聊天记录、配置和 Agent 记忆,无法恢复!

# 删除核心配置目录(包含 Token、数据库、聊天记录)
rm -rf ~/.clawdbot

# 删除工作空间目录(包含 Agent 代码、技能文件)
rm -rf ~/clawd

# 删除日志文件
rm -rf /var/log/clawdbot

1.3 删除程序本体

# 查找 clawdbot 安装位置
which clawdbot

# 根据输出删除(通常是以下之一)
sudo rm /usr/bin/clawdbot
# 或
sudo rm /usr/local/bin/clawdbot
# 或
rm ~/.local/bin/clawdbot

# 删除 npm/pnpm 全局包
sudo npm uninstall -g @clawdbot/cli 2>/dev/null
rm -rf ~/.local/share/pnpm/global 2>/dev/null

1.4 清理残留进程

# 强制杀掉所有相关进程
pkill -9 -f clawdbot
pkill -9 -f clawd

# 验证是否清理完成
ps aux | grep -E "clawd|openclaw" | grep -v grep
# 如果没有输出,说明清理完成

📥 第二部分:安装新版 OpenClaw

2.1 下载安装脚本

# 下载并运行官方安装脚本
curl -fsSL https://clawd.bot/install.sh | bash

2.2 配置环境变量

安装完成后,添加路径到环境变量:

# 添加到 .bashrc
echo 'export PATH="/root/clawd/network-design-app/bin:$PATH"' >> ~/.bashrc

# 立即生效
source ~/.bashrc

# 验证安装
openclaw --version
# 应输出:2026.3.2

⚙️ 第三部分:初始化配置(Onboarding)

3.1 运行引导程序

openclaw onboard

3.2 引导选项选择指南

步骤选项推荐选择说明
安全确认Continue?Yes确认知晓安全风险
引导模式Onboarding modeQuickStart快速配置,适合新手
配置处理Config handlingCreate new全新安装选这个
网关绑定Gateway bindlan⭐ WSL2 关键设置,不要选 loopback
网关认证Gateway authToken (default)使用 Token 认证
模型提供商Model providerSkip for now后续手动配置
默认模型Default model保持默认后续手动配置
选择渠道Select channelTelegram或其他你需要的
Telegram TokenBot Token稍后填写可先跳过或填占位符
配置技能Configure skillsNo跳过,后续按需配置
启用 HooksEnable hooksSkip for now跳过
服务运行时Gateway runtimeNode默认即可

3.3 引导完成后的关键修改

引导完成后,不要急着启动服务!先修改配置文件以适配 WSL2:

nano ~/.openclaw/openclaw.json

必须修改的字段

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",                    // ⭐ 必须是 "lan",不能用 "0.0.0.0"
    "auth": {
      "mode": "token",
      "token": "你的 Token"            // 记下这个 Token
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "bailian": {                    // 预留阿里云百炼配置
        "baseUrl": "",                // 后续填写
        "apiKey": "",                 // 后续填写
        "api": "openai-completions",
        "models": []
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": ""                 // 后续填写
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "",                 // 后续填写
      "groupPolicy": "open"           // 先设为 open 测试
    }
  }
}

🚀 第四部分:启动服务

4.1 手动启动(WSL2 推荐)

由于 WSL2 的 systemd 支持不完整,建议手动启动:

# 直接启动网关服务
openclaw gateway

4.2 验证启动成功

观察终端输出,应看到以下关键信息:

✓ Gateway listening on ws://0.0.0.0:18789
✓ heartbeat started
✓ health-monitor started
✓ agent model: [你的模型]

⚠️ 注意:这个终端窗口不能关闭,关闭后服务会停止。

4.3 后台运行(可选)

如果需要后台运行:

# 方法 1:使用 nohup
nohup openclaw gateway > ~/openclaw.log 2>&1 &

# 方法 2:使用 screen
screen -S openclaw
openclaw gateway
# 按 Ctrl+A 然后 D 离开屏幕会话

🌐 第五部分:访问 Web 界面

5.1 在 Windows 浏览器访问

打开 Windows 系统的 Chrome/Edge 浏览器,访问:

http://localhost:18789/?token=你的 Token

Token 在哪里找

  • 引导完成时终端会显示
  • 或在配置文件 ~/.openclaw/openclaw.json 中查找 gateway.auth.token

5.2 验证连接状态

成功连接后,Web 界面右上角应显示:

  • 🟢 健康状况 正常
  • 🟢 版本 dev(或具体版本号)

如果显示 Health OffLine,请检查:

  1. gateway.bind 是否为 "lan"
  2. 服务进程是否正在运行
  3. Token 是否正确

🔍 第六部分:常见问题排查

问题 1:Health OffLine / WebSocket 断开

症状:Web 界面能打开,但显示离线

解决方案

# 1. 检查配置文件
nano ~/.openclaw/openclaw.json
# 确保 "bind": "lan"

# 2. 重启服务
pkill -9 -f openclaw
openclaw gateway

# 3. 清除浏览器缓存
# 按 Ctrl+Shift+R 强制刷新,或使用无痕模式

问题 2:gateway token missing

症状:红色报错 unauthorized: gateway token missing

解决方案

  1. 确保访问链接包含 Token:http://localhost:18789/?token=xxx
  2. 或在 Web 界面设置中手动粘贴 Token

问题 3:API 401 错误

症状:聊天时返回 HTTP 401: Incorrect API key

解决方案

# 1. 先用 curl 测试 API Key 是否有效
curl -X POST https://coding.dashscope.aliyuncs.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的APIKey" \
  -d '{"model": "qwen3.5-plus", "messages": [{"role": "user", "content": "你好"}]}'

# 2. 如果 curl 成功但 OpenClaw 失败,检查配置文件 JSON 格式
python3 -m json.tool ~/.openclaw/openclaw.json > /dev/null

# 3. 确保配置文件只有一个最外层的 { }

问题 4:Telegram 连接失败

症状:日志显示 telegram ... failed: Network request failed

原因:WSL2 默认无法直接访问 Telegram(被防火墙阻挡)

解决方案

# 配置代理(假设 Windows 代理端口 7890)
export HTTPS_PROXY=http://172.28.0.1:7890

# 然后启动
openclaw gateway

问题 5:systemctl 服务无法启动

症状systemctl status openclaw-gateway.service 显示失败

解决方案:WSL2 的 systemd 支持不完整,建议改用手动启动:

# 不要使用 systemd,直接运行
openclaw gateway

🎯 第七部分:阿里云百炼 API 配置(完整排坑指南)

7.1 获取正确的 API 密钥

# 1. 登录阿里云百炼控制台 https://bailian.console.aliyun.com/
# 2. 点击右上角头像 → API-KEY → 创建新的 API-KEY
# 3. 立即复制并保存密钥(格式如:sk-7b0d5e4c3a2b1f9e8d7c6b5a4f3e2d1c)

⚠️ 重要:API Secret 只在创建时显示一次,务必保存好!

7.2 确定 Base URL(关键!)

根据你使用的模型类型,选择对应的 Base URL:

模型类型Base URL适用场景
标准模型https://dashscope.aliyuncs.com/compatible-mode/v1常规对话模型
Coding 模型https://coding.dashscope.aliyuncs.com/v1代码生成/理解专用
视觉模型https://dashscope.aliyuncs.com/compatible-mode/v1图片理解

7.3 验证 API 连通性(最关键一步)

一定要先用 curl 测试! 这是后续所有配置的基础:

# 测试 Coding 模型(我使用的是 coding 专用端点)
curl -X POST https://coding.dashscope.aliyuncs.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5-plus",
    "messages": [{"role": "user", "content": "你好"}]
  }'

预期成功响应(简化版):

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "你好!有什么我可以帮你的吗?"
    }
  }]
}

7.4 OpenClaw 配置文件修改

根据我的实操经验,代理级配置文件会覆盖全局配置,这是最容易踩的坑:

# 1. 先检查是否存在代理级配置(如果存在,需要删除)
cat ~/.openclaw/agents/main/agent/models.json

# 2. 如果文件存在,备份并删除(让代理使用全局配置)
mv ~/.openclaw/agents/main/agent/models.json ~/.openclaw/agents/main/agent/models.json.backup

7.5 修改全局配置文件

nano ~/.openclaw/openclaw.json

添加完整的百炼配置:

{
  "models": {
    "mode": "merge",
    "providers": {
      "bailian": {
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "apiKey": "sk-你的APIKey",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3.5-plus",
            "name": "qwen3.5-plus",
            "contextWindow": 1000000,
            "maxTokens": 65536
          },
          {
            "id": "qwen3-coder-plus",
            "name": "qwen3-coder-plus",
            "contextWindow": 1000000,
            "maxTokens": 65536
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "bailian/qwen3.5-plus"
      }
    }
  }
}

7.6 验证 OpenClaw 配置

# 1. 重启网关
systemctl --user restart openclaw-gateway.service
# 或手动重启
pkill -9 -f openclaw
openclaw gateway

# 2. 在新终端中查看模型状态
openclaw models status

# 3. 测试模型调用
openclaw agent --agent main --message "你好"

预期输出

你好!👋 我在线。有什么可以帮你的吗?

7.7 排错指南:API 401 错误的终极解决方案

错误现象可能原因解决方案
HTTP 401: Incorrect API keyAPI Key 错误或过期重新生成 API Key
curl 成功但 OpenClaw 失败代理级配置覆盖全局配置删除 ~/.openclaw/agents/main/agent/models.json
Unknown model模型 ID 错误确认模型名称,可用 openclaw models list 查看
Connection refused代理未启动检查网关运行状态

重点检查代理级配置

# 如果代理级配置文件存在,它会覆盖全局配置
ls -la ~/.openclaw/agents/main/agent/models.json

# 确保使用的是正确的 API Key
cat ~/.openclaw/agents/main/agent/models.json 2>/dev/null | grep apiKey

🌐 第八部分:WSL2 代理配置(方案三:端口转发)

8.1 问题背景

WSL2 默认使用 NAT 网络模式,无法直接访问 Windows 本机的代理服务(因为代理监听的是 127.0.0.1,而 WSL2 有自己的独立 IP)。

8.2 方案三:netsh 端口转发(已验证可行)

这是我在实操中成功的方法,不需要修改代理软件的监听地址:

# 在 Windows PowerShell(管理员)中执行

# 1. 添加端口转发规则
netsh interface portproxy add v4tov4 \
  listenport=20809 \
  listenaddress=0.0.0.0 \
  connectport=20809 \
  connectaddress=127.0.0.1

# 2. 查看转发规则
netsh interface portproxy show all

# 3. 添加防火墙规则(如果 Windows 防火墙阻挡)
New-NetFirewallRule -DisplayName "WSL2-Proxy" \
  -Direction Inbound \
  -InterfaceAlias "vEthernet (WSL)" \
  -Protocol TCP \
  -LocalPort 20809 \
  -Action Allow

8.3 在 WSL2 中配置代理

# 1. 获取 Windows 主机的 IP(WSL2 中固定的网关地址)
host_ip=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')
echo "Windows IP: $host_ip"

# 2. 临时设置代理(测试用)
export http_proxy="http://$host_ip:20809"
export https_proxy="http://$host_ip:20809"

# 3. 测试代理连通性
curl -I https://www.google.com

预期成功响应

HTTP/2 200
content-type: text/html; charset=ISO-8859-1
...

8.4 永久配置代理

将以下内容添加到 ~/.bashrc

# 在 ~/.bashrc 末尾添加
if [ -f /etc/resolv.conf ]; then
    host_ip=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')
    export http_proxy="http://$host_ip:20809"
    export https_proxy="http://$host_ip:20809"
    export all_proxy="http://$host_ip:20809"
    
    # 可选:为特定域名/IP 配置直连
    export no_proxy="localhost,127.0.0.1,::1,*.local"
fi

使配置生效:

source ~/.bashrc

8.5 验证代理自动生效

# 新开终端或 source 后测试
echo $http_proxy
# 应显示类似:http://172.29.144.1:20809

curl -I https://www.google.com
# 应返回 200

8.6 排错指南:代理连接失败

问题可能原因解决方案
Connection refused端口转发规则未生效在 PowerShell 中重新运行 netsh interface portproxy add...
Empty reply from server代理软件限制检查代理软件是否开启"允许局域网连接"
能访问 Google 但无法访问 ifconfig.me代理规则限制使用 curl ip.sbcurl icanhazip.com 替代
IP 变化导致代理失效WSL2 重启后 IP 变化使用动态获取 IP 的脚本(已在 .bashrc 中实现)

🤖 第九部分:QQ 机器人对接完整指南

9.1 安装 QQ 机器人插件

# 1. 克隆插件代码
git clone https://github.com/sliverp/qqbot.git
cd qqbot

# 2. 安装插件
openclaw plugins install .

# 3. 验证插件安装
openclaw plugins list | grep qqbot

9.2 在 QQ 开放平台创建机器人

9.2.1 注册与认证
  1. 访问 QQ 开放平台
  2. 使用邮箱注册账号(不能用 QQ 号直接登录
  3. 完成个人实名认证:姓名、身份证号、手机号、人脸识别
9.2.2 创建机器人
  1. 点击"创建机器人"
  2. 填写基本信息:
    • 机器人名称:自定义(如"我的助手")
    • 机器人头像:上传图片
    • 功能介绍:简要说明用途
  3. 提交审核(通常即时通过)
9.2.3 获取关键凭证

创建成功后,进入机器人管理页面 → 开发管理,找到并复制:

  • AppID:机器人 ID(如:102345678
  • AppSecret:机器人密钥(如:ABCDEFGHIGKLMNOPQRSTUVWXYZ

⚠️ 重要:AppSecret 只在生成时显示一次,务必保存好!如果忘记,只能重新生成。

9.3 配置 IP 白名单(最关键步骤!)

9.3.1 获取出口 IP
# 注意:不要通过代理获取 IP,否则会得到代理 IP
unset http_proxy https_proxy

# 获取真实服务器 IP
curl ifconfig.me
# 或
curl ip.sb

# 记录显示的 IP 地址,例如:123.456.789.0
9.3.2 添加白名单
  1. 在 QQ 开放平台进入机器人 开发管理 页面
  2. 找到 IP 白名单 设置
  3. 添加刚才获取的 IP 地址
  4. 保存配置

9.4 配置沙箱环境

QQ 机器人默认在沙箱环境中测试,需要添加测试成员:

  1. 进入 沙箱配置 页面
  2. 选择"在消息列表配置"(单独聊天场景)
  3. 点击"添加成员",输入你自己的 QQ 号
  4. 用手机 QQ 扫码确认添加

注意:截至 2026 年 3 月,QQ 开放平台的群聊配置功能暂时处于系统维护状态,目前仅支持单聊。

9.5 OpenClaw 配置 QQ 通道

# 1. 添加 QQ 通道(格式:AppID:AppSecret)
openclaw channels add --channel qqbot --token "你的AppID:你的AppSecret"

# 示例:
# openclaw channels add --channel qqbot --token "102345678:ABCDEFGHIGKLMNOPQRSTUVWXYZ"

9.6 验证配置

# 1. 重启网关
systemctl --user restart openclaw-gateway.service
# 或手动重启
pkill -9 -f openclaw
openclaw gateway

# 2. 查看 QQ 通道连接状态
journalctl --user -u openclaw-gateway.service | grep -i qq

9.7 测试机器人

  1. 打开手机 QQ,在消息列表中找到你添加的机器人
  2. 发送测试消息,比如"你好"
  3. 如果能收到智能回复,说明对接成功!

9.8 排错指南:"机器人去火星了"

这是最常见的错误,日志中会显示:

{"message":"接口访问源IP不在白名单","code":11298,"err_code":40023002}

解决方案

9.8.1 方案一:更新 IP 白名单
# 1. 获取当前出口 IP(取消代理)
unset http_proxy https_proxy
curl ifconfig.me

# 2. 登录 QQ 开放平台,将新 IP 添加到白名单
9.8.2 方案二:让 QQ 流量绕过代理

在代理软件中添加直连规则:

  • 域名:api.sgroup.qq.comapi.q.qq.com
  • 策略:直连(Direct)

验证配置:

# 应该显示真实服务器 IP
curl https://api.sgroup.qq.com -v 2>&1 | grep -i "connected to"
9.8.3 方案三:SSH 隧道固定出口 IP

如果你有固定公网 IP 的 VPS:

# 建立 SSH 隧道
ssh -D 1080 -f -C -q -N user@你的VPS_IP

# 配置 OpenClaw 使用 SOCKS 代理
export ALL_PROXY=socks5://127.0.0.1:1080

# 在 QQ 开放平台添加 VPS IP 到白名单

9.9 完整配置示例

{
  "channels": {
    "qqbot": {
      "enabled": true,
      "appId": "102345678",
      "appSecret": "ABCDEFGHIGKLMNOPQRSTUVWXYZ",
      "sandbox": true,
      "intents": ["guild_messages", "direct_message"]
    }
  }
}

🔍 第十部分:Brave Search 搜索功能配置

10.1 获取 Brave Search API Key

  1. 访问 Brave Search API 官网
  2. 注册/登录账号
  3. 进入控制台,创建新的 API Key
  4. 复制生成的密钥(格式如:BSA-JHCeW0EMa-_iVHSuxg563hT0KHm

10.2 配置 OpenClaw

# 编辑配置文件
nano ~/.openclaw/openclaw.json

添加以下配置:

{
  "tools": {
    "profile": "messaging",
    "search": {
      "enabled": true,
      "provider": "brave",
      "brave": {
        "apiKey": "你的Brave API Key",
        "endpoint": "https://api.search.brave.com/res/v1/web/search",
        "count": 5  // 每次返回结果数量
      }
    }
  },
  "agents": {
    "defaults": {
      "skills": {
        "allow": ["web_search"]  // 允许代理使用搜索技能
      }
    }
  }
}

10.3 验证搜索功能

# 重启网关
systemctl --user restart openclaw-gateway.service

# 测试搜索
openclaw agent --agent main --message "请搜索:今天天气怎么样"

10.4 排错指南

问题可能原因解决方案
搜索返回空结果API Key 无效或额度用完检查 API Key 有效性
搜索超时网络问题确保代理配置正确
代理无法调用搜索技能未开启检查 agents.defaults.skills.allow 配置

🎨 第十一部分:模型选择建议

根据我的套餐,有以下模型可选:

品牌模型能力推荐指数
千问qwen3.5-plus文本生成、视觉理解⭐⭐⭐⭐ 性价比首选
千问qwen3-max-2026-01-23文本生成、深度思考⭐⭐⭐ 高性能
千问qwen3-coder-next代码生成⭐⭐ 专用场景
千问qwen3-coder-plus代码生成⭐⭐ 专用场景
智谱glm-5文本生成、深度思考⭐⭐⭐⭐⭐ 智能体能力最强
智谱glm-4.7文本生成、深度思考⭐⭐⭐ 均衡
Kimikimi-k2.5文本生成、视觉理解⭐⭐⭐⭐ 多模态
MiniMaxMiniMax-M2.5文本生成⭐⭐⭐ 无周限额

推荐配置

# 设置默认模型
openclaw models set bailian/glm-5  # 最强推理
# 或
openclaw models set bailian/qwen3.5-plus  # 性价比

📝 第十二部分:配置文件模板(完整版)

{
  "meta": {
    "lastTouchedVersion": "2026.3.2"
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "你的Token"
    }
  },
  "models": {
    "providers": {
      "bailian": {
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "apiKey": "你的阿里云API Key",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3.5-plus",
            "name": "qwen3.5-plus",
            "contextWindow": 1000000,
            "maxTokens": 65536
          },
          {
            "id": "glm-5",
            "name": "glm-5",
            "contextWindow": 202752,
            "maxTokens": 16384
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "bailian/glm-5"
      },
      "skills": {
        "allow": ["web_search", "calculator", "datetime"]
      }
    }
  },
  "channels": {
    "qqbot": {
      "enabled": true,
      "appId": "你的AppID",
      "appSecret": "你的AppSecret"
    },
    "telegram": {
      "enabled": false
    }
  },
  "tools": {
    "search": {
      "enabled": true,
      "provider": "brave",
      "brave": {
        "apiKey": "你的Brave API Key"
      }
    }
  }
}

✅ 第十三部分:最终验证清单

  • OpenClaw 服务正常运行(openclaw gateway 无报错)
  • Web 界面能访问且显示 🟢 健康
  • 阿里云百炼模型能正常回复
  • QQ 机器人能收到并回复消息
  • 代理配置生效,能访问外网
  • Brave Search 能正常返回搜索结果
  • 配置文件格式正确,无多余配置项

📚 参考资料


最后更新:2026 年 3 月 4 日

本文基于我的实际操作经验编写,确保每一步都可复现。如果在迁移过程中遇到问题,建议按以下顺序排查:

  1. 检查配置文件 JSON 格式
  2. 确认代理级配置是否覆盖全局
  3. 查看网关日志定位具体错误
  4. 用 curl 直接测试 API 连通性

如果你希望我再出一版“最小步骤版”(10 分钟快速迁移),可以留言,我会整理成速查清单。


CTA:资料领取

如果你正在做同类迁移,关注公众号[数字卢语]后私信我关键词:openclaw部署,可领取:

  • 可直接复用的配置模板(含模型、通道、搜索)
  • OpenClaw 完整配置json文件