feishu-image

飞书图片发送器

向飞书（Lark）会话发送图片。此技能既可在 OpenClaw 中使用，也可作为独立 CLI 工具使用。

何时使用此技能

• 用户要求“截图发给我”
• 用户想通过飞书分享任何图片文件
• 需要通过飞书发送视觉内容（图表、示意图、照片）
• OpenClaw 内置的消息工具无法发送图片

配置

OpenClaw 用户

在 OpenClaw 中运行时，此技能会自动读取 OpenClaw 的飞书配置。无需手动设置。

独立使用

设置以下环境变量：

export FEISHU_APP_ID="cli_xxxxxxxxxxxxxxxx"
export FEISHU_APP_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

或者在项目根目录中创建一个 .env 文件：

FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

注意：如果在 OpenClaw 外运行且未配置凭据，此技能会显示清晰的错误消息和设置说明。

飞书应用设置

1. 前往 飞书开发者后台
2. 创建一个新应用（企业自建应用）
3. 启用以下权限：
   • im:resource - 上传图片
   • im:message - 发送消息
4. 在应用凭据页面获取 App ID 和 App Secret
5. 发布应用，并将其提供给组织使用

用法

作为 OpenClaw 中的技能

此技能会自动使用 OpenClaw 的飞书配置：

// Example: User asks to "send me a screenshot"
// The skill will automatically:
// 1. Read OpenClaw config for Feishu credentials
// 2. Upload the screenshot to Feishu
// 3. Send it to the user

作为 CLI 工具

向飞书用户发送图片：

node feishu-image.js --image /path/to/screenshot.png --to ou_xxxxxxxx

附带可选消息：

node feishu-image.js --image chart.png --to ou_xxxxxxxx --text "Q4 Sales Report"

发送到群聊：

node feishu-image.js --image announcement.png --to oc_xxxxxxxx --chat

作为 Node.js 库

const { FeishuImage } = require('./scripts/feishu-image.js');

const sender = new FeishuImage({
  appId: 'cli_xxxxxxxxxxxxxxxx',
  appSecret: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
});

// Send image to a user
await sender.sendImage({
  imagePath: '/path/to/screenshot.png',
  receiveId: 'ou_xxxxxxxx',
  receiveType: 'user'
});

// Send image with text
await sender.sendImage({
  imagePath: '/path/to/chart.png',
  receiveId: 'ou_xxxxxxxx',
  receiveType: 'user',
  text: 'Here is the sales report'
});

CLI 参考

选项

选项	简写	说明	必填
--image	-i	图片文件的路径	是
--to	-t	接收者的飞书 open_id 或 chat_id	是
--text		可选的附带文本消息	否
--chat	-c	发送到群聊（默认：用户）	否
--help	-h	显示帮助消息	否

示例

# Basic usage
node feishu-image.js -i screenshot.png -t ou_123456

# With message
node feishu-image.js --image chart.png --to ou_123456 --text "Q4 Report"

# To group chat
node feishu-image.js -i announcement.png -t oc_789012 --chat

库 API 参考

new FeishuImage(config)

创建一个新的飞书图片发送器实例。

参数：

• config.appId (string)：飞书应用 ID
• config.appSecret (string)：飞书应用密钥
• config.baseUrl (string, optional)：API 基础 URL，默认为 'https://open.feishu.cn/open-apis'

示例：

const sender = new FeishuImage({
  appId: process.env.FEISHU_APP_ID,
  appSecret: process.env.FEISHU_APP_SECRET
});

async sendImage(options)

上传图片并发送到飞书会话。

参数：

• options.imagePath (string, required)：本地图片文件的路径
• options.receiveId (string, required)：接收者的 open_id（用户）或 chat_id（群组）
• options.receiveType (string, optional)：'user' 或 'chat'，默认为 'user'
• options.text (string, optional)：可选的随图片发送的文本消息

返回值： Promise - 已发送消息的 ID

抛出异常：

• FeishuImageError - 各种错误代码：MISSING_CREDENTIALS、AUTH_FAILED、FILE_NOT_FOUND、UPLOAD_FAILED、SEND_FAILED

示例：

try {
  const messageId = await sender.sendImage({
    imagePath: '/path/to/screenshot.png',
    receiveId: 'ou_xxxxxxxx',
    receiveType: 'user',
    text: 'Here is the screenshot you requested'
  });
  console.log('Image sent successfully, message ID:', messageId);
} catch (error) {
  console.error('Failed to send image:', error.message);
}

错误处理

所有错误均为 FeishuImageError 实例，并带有特定错误代码：

错误代码	说明	解决方案
MISSING_CREDENTIALS	未设置 FEISHU_APP_ID 或 FEISHU_APP_SECRET	设置环境变量或传入构造函数
AUTH_FAILED	飞书 API 身份验证失败	检查 app_id 和 app_secret 是否正确
FILE_NOT_FOUND	图片文件不存在	检查图片路径是否正确
UPLOAD_FAILED	上传图片到飞书失败	检查网络连接和文件大小限制
SEND_FAILED	发送消息失败	检查接收者 ID 和权限

错误处理示例：

const { FeishuImage, FeishuImageError } = require('./scripts/feishu-image.js');

try {
  await sender.sendImage({ ... });
} catch (error) {
  if (error instanceof FeishuImageError) {
    switch (error.code) {
      case 'MISSING_CREDENTIALS':
        console.error('Please set FEISHU_APP_ID and FEISHU_APP_SECRET');
        break;
      case 'AUTH_FAILED':
        console.error('Invalid credentials. Check your app ID and secret.');
        break;
      case 'FILE_NOT_FOUND':
        console.error(`Image file not found: ${error.details.path}`);
        break;
      default:
        console.error(`Error: ${error.message}`);
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

限制

• 图片大小：受飞书 API 限制（当前限制请查看飞书文档）
• 支持的格式：PNG、JPG、GIF（以飞书支持的格式为准）
• 速率限制：受飞书 API 速率限制

另请参阅

• Feishu 开放平台文档
• Feishu 图片上传 API
• Feishu 消息发送 API
• Peekaboo - 截图工具（如适用）