{"skill":{"slug":"feishu-proactive-messenger","displayName":"Feishu Proactive Messenger","summary":"飞书主动消息发送器 — 飞书渠道只支持被动回复，agent 无法主动发起对话。本 skill 调用飞书 OpenAPI 发送文本消息，补齐主动投递能力。| Feishu Proactive Messenger — Send text messages proactively via Feishu OpenAPI,...","description":"---\nname: feishu-proactive-messenger\ndescription: 飞书主动消息发送器 — 飞书渠道只支持被动回复，agent 无法主动发起对话。本 skill 调用飞书 OpenAPI 发送文本消息，补齐主动投递能力。| Feishu Proactive Messenger — Send text messages proactively via Feishu OpenAPI, filling the channel's missing outbound messaging.\nlicense: MIT\ncompatibility: openclaw\nmetadata:\n  version: \"1.0.1\"\n  tags: [feishu, message, proactive, outbound, openapi, messaging]\n  author: wen-ai\n  openclaw:\n    emoji: \"📨\"\n    requires:\n      bins: [python3]\n      config:\n        - ~/.openclaw/openclaw.json\n---\n\n# Feishu Proactive Messenger | 飞书主动消息发送器\n\n飞书渠道只支持被动回复——用户先发消息，agent 才能回复。当 agent 需要**主动发起对话**（如 Agent A 派任务给 Agent B，Agent B 需要在自己的飞书窗口回复用户），飞书渠道没有这个能力。本 skill 通过直接调用飞书 OpenAPI 发送文本消息，补齐主动投递能力。\n\nThe 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.\n\n## 快速开始 | Quick Start\n\n```bash\npython3 scripts/feishu_proactive_messenger.py --agent <agent_id> --text \"Mission accomplished\"\n```\n\n`--agent` 指定当前 agent 的 id（如 `coder`、`data`、`life`），脚本会自动读取对应的飞书凭证和 `defaultTo` 目标用户。若省略 `--agent`，则通过 cwd 自动匹配。\n\n`--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.\n\n## 使用方法 | Usage\n\n```bash\npython3 scripts/feishu_proactive_messenger.py \\\n  --agent <agent_id> \\\n  --text \"要发送的消息内容\" \\\n  --receive-id <chat_id|open_id> \\\n  --receive-id-type <chat_id|open_id|user_id>\n```\n\n### 参数说明 | Arguments\n\n- `--agent`（推荐）：agent id（如 `coder`、`data`、`main`）。用于确定使用哪个飞书应用的凭证。若省略，通过 cwd 自动匹配（在被派发任务场景下可能不准确，建议显式指定）。\n- `--text`（必填）：要发送的消息文本。\n- `--receive-id`（可选）：目标 chat_id 或 open_id。若省略，依次从环境变量\n  `OPENCLAW_CHAT_ID` / `OPENCLAW_RECEIVE_ID` / `FEISHU_CHAT_ID` 或 account 的\n  `defaultTo` 配置中读取。\n- `--receive-id-type`（可选）：若省略，根据前缀自动识别：\n  - `oc_` → chat_id\n  - `ou_` → open_id\n  - `on_` → user_id\n\n- `--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).\n- `--text` (required): The message text to send.\n- `--receive-id` (optional): Target chat_id or open_id. If omitted, reads from\n  env `OPENCLAW_CHAT_ID` / `OPENCLAW_RECEIVE_ID` / `FEISHU_CHAT_ID`, or from\n  the account's `defaultTo` config.\n- `--receive-id-type` (optional): If omitted, auto-detect by prefix:\n  - `oc_` → chat_id\n  - `ou_` → open_id\n  - `on_` → user_id\n\n## 工作原理 | How It Works\n\n1. 通过 `--agent` 参数或 `cwd` 匹配确定当前 agent id。\n2. 根据 agent id 从 `~/.openclaw/openclaw.json` 读取对应 account 的 appId/appSecret。\n3. 从同一 account 的 `defaultTo` 读取默认目标用户（如未通过参数指定）。\n4. 获取 tenant access token。\n5. 通过飞书 `bot/v3/info` API 获取 bot 显示名称。\n6. 调用飞书 **发送消息** API（`im/v1/messages`）发送文本消息。\n7. 输出简洁结果：`✅ [Bot名称] 消息已发送`。\n\n1. Determine agent id via `--agent` parameter or by matching `cwd`.\n2. Read appId/appSecret from `~/.openclaw/openclaw.json` based on the agent id.\n3. Read the default target user from the same account's `defaultTo` (if not specified via args).\n4. Obtain a tenant access token.\n5. Retrieve the bot's display name via Feishu `bot/v3/info` API.\n6. Call Feishu **Send Message** API (`im/v1/messages`) to deliver the text message.\n7. Output clean result: `✅ [BotName] 消息已发送`.\n\n## 前置配置 | Prerequisites\n\n每个飞书 account 需要配置 `defaultTo`，指向目标用户的 open_id：\n\nEach Feishu account needs a `defaultTo` pointing to the target user's open_id:\n\n```bash\nopenclaw config set channels.feishu.accounts.<account>.defaultTo \"user:ou_xxx\"\n```\n\n注意：飞书的 open_id 是按应用隔离的，同一个用户在不同 bot 下有不同的 open_id。\n\nNote: Feishu open_id is app-scoped — the same user has different open_ids under different bots.\n\n## 错误处理 | Error Handling\n\n- **缺少凭证** → 确保 `channels.feishu.accounts` 存在于\n  `~/.openclaw/openclaw.json`，且 bindings 映射 agentId → accountId。\n- **机器人不在聊天中（230002）** → 用户需要先跟该 bot 发起过对话。\n- **缺少 receive_id** → 传入 `--receive-id`，设置 `OPENCLAW_CHAT_ID`，\n  或配置 `defaultTo`。\n- **HTTP 错误** → 查看飞书错误返回中的 `log_id` 进行排查。\n\n- **Missing credentials** → Ensure `channels.feishu.accounts` exists in\n  `~/.openclaw/openclaw.json` and bindings map agentId → accountId.\n- **Bot not in chat (code 230002)** → The user must have initiated a chat with\n  the bot at least once.\n- **Missing receive_id** → Pass `--receive-id`, set `OPENCLAW_CHAT_ID`,\n  or configure `defaultTo`.\n- **HTTP errors** → Check the returned `log_id` in Feishu error payload.\n\n## 安全说明 | Security\n\n本技能从 `~/.openclaw/openclaw.json` 读取飞书凭证：\n\n- `channels.feishu.accounts.*.appId`\n- `channels.feishu.accounts.*.appSecret`\n\n凭证仅用于获取 tenant access token 并发送消息。技能不会存储或向其他地方传输凭证。\n\nThis skill reads Feishu credentials from `~/.openclaw/openclaw.json`:\n\n- `channels.feishu.accounts.*.appId`\n- `channels.feishu.accounts.*.appSecret`\n\nThese values are used only to obtain a tenant access token and send the message.\nThe skill does not store or transmit credentials anywhere else.\n\n## 备注 | Notes\n\n- 本技能面向 **所有 agent** 设计，通过 `--agent` 参数或工作区匹配选择正确的飞书应用凭证。\n- 配合 `defaultTo` 使用时，agent 无需知道任何 ID 即可主动发消息。\n- 与 `feishu-file-sender` 互补：一个发文件，一个发文本。\n\n- Designed for **all agents**; uses `--agent` parameter or workspace matching to choose credentials.\n- When used with `defaultTo`, agents can send messages without knowing any IDs.\n- Complements `feishu-file-sender`: one sends files, the other sends text.\n\n## 随附脚本 | Bundled Script\n\n- `scripts/feishu_proactive_messenger.py`\n\n## 更新日志 | Changelog\n\n### 1.0.1\n- 新增 `--agent` 参数，显式指定 agent 身份（解决被派发任务时 cwd 匹配不准确的问题）\n- 新增通过飞书 `bot/v3/info` API 获取 bot 显示名称\n- 输出简化为 `✅ [Bot名称] 消息已发送`，不再暴露 open_id 等敏感信息\n- `resolve_agent_id` 支持 `agents.defaults.workspace` 作为 fallback\n\n### 1.0.0\n- 初始版本\n","tags":{"latest":"1.0.1"},"stats":{"comments":0,"downloads":807,"installsAllTime":30,"installsCurrent":2,"stars":1,"versions":2},"createdAt":1772095228672,"updatedAt":1778491649051},"latestVersion":{"version":"1.0.1","createdAt":1772096199787,"changelog":"Add --agent parameter for explicit agent identity, bot name display via Feishu API, cleaner output without sensitive info, defaults.workspace fallback","license":null},"metadata":{"setup":[{"key":"~/.openclaw/openclaw.json","required":true}],"os":null,"systems":null},"owner":{"handle":"ziwenwang28","userId":"s171mctt5y0wfc7zvv2fezmb8d83gm7k","displayName":"Ziwen Wang","image":"https://avatars.githubusercontent.com/u/84793687?v=4"},"moderation":null}