feishu-claude-code-bridge

用途

feishu-claude-code-bridge（包名 lark-channel-bridge）用于把飞书（Lark）的消息与本地运行的 Claude Code CLI 打通。发给机器人的消息会被转发到用户指定工作目录中的 claude 命令，Claude 的回复则以实时流式卡片的形式回到飞书会话中。

主要能力

流式卡片：Claude 的输出会在单张飞书卡片中实时更新。
每会话独立会话：每个聊天/话题维护自己的 Claude 会话。
多工作区：通过 /ws 在多个项目目录之间切换，会话历史按工作区保留。
图片与文件：可直接发送媒体，Claude 读取机器人下载到本地的文件路径。
抢占：新消息可以中断正在运行的请求。
访问控制：可选的用户、群聊允许列表以及管理员命令限制。

安装与前置条件

前置条件：Node.js >= 20；已安装并完成认证的 claude CLI；飞书/Lark PersonalAgent 应用（首次运行通过二维码向导创建）。

全局安装：

npm install -g lark-channel-bridge
# 或
pnpm add -g lark-channel-bridge

官方说明强调：在使用守护进程/服务命令前始终先全局安装，因为 npx 路径是临时的，会破坏后台服务。

首次设置

lark-channel-bridge run

首次运行且无配置时：终端显示二维码，用飞书/Lark 应用扫描，选择或创建 PersonalAgent 应用，凭据保存到 ~/.lark-channel/config.json（权限 600）。

使用方式

进程管理

# 前台（交互式）
lark-channel-bridge run [-c <config>]

# 列出所有运行中的桥接
lark-channel-bridge ps

# 结束指定桥接
lark-channel-bridge kill <id|#>

# 帮助
lark-channel-bridge --help

守护进程/服务管理

# 安装并启动守护进程
lark-channel-bridge start

# 停止守护进程
lark-channel-bridge stop

# 原地重启
lark-channel-bridge restart

# 查看状态
lark-channel-bridge status

# 移除服务定义
lark-channel-bridge unregister

平台映射：macOS 为 launchd 用户代理；Linux 为 systemd 用户单元（需 loginctl enable-linger $USER 以在注销后保持）；Windows 为任务计划程序任务。日志位于 ~/.lark-channel/logs/。

旧版本迁移：

lark-channel-bridge migrate

聊天内命令

在飞书/Lark 聊天中发送：

命令	说明
/new、/reset	清除当前聊天的 Claude 会话
/cd <path>	切换工作目录（会重置会话）
/ws list	列出命名工作区（交互卡片）
/ws save <name>	将当前目录保存为工作区
/ws use <name>	切换到命名工作区
/ws remove <name>	删除工作区
/status	显示当前目录/会话/代理
/config	调整偏好（回复样式、访问控制、超时）
/stop	终止正在运行的 Claude 进程
/timeout [N\|off\|default]	设置会话空闲看门狗（分钟）
/ps	列出所有运行中的桥接进程
/exit <id\|#>	停止某个桥接进程
/reconnect	强制 WebSocket 重连
/doctor [description]	基于近期日志自诊断
/help	显示帮助卡片
其它 /xxx	原样转发给 Claude

回复行为：私聊中机器人回复所有消息；群聊中默认仅在 @ 提及时回复（自 0.1.22 起）。可通过 /config 中的“Require @bot in groups”修改。

配置

配置文件 ~/.lark-channel/config.json 结构示例：

{
  "appId": "cli_xxxxxxxxxxxxxxxx",
  "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "preferences": {
    "access": {
      "allowedUsers": [],
      "allowedChats": [],
      "admins": []
    },
    "requireAtInGroups": true,
    "defaultTimeoutMinutes": 0,
    "replyStyle": "streaming",
    "showToolCalls": true
  }
}

访问控制可通过 /config 或直接编辑 JSON 设置，支持仅个人使用、团队受限管理员、仅特定群组等场景。空字段表示不限制；私聊不受群聊允许列表限制；更改在下一条消息生效，无需重启。管理员命令包括 /account、/config、/exit、/reconnect、/doctor、/cd、/ws。

数据目录

路径	内容
~/.lark-channel/config.json	应用凭据（权限 600）
~/.lark-channel/sessions.json	每个聊天的会话 ID 与工作目录
~/.lark-channel/workspaces.json	命名工作区映射
~/.lark-channel/processes.json	供 ps/stop 使用的进程注册表
~/.lark-channel/media/<chatId>/	下载的文件（24 小时清理）
~/.lark-channel/logs/YYYY-MM-DD.log	结构化日志（默认保留 7 天，可用 LARK_CHANNEL_LOG_DAYS 配置）

适用场景

在飞书内直接调用本地 Claude Code 处理项目任务，并让回复以流式卡片呈现。
在多个项目目录间频繁切换，用命名工作区保持各自会话历史。
通过飞书发送图片或文件给 Claude 读取处理。
团队或个人按需要限制可访问的用户、群聊与管理员命令。

限制与注意事项

需要 Node.js >= 20、已认证的 claude CLI 和飞书 PersonalAgent 应用。
使用守护进程/服务命令前必须先全局安装，npx 路径会导致后台服务失效。
Docker 部署为非官方支持的社区做法。
若出现机器人无响应、卡片冻结、守护进程重启后未启动、多实例争抢事件等问题，官方提供了对应的排查步骤（/status、/new、/cd、/stop、/timeout、/reconnect、/doctor、loginctl enable-linger 等）。
协议为 MIT。

（价格、收费等其它信息原文暂未提供。）