feishu-unofficial

Feishu Channel for Claude Code

飞书 (Feishu/Lark) 通道插件，让 Claude Code 可以通过飞书与用户交互。

功能

• 📱 通过飞书私聊和群聊与 Claude Code 交互
• 🔐 内置访问控制：配对流程、白名单、策略管理
• 🔄 WebSocket 长连接模式：本地开发无需公网 IP
• 🎯 群组 @ 提及检测
• 🔔 权限请求转发：Claude Code 的权限请求推送到飞书让用户批准

前置条件

• Bun — 安装：curl -fsSL https://bun.sh/install | bash
• Claude Pro/Max 账户（使用 --channels 需要 claude.ai 付费账户）

快速开始

以下为单用户私聊机器人的默认配对流程。群组和多用户设置详见 ACCESS.md。

1. 创建飞书应用

1. 访问 飞书开放平台（国际版用 Lark）
2. 点击「创建企业自建应用」
3. 填写应用名称和描述，创建应用
4. 进入应用详情页，在「凭证与基础信息」中获取：
   • App ID — 格式如 cli_a93643d59af89ceb
   • App Secret — 格式如 W4h7t7MAYDvfDsM0vZNdNfknOKbEpkpE
5. 在「权限管理」中开通以下权限：
   • im:message - 获取与发送单聊、群组消息
   • im:message:send_as_bot - 以应用身份发消息
   • contact:user.base:readonly - 获取用户基本信息
6. 在「事件订阅」中启用 WebSocket 模式（无需公网 IP）

2. 安装插件

在 Claude Code 会话中运行：

/plugin install feishu-unofficial

3. 配置凭证

/feishu-unofficial:configure <your_app_id> <your_app_secret>

这会将凭证写入 ~/.claude/channels/feishu/.env。

国际版 Lark 用户：在 .env 中添加 FEISHU_DOMAIN=lark

4. 启动带通道的会话

退出当前会话，用 --channels 参数启动：

claude --channels plugin:feishu-unofficial

5. 配对

在飞书中给你的机器人发私信，它会回复一个 6 位配对码。然后在 Claude Code 中：

/feishu-unofficial:access pair <code>

你的下一条私信就会发送给助手。

6. 锁定访问（推荐）

配对完成后，切换到 allowlist 模式防止陌生人访问：

/feishu-unofficial:access policy allowlist

访问控制

详见 ACCESS.md，包含：

• 私聊策略（pairing / allowlist / disabled）
• 群组配置和提及检测
• 技能命令参考

快速参考：用户 ID 是 Open ID 格式（如 ou_xxxxx）。

暴露给助手的工具

工具	用途
reply_to_feishu	发送消息到飞书聊天
reply_with_reaction_feishu	对消息添加表情反应
manage_feishu_access	管理访问控制（list/pair/allow/deny/policy 等）

助手回复时会自动触发「正在输入」指示器。

媒体文件

收到的图片会下载到 ~/.claude/channels/feishu/inbox/，助手可以用 Read 工具读取。

限制

• 无历史记录：飞书 Bot API 不提供消息历史，机器人只能看到实时消息
• 无搜索功能：没有 fetch_messages 工具，助手需要你提供上下文

权限请求转发

当 Claude Code 需要批准敏感操作时：

1. 收到通知：[权限请求] <request_id>: <操作描述>
2. 回复 yes <request_id> 批准，或 no <request_id> 拒绝

配置文件

文件	用途
~/.claude/channels/feishu/.env	凭证（App ID、App Secret）
~/.claude/channels/feishu/access.json	访问控制配置

开发

bun install
bun server.ts

发布到 npm

必需文件

claude-channel-feishu-unofficial/
├── .claude-plugin/
│   └── plugin.json      # 插件元信息（name: "feishu-unofficial"）
├── .mcp.json            # MCP 服务器启动配置
├── package.json         # npm 包配置（name: "claude-channel-feishu-unofficial"）
├── server.ts            # 主程序
├── skills/
│   ├── access/SKILL.md
│   └── configure/SKILL.md
├── README.md
├── ACCESS.md
├── LICENSE
└── .gitignore

关键配置

package.json — npm 包名（用户 npm install 用）

{
  "name": "claude-channel-feishu-unofficial",
  "bin": "./server.ts",
  "type": "module"
}

.claude-plugin/plugin.json — 插件名（用户 /plugin install 用）

{
  "name": "feishu-unofficial",
  "description": "..."
}

.mcp.json — MCP 服务器启动

{
  "mcpServers": {
    "feishu-unofficial": {
      "command": "bun",
      "args": ["run", "--cwd", "${CLAUDE_PLUGIN_ROOT}", "--shell=bun", "--silent", "start"]
    }
  }
}

发布步骤

# 1. 登录 npm
npm login

# 2. 发布（首次发布需要 --access public）
npm publish --access public

# 3. 后续更新
npm version patch  # 或 minor / major
npm publish

用户安装方式

发布后，用户可以通过两种方式安装：

方式 1：Claude Code 内部安装

/plugin install feishu-unofficial

方式 2：全局 npm 安装

npm install -g claude-channel-feishu-unofficial

架构

┌─────────────────────┐
│  Claude Code        │
│  └── MCP Client     │
└─────────┬───────────┘
          │ stdin/stdout
┌─────────▼───────────┐
│  server.ts          │
│  ├── MCP Server     │
│  ├── Access Control │
│  ├── Permission Relay│
│  └── WS Client      │
└─────────┬───────────┘
          │ WebSocket
┌─────────▼───────────┐
│  飞书服务器          │
└─────────────────────┘

参考文档

• Claude Code Channels 官方文档
• Channels Reference
• 飞书开放平台

许可证

Apache-2.0