OpenClaw 安装配置 + 飞书接入指南

如果你有第三方 OpenAI 兼容 API（如自建代理），可以在中配置自定义提供商："model": {},

Hey Stephen

978人浏览 · 2026-03-19 00:13:05

Hey Stephen · 2026-03-19 00:13:05 发布

本文档记录了在 Linux（WSL2）环境下安装 OpenClaw 并接入飞书机器人的完整步骤。

一、前置条件

操作系统：Linux / macOS / Windows（WSL2 推荐）
Node.js：>= 22
飞书开发者账号：https://open.feishu.cn

二、安装 OpenClaw CLI

2.1 一键安装

curl -fsSL https://openclaw.ai/install.sh | bash

也可以用 npm 全局安装：npm install -g openclaw@latest

2.2 运行新手引导向导

openclaw onboard --install-daemon

向导会引导你配置：

模型/认证方式
Gateway 网关设置
聊天渠道（飞书/Telegram/Discord 等）
后台服务（systemd）

三、配置免费模型（Qwen Portal）

Qwen Portal 提供免费 OAuth 访问，每天 2,000 次请求，无需 API Key。

3.1 启用 Qwen Portal 插件

openclaw plugins enable qwen-portal-auth

3.2 OAuth 登录

openclaw models auth login --provider qwen-portal --set-default

运行后终端会显示一个授权链接，类似：

https://chat.qwen.ai/authorize?user_code=XXXX&client=qwen-code

操作步骤：

复制完整链接，在浏览器中打开（注意链接不要被终端换行截断）
如果未登录 Qwen，先登录你的通义千问账号
在页面上点击 授权/Approve
看到「认证成功」后，终端会自动完成配置

模型自动设置为 qwen-portal/coder-model

3.3 （可选）使用自定义 API Key

如果你有第三方 OpenAI 兼容 API（如自建代理），可以在 ~/.openclaw/openclaw.json 中配置自定义提供商：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "my-provider/qwen2.5-72b-instruct"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "my-provider": {
        "baseUrl": "https://your-api-proxy.com/v1",
        "apiKey": "sk-your-api-key",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen2.5-72b-instruct",
            "name": "Qwen2.5 72B Instruct",
            "contextWindow": 131072,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

四、配置飞书渠道

4.1 飞书开发者后台配置

4.1.1 添加机器人能力

左侧菜单 → 添加应用能力 → 添加 机器人

4.1.2 配置事件与回调

左侧菜单 → 事件与回调
订阅方式：选择 「使用长连接接收事件」（推荐）
添加事件：搜索并添加 im.message.receive_v1（接收消息 v2.0）

4.1.3 开通权限

左侧菜单 → 权限管理
开通以下权限：
- im:message — 获取与发送单聊、群聊消息
- im:message.receive — 读取用户发给机器人的单聊消息

4.1.4 获取凭证

左侧菜单 → 凭证与基础信息
记录 App ID 和 App Secret

4.1.5 发布应用

左侧菜单 → 版本管理与发布 → 创建版本并发布
确保页面显示 「当前修改均已发布」

4.2 OpenClaw 侧配置

在 openclaw onboard 时选择飞书渠道，向导会自动安装 @openclaw/feishu 插件。

也可以手动编辑 ~/.openclaw/openclaw.json：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxxxxxxxxxxxxxxx",
      "appSecret": "your-app-secret",
      "connectionMode": "websocket",
      "domain": "feishu",
      "groupPolicy": "open"
    }
  },
  "plugins": {
    "entries": {
      "feishu": {
        "enabled": true
      }
    }
  }
}

domain 说明：国内飞书填 "feishu"，海外 Lark 填 "lark"

五、启动 Gateway 网关

5.1 前台启动（调试用）

openclaw gateway --port 18789 --verbose

5.2 验证状态

# 查看整体状态
openclaw status

# 健康检查
openclaw health

5.3 访问 Dashboard

浏览器打开：http://127.0.0.1:18789/

可以直接在 Dashboard 的聊天界面与 AI 对话。

六、使用机器人

6.1 飞书客户端

打开飞书 App（桌面端或手机端）
在顶部搜索栏搜索你的机器人名称（如「玩虾大会」）
点击机器人，直接发消息聊天

6.2 Dashboard Web 聊天

浏览器打开 http://127.0.0.1:18789/
在聊天界面直接输入消息

七、关键文件位置

文件说明	路径
主配置文件	`~/.openclaw/openclaw.json`
认证凭证	`~/.openclaw/agents/main/agent/auth-profiles.json`
会话数据	`~/.openclaw/agents/main/sessions/`
工作区	`~/.openclaw/workspace/`
运行日志	`/tmp/openclaw/openclaw-*.log`
飞书插件	`~/.openclaw/extensions/feishu/`

八、常用命令速查

# 状态检查
openclaw status              # 查看整体状态
openclaw health              # 健康检查
openclaw status --all        # 完整调试报告

# Gateway 管理
openclaw gateway --port 18789 --verbose   # 前台启动
openclaw gateway status                   # 查看网关状态

# 模型管理
openclaw models list                      # 查看已配置模型
openclaw models list --all                # 查看所有可用模型
openclaw models set <provider/model>      # 切换默认模型

# 配置
openclaw configure                        # 交互式配置向导
openclaw configure --section model        # 仅配置模型
openclaw doctor --fix                     # 修复配置问题

# 日志
openclaw logs --follow                    # 实时查看日志