# 飞书 + OpenClaw 配置

> 更新：2026-05-30 | 总指挥

## 整体架构

```
飞书客户端
  ├─ 私聊消息 → OpenClaw Gateway（DeepSeek Chat）
  │                 │
  │                 └─→ 我（总指挥）→ exec-bridge → 4引擎
  │
  ├─ 卡片消息 ← task-monitor (:3455) — 应用身份发送（唯一卡片源）
  │
  └─ 唤醒消息 ← callback-agent (:3463) — 用户身份发送
```

## OpenClaw Gateway

- **运行方式**：自动启动（非PM2管理）
- **模型**：DeepSeek Chat（默认）
- **频道**：飞书私信（DM）
- **配置文件**：`~/.openclaw/openclaw.json`
- **Cron任务**：`~/.openclaw/cron/jobs.json`

## 飞书应用凭证

### 应用信息
- **App ID**：`cli_a946d47647b81bc8`
- **App Secret**：环境变量 `FEISHU_APP_SECRET`
- **用途**：task-monitor 发送卡片（应用身份）

### 用户 OAuth
- **存储位置**：macOS Keychain
- **服务名**：`openclaw-feishu-uat`
- **账号格式**：`{app_id}:{user_open_id}`
- **用途**：callback-agent 以用户身份发唤醒消息

## 关键ID

| 标识 | 值 | 用途 |
|:-----|:---|:-----|
| 用户 open_id | `ou_eab14c8e7fef3117b2a137e654866c17` | 私聊目标用户 |
| DM 群 chat_id | `oc_08a5dd4915fa9f25dc519a497ac51f13` | 老大私聊群 |

## 卡片发送链路

```
任务开始/完成
  │
  ▼
exec-bridge (:3461) → pushLiveChunk → task-monitor (:3455)
                                          │
                                          ├─ notifyFromLiveChunk
                                          ├─ sendFeishuStartCard (indigo)
                                          ├─ sendFeishuCard (green, 完成卡)
                                          └─ updateFeishuCard (更新同一张卡片)
                                          │
                                          ▼
                                    feishu-card-sender.mjs
                                          │
                                          ├─ buildCard() — 完成卡片模板
                                          ├─ buildStartCard() — 开始卡片模板
                                          └─ 应用身份 token → 飞书 open API
```

### 卡片模板要点
- **手机优先**：紧凑排版，飞书 Markdown 限制（不支持 `#`/`##`/`###` 标题）
- **引擎色条**：卡片顶部彩色标识条区分引擎
- **字段**：引擎/耗时/taskId/结果摘要
- **限制**：飞书 Markdown 1500字上限，超长自动 `splitIntoChunks` + `(1/3)` 标签
- **注意**：加粗内不能有中文符号或表情

## 唤醒消息链路

```
任务完成
  │
  ▼
exec-bridge → callback → callback-agent (:3463)
                            │
                            ├─ 持久化结果（pending-summary.json）
                            ├─ feishuMessageNotify → 用户身份消息
                            └─ AgentFlow 检测 → 自动投递下一阶段
```

- callback-agent 使用**用户 token** 发消息（从 Keychain 读取）
- 消息格式：含引擎/耗时/任务ID/结果摘要
- 注意：callback-agent 不应自己管理 token，应通过 OpenClaw 平台工具

## API 地址

- **飞书 Open API**：`https://open.feishu.cn/open-apis/`
- **消息发送**：`POST /im/v1/messages`
- **卡片发送**：`POST /im/v1/messages`（`msg_type: interactive`）
- **用户信息**：`GET /contact/v3/users/{open_id}`

## 注意

- **飞书 API 不走代理**：`open.feishu.cn` 是国内服务，必须直连（2026-05-22修复：feishu-card-sender 去掉了 Decodo 代理）
- **卡片唯一源**：task-monitor (:3455) 是飞书卡片的唯一发送源，task-notifier (:3462) 已停用
- **用户 vs 应用身份**：卡片用应用身份发（格式丰富），唤醒消息用用户身份发（触发 OpenClaw 会话激活）
- **callback-agent 不重复实现 token 管理**：系统级能力由 OpenClaw 平台管理，自定义服务只负责信号处理