Feishu Proactive Messenger

飞书主动消息发送器 — 飞书渠道只支持被动回复，agent 无法主动发起对话。本 skill 调用飞书 OpenAPI 发送文本消息，补齐主动投递能力。| Feishu Proactive Messenger — Send text messages proactively via Feishu OpenAPI,...

Security Scan

The skill's code, instructions, and requested local config are coherent with its stated purpose of proactively sending Feishu text messages and do not request unrelated credentials or install remote code.

Purpose & Capability

Name/description match the implementation: a Python CLI that reads Feishu appId/appSecret from ~/.openclaw/openclaw.json and calls Feishu OpenAPI to send text messages. Required binary (python3) and required config path are proportional to the described functionality.

Instruction Scope

SKILL.md and the bundled script limit operations to reading ~/.openclaw/openclaw.json, optional environment variables (OPENCLAW_CHAT_ID / OPENCLAW_RECEIVE_ID / FEISHU_CHAT_ID), resolving agent bindings, obtaining a tenant token, calling Feishu bot/info and im/v1/messages, and printing a result. There are no instructions to read unrelated system files or transmit data to endpoints beyond Feishu's open.feishu.cn.

Install Mechanism

No install spec that downloads or writes code to disk; the skill is instruction-only with a bundled Python script. It requires the requests library (documented). No remote/untrusted downloads or archive extraction are present.

Credentials

The only secret material the script needs is appId/appSecret from the declared OpenClaw config path; optional env vars used are for target IDs. It does not request unrelated cloud credentials or other secret tokens.

Persistence & Privilege

always is false and the skill does not attempt to modify other skills or system-wide agent configuration. It runs on demand (user-invocable) and does not request persistent elevated privileges.

Assessment

This skill appears to be what it says: a small Python CLI that reads Feishu appId/appSecret from your local OpenClaw config and calls Feishu's official OpenAPI to send a text message. Before installing/using it: (1) verify ~/.openclaw/openclaw.json contains only the account entries you expect and limit file permissions so only your user can read it; (2) confirm the Feishu app credentials have the minimal scopes needed (send messages) and do not expose broader privileges you don't want to share; (3) ensure you trust the agent(s) that will invoke this skill because it can send outbound messages on their behalf; and (4) install the requests package in a controlled environment (virtualenv) if desired. No remote downloads or unrelated credential access were found.

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

• 初始版本