> 记录时间: 2026-02-25
> OpenClaw 版本: 2026.2.24
> 飞书插件: @m1heng-clawd/feishu v0.1.11（社区版，来源: https://github.com/m1heng/clawdbot-feishu）
> 系统环境: Linux (Amazon Linux 2023), Node.js v24.11.1, npm 11.6.2
---
## 1. 环境检查
```bash
# 确认 Node.js >= 22
node --version # v24.11.1 ✓
# 确认 npm 可用
npm --version # 11.6.2 ✓
```
OpenClaw 要求 Node.js 版本 >= 22。
---
## 2. 解决 npm 全局安装权限问题
由于 `/usr/local/nodejs/lib/node_modules/` 目录无写权限，需要将 npm 全局安装目录改为用户目录：
```bash
# 创建用户级全局包目录
mkdir -p ~/.npm-global
# 设置 npm 全局安装前缀
npm config set prefix '~/.npm-global'
# 将新路径加入 PATH（写入 .bashrc 使之持久化）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
# 当前 session 立即生效
export PATH=~/.npm-global/bin:$PATH
```
---
## 3. 安装 OpenClaw
```bash
npm install -g openclaw@latest
```
安装完成后验证：
```bash
openclaw --version
# 输出: 2026.2.24
```
安装位置: `~/.npm-global/lib/node_modules/openclaw/`
---
## 4. 安装飞书 (Feishu) 插件
> 参考文档: https://github.com/m1heng/clawdbot-feishu
>
> 选择社区版而非内置版的原因：
> - 社区版功能更完善，支持图片/文件处理、卡片渲染、文档/知识库/云盘/多维表格工具、任务管理
> - 支持动态 Agent 隔离（每个用户独立工作空间）
> - 社区活跃维护，更新更快
### 4.1 禁用内置飞书插件
OpenClaw 内置了一个飞书插件 `@openclaw/feishu`，但我们使用社区维护的版本。先禁用内置版：
```bash
openclaw plugins disable feishu
```
### 4.2 安装社区版飞书插件
来源仓库: https://github.com/m1heng/clawdbot-feishu
npm 包名: `@m1heng-clawd/feishu`
```bash
openclaw plugins install @m1heng-clawd/feishu
```
如果安装失败（Windows 上可能出现 `spawn npm ENOENT`），手动下载安装：
```bash
curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.11.tgz
openclaw plugins install ./feishu-0.1.11.tgz
```
升级插件：
```bash
openclaw plugins update feishu
```
### 4.3 验证插件状态
```bash
openclaw plugins list
```
确认社区版 `Feishu v0.1.11` 状态为 `loaded`，内置版 `@openclaw/feishu` 为 `disabled`。
安装位置: `~/.openclaw/extensions/feishu/`
### 4.4 社区版插件提供的工具
安装后自动注册以下工具（可通过 `channels.feishu.tools` 配置开关）：
| 工具类别 | 说明 | 默认 |
|----------|------|------|
| `doc` | 文档操作（创建/编辑飞书文档） | 开启 |
| `wiki` | 知识库操作（依赖 doc） | 开启 |
| `drive` | 云盘操作（文件上传/下载/管理） | 开启 |
| `perm` | 权限管理（敏感操作） | 关闭 |
| `scopes` | 应用权限诊断 | 开启 |
| `task` | 飞书任务（创建/更新/删除/查询） | 开启 |
如需使用文档/知识库/云盘等工具，还需额外开通飞书权限：
- `docx:document:readonly` — 文档只读
- `drive:drive:readonly` — 云盘只读
- `wiki:wiki:readonly` — 知识库只读
- `bitable:app:readonly` — 多维表格只读
- `task:task:read` — 任务只读
---
## 5. Gateway 模式配置
首次启动 gateway 会报错：`set gateway.mode=local`。需要在配置中添加：
```json
{
"gateway": {
"mode": "local"
}
}
```
这在运行 `openclaw onboard` 向导时会自动配置，或手动编辑 `~/.openclaw/openclaw.json`。
---
## 6. AI 模型配置（Bedrock）
> 参考文档: https://docs.openclaw.ai/providers/bedrock
本环境使用 AWS Bedrock 上的 Claude，通过 EC2 IAM 角色认证。
### 6.1 在配置文件中注册 Bedrock Provider
在 `~/.openclaw/openclaw.json` 中添加以下配置：
```json
{
"models": {
"providers": {
"amazon-bedrock": {
"baseUrl": "https://bedrock-runtime.us-east-1.amazonaws.com",
"api": "bedrock-converse-stream",
"auth": "aws-sdk",
"models": [
{
"id": "us.anthropic.claude-sonnet-4-6",
"name": "Claude Sonnet 4.6 (Bedrock)",
"contextWindow": 200000,
"maxTokens": 8192
}
]
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "amazon-bedrock/us.anthropic.claude-sonnet-4-6"
}
}
}
}
```
关键说明：
- `auth: "aws-sdk"` — 使用 AWS SDK 凭证链，自动从 EC2 IAM 角色获取凭证
- `api: "bedrock-converse-stream"` — 使用 Bedrock Converse 流式 API
- 模型 ID 必须使用**推理配置文件 ID**（如 `us.anthropic.claude-sonnet-4-6`），不能用基础模型 ID（如 `anthropic.claude-sonnet-4-6`），否则会报 `Invocation with on-demand throughput isn't supported`
### 6.2 配置环境变量传递
在配置文件中添加 `env` 段，确保 gateway 进程能获取 AWS 区域和 IAM 凭证：
```json
{
"env": {
"shellEnv": {
"enabled": true
},
"vars": {
"AWS_REGION": "us-east-1"
}
}
}
```
- `shellEnv.enabled: true` — 从 shell 环境导入凭证（IAM 角色通过 instance metadata 自动获取）
- `vars.AWS_REGION` — 指定 Bedrock 所在区域
### 6.3 IAM 角色所需权限
EC2 实例的 IAM 角色需要以下权限：
- `bedrock:InvokeModel`
- `bedrock:InvokeModelWithResponseStream`
- `bedrock:ListFoundationModels`
### 6.4 验证模型连通性
```bash
openclaw agent --message "Hello, reply with just OK" --agent main
# 如果输出 OK，说明 LLM 连通正常
```
---
## 7. 飞书频道配置
### 7.1 配置文件位置
OpenClaw 配置文件路径: `~/.openclaw/openclaw.json`
### 7.2 飞书配置模板
```json
{
"channels": {
"feishu": {
"enabled": true,
"appId": "<YOUR_FEISHU_APP_ID>",
"appSecret": "<YOUR_FEISHU_APP_SECRET>",
"domain": "feishu",
"connectionMode": "websocket",
"dmPolicy": "pairing",
"groupPolicy": "allowlist",
"requireMention": true
}
}
}
```
### 7.3 配置字段说明
| 字段 | 说明 | 默认值 |
|------|------|--------|
| `appId` | 飞书应用的 App ID (`cli_xxxxx` 格式) | 必填 |
| `appSecret` | 飞书应用的 App Secret | 必填 |
| `domain` | `"feishu"` (中国版) 或 `"lark"` (国际版) | `"feishu"` |
| `connectionMode` | `"websocket"` (推荐，无需公网IP) 或 `"webhook"` | `"websocket"` |
| `dmPolicy` | 私聊策略: `"open"` / `"pairing"` / `"allowlist"` | `"pairing"` |
| `groupPolicy` | 群聊策略: `"open"` / `"allowlist"` / `"disabled"` | `"allowlist"` |
| `requireMention` | 群聊中是否需要 @机器人 才响应 | `true` |
| `renderMode` | 消息渲染: `"auto"` / `"raw"` / `"card"` | `"auto"` |
| `encryptKey` | (可选) 事件加密密钥 | - |
| `verificationToken` | (可选, webhook 模式必填) 验证 Token | - |
### 7.4 环境变量方式（替代配置文件中的明文凭证）
```bash
export FEISHU_APP_ID="cli_xxxxxxxxxxxxxxxx"
export FEISHU_APP_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```
---
## 8. 飞书开放平台应用配置（需手动完成）
### 8.1 创建应用
1. 访问 [飞书开放平台](https://open.feishu.cn)
2. 登录后，进入「开发者后台」
3. 点击「创建自建应用」
4. 在「凭证与基础信息」页面获取 **App ID** 和 **App Secret**
### 8.2 开启权限（重要！）
在「权限管理」中开启以下权限：
| 权限 | 说明 |
|------|------|
| `im:message` | 发送和接收消息 |
| `im:message.p2p_msg:readonly` | 读取私聊消息 |
| `im:message.group_at_msg:readonly` | 接收群聊 @消息 |
| `im:message:send_as_bot` | 以机器人身份发送消息 |
| `im:resource` | 图片/文件处理 |
| `im:chat` | 获取群信息 |
| `contact:user.base:readonly` | 用户基本信息只读 |
| `contact:contact.base:readonly` | 通讯录基本信息只读（实测必须开通，否则报 99991672 错误） |
### 8.3 配置事件订阅（关键步骤！）
进入「事件与回调」→「事件订阅」：
1. **选择订阅方式**：选择「长连接」（对应 websocket 模式，推荐，无需公网 URL）
2. **添加必要事件**：
- `im.message.receive_v1` — **必须！接收消息的核心事件**
- `im.message.message_read_v1` — (可选) 已读回执
- `im.chat.member.bot.added_v1` — (可选) 机器人被加入群聊
- `im.chat.member.bot.deleted_v1` — (可选) 机器人被移出群聊
### 8.4 发布应用
发布应用（或先添加到测试企业/群组进行调试）。
### 8.5 资源访问配置
- **云文档**: 机器人没有独立「我的空间」。需要右键文件夹 → 分享 → 搜索机器人名称，授予查看/编辑权限
- **知识库**: 在知识库「设置」→「成员」→「添加成员」中添加机器人
- **多维表格**: 直接将表格分享给机器人
---
## 9. 启动 OpenClaw Gateway
```bash
# 设置环境变量
export PATH=~/.npm-global/bin:$PATH
export AWS_REGION=us-east-1
unset AWS_PROFILE # 避免使用可能过期的临时凭证
# 启动 Gateway
openclaw gateway --port 18789 --verbose
# 或者安装为系统守护进程（推荐生产环境使用）
openclaw onboard --install-daemon
```
---
## 10. 验证连接
```bash
# 检查频道状态
openclaw channels status
# 运行健康检查
openclaw doctor
```
---
## 11. 其他常用命令
```bash
# 查看所有已配置的频道
openclaw channels list
# 查看 Gateway 日志
openclaw logs
# 发送测试消息
openclaw agent --message "Hello from OpenClaw" --thinking high
# 打开终端 UI
openclaw tui
# 打开 Web 控制面板
openclaw dashboard
# 更新 OpenClaw
openclaw update
# 更新飞书插件
openclaw plugins update feishu
```
---
## 12. 目录结构说明
```
~/.npm-global/ # npm 全局安装目录
└── lib/node_modules/openclaw/ # OpenClaw 安装位置
└── extensions/feishu/ # 内置飞书插件（已禁用）
~/.openclaw/ # OpenClaw 状态 & 配置目录
├── openclaw.json # 主配置文件
├── extensions/feishu/ # 社区版飞书插件（@m1heng-clawd/feishu）
├── agents/main/ # 主 Agent
│ ├── agent/auth-profiles.json # 认证配置
│ └── sessions/ # 会话存储
├── credentials/ # OAuth 凭证
└── logs/ # 日志目录
```
---
## 13. 故障排查
### 飞书发消息无响应
排查顺序：
1. **检查事件订阅** — 飞书开放平台是否配置了 `im.message.receive_v1`，且选择了「长连接」模式
2. **检查应用发布** — 应用是否已发布或设为可用状态
3. **检查权限** — 所有必需权限是否已开启且审批通过（特别注意 `contact:contact.base:readonly`）
4. **检查 AI 模型** — `openclaw agent --message "test" --agent main` 测试模型是否连通
5. **检查 DM 策略** — 如果 `dmPolicy: "pairing"`，需要先配对；日志中出现 `received message from ou_xxx` 但没有回复，通常是策略拦截
6. **查看日志** — `journalctl --user -u openclaw -f` 或 gateway verbose 输出
### DM 策略说明
| 策略 | 说明 |
|------|------|
| `"open"` | 任何人可私聊，需设置 `"allowFrom": ["*"]` |
| `"pairing"` | 需先配对：`openclaw pairing list` 查看请求，`openclaw pairing approve <id>` 批准 |
| `"allowlist"` | 仅允许指定用户，`"allowFrom": ["ou_xxx"]`（open_id 可从日志中获取） |
### Gateway token_mismatch
控制面板 (Control UI) 连接时报 token 不匹配，使用 `openclaw dashboard` 命令打开面板会自动传入正确 token。
### npm 全局安装权限报错 (EACCES)
参照第 2 节，将 npm 全局目录改到用户目录 `~/.npm-global`。
