乐于分享
好东西不私藏
当前位置：夜雨聆风 > 技术教程 > 软件教程 > 在WSL2里跑OpenClaw: 我踩过的那些坑,和最后怎么爬出来的

在WSL2里跑OpenClaw: 我踩过的那些坑,和最后怎么爬出来的

当前时间： 2026-06-21 11:33:06 更新时间： 2026-06-21 分类：软件教程 评论(0)

在WSL2里跑OpenClaw: 我踩过的那些坑,和最后怎么爬出来的

不是什么”五分钟入门教程”。是一整晚没睡、把错误日志翻了三十遍之后总结出来的东西。

不是什么”五分钟入门教程”。是一整晚没睡、把错误日志翻了三十遍、对着一个报 No API key found 的终端发了二十分钟呆之后，总结出来的东西。如果你也在WSL2里折腾OpenClaw，希望你能比我少走几个弯路。

先说清楚我在干什么

OpenClaw是一个AI Agent框架，支持多channel（飞书、Discord、Telegram……）。核心是一个gateway进程，负责接收各平台的消息、路由、维持长连接。它不是那种一键安装完就能用的产品，需要自己配模型、配channel、配认证。

我想在WSL2（Windows Subsystem for Linux 2）里跑它，接入飞书，作为日常工作的助手。理论上几行命令的事。实际上，我花了整整两个晚上。

环境：Windows 11 + WSL2 (Ubuntu) · OpenClaw latest · 飞书(Lark) · MiniMax-M2.7

坑一：systemd跑不起来，整个大厦地基就没了

▎症状

执行 systemctl --user start openclaw-gateway.service 报错：

Failed to connect to bus: No such file or directory

执行 openclaw gateway probe 一直超时。

诊断：

ps -p 1 -o comm=

输出的是 init 或 /init，而不是 systemd。这说明systemd根本没起来。

为什么会这样

WSL2默认不启动systemd。在 /etc/wsl.conf 里加了 systemd=true，然后执行了 wsl --shutdown——还是不行。

原因是：在某些Windows版本里，wsl --shutdown 只会终止WSL进程，不会触发完整的init重初始化。

▎真正有用的办法

完整的Windows重启，不是关WSL，是关Windows：

shutdown /r /t 0

等Windows重启完，再查 ps -p 1 -o comm=，这次应该显示 systemd 了。

如果你懒得重启

OpenClaw的gateway不需要systemd也能跑，直接后台启动：

openclaw gateway &
sleep 8
openclaw gateway probe

输出 Reachable: yes · Connect: ok · RPC: ok 就表示跑起来了。

坑二：MiniMax的API地址，我一直填错了

▎症状

日志：No API key found for provider "minimax"，但用curl测试key，明明是通的。

根因：地址填错了。

api.minimax.io — 旧地址

api.minimax.chat — 常见错误

✓ api.minimaxi.com/anthropic/v1 — 正确地址

▎修复

sed -i ‘s|api\.minimax\.io|api.minimaxi.com|g’ ~/.openclaw/agents/main/agent/models.json

然后重启gateway。

坑三：API Key被”吞”了——文件里明明有，但gateway读不到

▎症状

日志：No API key found for provider "minimax"

cat auth-profiles.json → 显示 ***

真正诡异的地方

用 cat 读，显示 ***。

用 xxd 读，显示真实key的十六进制：736b 2d61 7069 2d6b 6970 6648 634d 6835 sk-api...

真实key存在文件里，但gateway读到的就是字面的 ***。OpenClaw工具层在保护敏感信息，但gateway并没有绕过这个masking层。

▎正确的做法

用工具直接写文件，不要用echo/cat。写入 ~/.openclaw/agents/main/agent/auth-profiles.json：

{“minimax”: {“apiKey”: “sk-api…Dxo8”}}

同样操作 ~/.openclaw/agents/main/auth-profiles.json。然后kill+重启gateway。

openclaw secrets reload

 看起来合理，但不够——必须完全kill掉gateway再重启：

kill -9 $(ps aux | grep ‘openclaw-gateway’ | grep -v grep | awk ‘{print $2}’)

坑四：飞书多实例——单gateway只能接一个channel

▎症状

同时跑两个飞书实例（公司号+个人号），配置好第二个，第一个就连不上了。

原因：单gateway只支持一个feishu channel。想跑多个飞书账号，必须跑多个独立的gateway进程。

▎解决方案

# 实例1（公司飞书）
OPENCLAW_CONFIG_PATH=/root/.openclaw-feishu1/openclaw.json \
openclaw gateway –port 18789 &

# 实例2（个人飞书）
OPENCLAW_CONFIG_PATH=/root/.openclaw-feishu2/openclaw.json \
openclaw gateway –port 18790 &

坑五：CLI设备无法给自己审批——Pairing死锁

▎症状

