feishu-proactive-messenger（飞书主动使者）

Feishu Proactive Messenger | 飞书主动消息发送器

飞书渠道只支持被动回复——用户先发消息，agent 才能回复。当 agent 需要主动发起对话（如 Agent A 派任务给 Agent B，Agent B 需要在自己的飞书窗口回复用户），飞书渠道没有这个能力。本 skill 通过直接调用飞书 OpenAPI 发送文本消息，补齐主动投递能力。

The Feishu channel only supports passive replies — the user must send a message first before the agent can respond. When an agent needs to proactively initiate a conversation (e.g. Agent A dispatches a task to Agent B, and Agent B needs to reply in its own Feishu chat window), the channel lacks this capability. This skill fills that gap by calling Feishu OpenAPI to send text messages directly.

快速开始 | Quick Start

python3 scripts/feishu_proactive_messenger.py --agent <agent_id> --text "Mission accomplished"

--agent 指定当前 agent 的 id（如 coder、data、life），脚本会自动读取对应的飞书凭证和 defaultTo 目标用户。若省略 --agent，则通过 cwd 自动匹配。

--agent specifies the current agent's id (e.g. coder, data, life). The script reads the corresponding Feishu credentials and defaultTo target automatically. If --agent is omitted, the script resolves the agent by matching cwd.

使用方法 | Usage

python3 scripts/feishu_proactive_messenger.py \
  --agent <agent_id> \
  --text "要发送的消息内容" \
  --receive-id <chat_id|open_id> \
  --receive-id-type <chat_id|open_id|user_id>

参数说明 | Arguments

• --agent（推荐）：agent id（如 coder、data、main）。用于确定使用哪个飞书应用的凭证。若省略，通过 cwd 自动匹配（在被派发任务场景下可能不准确，建议显式指定）。
• --text（必填）：要发送的消息文本。
• --receive-id（可选）：目标 chat_id 或 open_id。若省略，依次从环境变量 OPENCLAW_CHAT_ID / OPENCLAW_RECEIVE_ID / FEISHU_CHAT_ID 或 account 的 defaultTo 配置中读取。
• --receive-id-type（可选）：若省略，根据前缀自动识别：

- oc_ → chat_id - ou_ → open_id - on_ → user_id

• --agent (recommended): Agent id (e.g. coder, data, main). Determines which Feishu app credentials to use. If omitted, resolves by matching cwd (may be inaccurate in dispatched-task scenarios; explicit is recommended).
• --text (required): The message text to send.
• --receive-id (optional): Target chat_id or open_id. If omitted, reads from env OPENCLAW_CHAT_ID / OPENCLAW_RECEIVE_ID / FEISHU_CHAT_ID, or from the account's defaultTo config.
• --receive-id-type (optional): If omitted, auto-detect by prefix:

- oc_ → chat_id - ou_ → open_id - on_ → user_id

工作原理 | How It Works

1. 通过 --agent 参数或 cwd 匹配确定当前 agent id。
2. 根据 agent id 从 ~/.openclaw/openclaw.json 读取对应 account 的 appId/appSecret。
3. 从同一 account 的 defaultTo 读取默认目标用户（如未通过参数指定）。
4. 获取 tenant access token。
5. 通过飞书 bot/v3/info API 获取 bot 显示名称。
6. 调用飞书 发送消息 API（im/v1/messages）发送文本消息。
7. 输出简洁结果：✅ [Bot名称] 消息已发送。
8. Determine agent id via --agent parameter or by matching cwd.
9. Read appId/appSecret from ~/.openclaw/openclaw.json based on the agent id.
10. Read the default target user from the same account's defaultTo (if not specified via args).
11. Obtain a tenant access token.
12. Retrieve the bot's display name via Feishu bot/v3/info API.
13. Call Feishu Send Message API (im/v1/messages) to deliver the text message.
14. Output clean result: ✅ [BotName] 消息已发送.

前置配置 | Prerequisites

每个飞书 account 需要配置 defaultTo，指向目标用户的 open_id：

Each Feishu account needs a defaultTo pointing to the target user's open_id:

openclaw config set channels.feishu.accounts.<account>.defaultTo "user:ou_xxx"

注意：飞书的 open_id 是按应用隔离的，同一个用户在不同 bot 下有不同的 open_id。

Note: Feishu open_id is app-scoped — the same user has different open_ids under different bots.

错误处理 | Error Handling

• 缺少凭证 → 确保 channels.feishu.accounts 存在于 ~/.openclaw/openclaw.json，且 bindings 映射 agentId → accountId。
• 机器人不在聊天中（230002） → 用户需要先跟该 bot 发起过对话。
• 缺少 receive_id → 传入 --receive-id，设置 OPENCLAW_CHAT_ID， 或配置 defaultTo。
• HTTP 错误 → 查看飞书错误返回中的 log_id 进行排查。
• Missing credentials → Ensure channels.feishu.accounts exists in ~/.openclaw/openclaw.json and bindings map agentId → accountId.
• Bot not in chat (code 230002) → The user must have initiated a chat with the bot at least once.
• Missing receive_id → Pass --receive-id, set OPENCLAW_CHAT_ID, or configure defaultTo.
• HTTP errors → Check the returned log_id in Feishu error payload.

安全说明 | Security

本技能从 ~/.openclaw/openclaw.json 读取飞书凭证：

• channels.feishu.accounts.*.appId
• channels.feishu.accounts.*.appSecret

凭证仅用于获取 tenant access token 并发送消息。技能不会存储或向其他地方传输凭证。

This skill reads Feishu credentials from ~/.openclaw/openclaw.json:

• channels.feishu.accounts.*.appId
• channels.feishu.accounts.*.appSecret

These values are used only to obtain a tenant access token and send the message. The skill does not store or transmit credentials anywhere else.

备注 | Notes

• 本技能面向 所有 agent 设计，通过 --agent 参数或工作区匹配选择正确的飞书应用凭证。
• 配合 defaultTo 使用时，agent 无需知道任何 ID 即可主动发消息。
• 与 feishu-file-sender 互补：一个发文件，一个发文本。
• Designed for all agents; uses --agent parameter or workspace matching to choose credentials.
• When used with defaultTo, agents can send messages without knowing any IDs.
• Complements feishu-file-sender: one sends files, the other sends text.

随附脚本 | Bundled Script

• scripts/feishu_proactive_messenger.py

更新日志 | Changelog

1.0.1

• 新增 --agent 参数，显式指定 agent 身份（解决被派发任务时 cwd 匹配不准确的问题）
• 新增通过飞书 bot/v3/info API 获取 bot 显示名称
• 输出简化为 ✅ [Bot名称] 消息已发送，不再暴露 open_id 等敏感信息
• resolve_agent_id 支持 agents.defaults.workspace 作为 fallback

1.0.0

• 初始版本