Windows 11 WSL + Ubuntu 22.04 安装 OpenClaw 完整血泪史（2026.2 版实测）

OpenClaw 是一个强大的本地 AI Agent 框架，支持多模型切换、Agent 执行、飞书集成等功能。在 Windows 11 的 WSL Ubuntu 22.04 环境下安装时，会遇到大量配置陷阱，包括 config invalid、模型权限拒绝、插件 duplicate id 等。本文提供完整可复现步骤、所有常见坑点及解决方案。

1. 环境准备

在 WSL Ubuntu 22.04 中执行：

# 启用 systemd（OpenClaw daemon/service 必须）
sudo tee /etc/wsl.conf > /dev/null <<EOF
[boot]
systemd=true
EOF

# Windows PowerShell（管理员）重启 WSL
wsl --shutdown

更新系统并安装 Node.js 22.x：

sudo apt update && sudo apt upgrade -y
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

2. 安装 OpenClaw

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard   # 交互向导，先配置一个稳定模型（如 Z.AI / GLM）

坑点：onboard 向导不包含 DeepSeek、阿里百炼等模型 → 选 Skip for now，后续手动添加。

3. 模型配置（失败率最高的部分）

推荐起点：Z.AI / GLM（最稳定）
在 onboard 向导中选择 Z.AI，输入 API key，即可使用 zai/glm-4.7 或 zai/glm-4.6v。streaming 稳定，dashboard 和飞书均正常响应。

阿里百炼（DashScope / Bailian）配置
常见失败原因及解决：

Coding Plan sk-sp- key 不兼容 OpenAI 协议
该 key 仅支持 Anthropic 格式 endpoint（/apps/anthropic），OpenClaw 使用 OpenAI 协议（/v1/chat/completions），会导致 invalid key 或 403。
解决：使用普通按量计费 sk- 开头 key（主账号生成）。
403 Model access denied
高级模型（如 qwen3.5-plus、kimi-k2.5）需手动申请权限。
解决：先测试 qwen-turbo（默认有权限），通过后再申请目标模型。
models.providers 结构错误
常见报错：expected array, received undefined、Config invalid。
正确配置（中国用户推荐）：

"models": {
  "mode": "merge",
  "providers": {
    "aliyun": {
      "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "apiKey": "sk-你的普通key",
      "api": "openai-completions",
      "models": [
        {
          "id": "qwen-turbo",
          "name": "Qwen Turbo",
          "contextWindow": 8192,
          "maxTokens": 8192
        },
        {
          "id": "qwen3.5-plus",
          "name": "Qwen3.5 Plus",
          "contextWindow": 1000000,
          "maxTokens": 65536
        }
      ]
    }
  }
}

agents.defaults.models 必须包含 allowlist
未列出的模型无法使用。

"agents": {
  "defaults": {
    "model": {
      "primary": "zai/glm-4.7"   // 或 aliyun/qwen-turbo 测试
    },
    "models": {
      "zai/glm-4.7": { "alias": "GLM" },
      "aliyun/qwen-turbo": {},
      "aliyun/qwen3.5-plus": {}
    }
  }
}

保存后执行：

openclaw doctor --fix
openclaw gateway restart
openclaw models status   # 确认 active

4. 飞书集成（含 Bot 创建全流程）

步骤1：创建飞书自建应用 & Bot（飞书开放平台）

打开 https://open.feishu.cn/app（或国际版 https://open.larksuite.com/app）
点击“创建企业自建应用”，填写名称（如 “OpenClaw Bot”）、描述，创建成功。
凭证与基础信息：
- 复制 App ID（cli_ 开头）
- 复制 App Secret
应用功能 → 机器人：
- 添加机器人能力 → 启用
- 设置机器人名称、头像、简介（可选）
权限管理：
- 添加 im:message 相关权限（如 im:message:receive_as_bot、im:message.group_at_msg）
版本管理与发布：
- 创建版本（1.0）
- 提交审核（企业自建通常秒过）
- 发布成功后 Bot 才可见

步骤2：安装插件

openclaw plugins install @openclaw/feishu

常见警告：plugins.entries.feishu: duplicate plugin id detected
→ 官方插件源码重复定义 id: “feishu”，无实际影响，功能正常。忽略或升级最新版。

步骤3：添加 Channel

openclaw channels add   # 无参数，进入向导

向导输入：

选择 Feishu（或 Lark）
App ID / App Secret
Domain：feishu（国内）或 lark（国际）
Connection Mode：websocket（推荐，无需公网）

步骤4：飞书开放平台配置事件订阅

应用详情页 → 事件与回调：

订阅方式：使用长连接接收事件（WebSocket）
添加事件：im.message.receive_v1（至少）
保存（gateway 必须已运行，否则验证失败）

步骤5：测试

飞书搜索 Bot 应用名，加好友或拉群
私聊发 “hi” → 若 dmPolicy 为 pairing，回复 code 后执行：
```
openclaw pairing approve feishu <CODE>
```
群聊默认需 @Bot 触发（可后期 config 改 groupPolicy: “open”）

常见问题：

搜不到 Bot → 应用未发布或可见范围未设为“所有成员”
websocket 连不上 → 检查 openclaw logs --follow 是否有 “feishu websocket connected”

5. 常用诊断命令

openclaw doctor --fix
openclaw models status
openclaw models list
openclaw gateway restart
openclaw logs --follow --level debug
openclaw tui chat   # 终端测试

6. 安全配置建议

"compaction": {
  "mode": "safeguard"
},
"agents": {
  "defaults": {
    "model": { "primary": "zai/glm-4.7" }
  }
}

优先官方/自写 skill，避免 ClawHub 第三方
最小权限：deny exec、shell、rm 等高危 tool
gateway 绑定 127.0.0.1

总结

最稳定组合：

默认模型：zai/glm-4.7
飞书：websocket 长连接
阿里百炼：先 qwen-turbo 验证权限，再申请高级模型

自定义 provider 必须完整 models: [] 数组，且模型需阿里控制台授权。
当前版本下，阿里 Coding Plan key 无法直接使用，建议普通 sk- key 或 OpenRouter 路由。

配置过程中优先用 openclaw doctor --fix 和 openclaw logs --follow 诊断。

X Facebook LinkedIn Bluesky

EUGENE