Error: pairing required — CLI在等待审批，但审批操作本身需要CLI，死锁了。

▎修复

手动编辑 ~/.openclaw/devices/paired.json，给CLI设备加完整的operator权限（role: operator, scopes包含全部6项）。清空 pending.json（设为 {}），重启gateway。

坑六：Control UI的Token——URL fragment不是query string

▎症状

打开 http://127.0.0.1:18789/ 看到 token_missing，或输入token后报 unauthorized: too many failed attempts。

原因：你打开的是Canvas测试页（/__openclaw__/canvas/），不是真正的Control UI（/#token=...）。token在URL fragment（#后面），不是query string（?后面）。

▎正确的做法

openclaw dashboard –no-open

复制输出中的完整URL（包括 #token= 整个部分）。

如果token被锁定：openclaw devices rotate operator 然后重新获取。

坑七：没有systemd，gateway崩了没人管

▎解决方案：crontab看门脚本

# 创建脚本
cat > /root/guardian-openclaw.sh << ‘EOF’
#!/bin/bash
GATEWAY_PID=$(pgrep -f “openclaw-gateway” 2>/dev/null | head -1)
if [ -z “$GATEWAY_PID” ]; then
  nohup openclaw gateway > /tmp/gateway-guardian-out.log 2>&1 &
fi
EOF
chmod +x /root/guardian-openclaw.sh

# 加入crontab，每分钟检查
(crontab -l 2/dev/null; echo “* * * * * /root/guardian-openclaw.sh”) | crontab –

坑八：Gateway Probe Connect ok但RPC timeout

openclaw gateway probe → Reachable: yes · Connect: ok 但 RPC: failed - timeout。

原因：gateway supervision没有正常工作，RPC层没有初始化。修复：kill后用后台方式重启。如果还是不行，重启Windows（见坑一）。

坑九：模型配置对，但Agent还是报”No API key found”

▎症状

API key填了，地址对了，日志没有401，但飞书发消息bot不回。日志：⚠️ Agent failed: No API key found for provider "minimax"

原因：Agent配置的model provider和auth-profiles.json里配的不匹配。比如agent配置了 deepseek/deepseek-reasoner，但你只配了MiniMax的key。

修复：openclaw models set minimax/MiniMax-M2.7，或在openclaw.json里改agent的model配置，然后重启gateway。

坑十：飞书Channel显示running但bot不回

openclaw channels status 显示 Feishu default: enabled, configured, running，但消息没有回复。

诊断步骤：

  1. 看gateway日志——如果有 Agent failed，问题在agent层（见坑九）
  2. 如果没有消息记录，但飞书显示”已送达”，检查appId/appSecret
  3. openclaw config get channels.feishu
     确认配置正确

①systemd? → ②gateway probe → ③No API key? → ④飞书不回?

附录一：完整debug命令清单

命令
用途
ps -p 1 -o comm=
检查systemd是否运行
ps aux | grep openclaw
检查gateway进程
ss -tlnp | grep 18789
检查端口占用
tail -50 /tmp/openclaw/openclaw-*.log
查看gateway日志
xxd | grep sk-api
 验证API key真实内容
openclaw channels status
检查channel状态
openclaw pairing list
检查pending pairing

附录二：最小可运行配置（从零开始）

第一步
 openclaw models set minimax/MiniMax-M2.7
第二步
直接写auth-profiles.json（工具写，不要用cat）
第三步
 openclaw config set channels.feishu.appId "cli_xxx"
第四步
 openclaw gateway &

 + openclaw gateway probe
第五步
 openclaw dashboard --no-open

 获取URL
第六步
 openclaw pairing approve feishu <id>

附录三：常见错误速查

错误信息
第一步处理
Failed to connect to bus
重启Windows，或直接后台跑gateway
No API key found
用xxd验证文件真实内容，重启gateway
RPC: failed – timeout
kill掉gateway，后台方式重启
pairing required
手动编辑paired.json加权限
token_missing
 openclaw dashboard --no-open
too many failed attempts
 openclaw devices rotate operator
Feishu running但bot不回
检查日志Agent failed错误
Unrecognized key “providers”
从openclaw.json里删除providers字段

写给后来者

WSL2 + OpenClaw 这套组合拳，官方文档写得不全。很多坑藏在错误日志深处，没有任何一处文档会明确告诉你：

  • “如果systemd起不来，先重启Windows，而不是反复执行 wsl --shutdown“
  • “cat 看到 *** 不代表文件里真的存的是 ***“
  • “Control UI的URL里 # 后面的token是故意设计成这样的”

这些信息散落在GitHub issue、Discord讨论和无数次深夜debug里。把这段经历整理出来，希望你不用再对着一个 *** 干瞪眼。

如果你觉得这篇文章有用，欢迎转发。
有问题欢迎留言，不保证秒回，但保证认真看。