lark-channel-bridge

对于习惯使用 Claude Code CLI 进行本地代码开发和文件处理的开发者而言，受限于终端环境、无法随时随地交互往往是一个痛点。lark-channel-bridge 是一个轻量级的 Bot 工具，旨在将飞书（Lark）消息与本地 Claude Code CLI 无缝打通。

只需一条命令启动服务，扫码绑定应用，你就能在飞书中直接给 Claude 发送指令、上传图片或文件，让它读取本地路径、修改代码，并实时接收流式反馈。

核心亮点：为何选择 lark-channel-bridge？

1. 极简部署，扫码即用

• 一键启动：通过 npm i -g lark-channel-bridge 安装后，运行 lark-channel-bridge run 即可启动。
• 自动配置：首次启动会自动渲染二维码，使用飞书 App 扫码即可创建或绑定 PersonalAgent 应用，凭据自动写入本地配置，无需手动申请 API Key。

2. 流式卡片，实时反馈

• 所见即所得：Claude 的文本回复和工具调用状态会实时呈现在同一张飞书卡片上，无需等待生成结束即可看到进展。
• 交互按钮：卡片底部提供“终止”、“重试”等按钮，方便随时干预正在运行的任务。

3. 多工作空间与会话管理

• 独立 Session：每个聊天窗口（私聊或群话题）拥有独立的 Claude Session，对话上下文互不干扰。
• 工作空间切换：通过 /ws 命令轻松切换不同项目目录，Session 自动重置，确保 Claude 在正确的上下文中工作。
• 抢占与批处理：中途发送新消息会打断旧任务；快速连发多条消息会自动合并为一次请求，避免资源浪费。

4. 多媒体支持

• 图片/文件直传：直接在飞书中发送图片或文件，Bot 会自动下载到本地临时目录，并将路径传递给 Claude，实现“看图说话”或“基于文件编程”。

快速开始指南

1. 前置条件

• Node.js ≥ 20
• Claude Code CLI 已安装并登录（参考 Anthropic 官方文档）
• 飞书/Lark 账号

2. 安装与启动

# 全局安装
npm i -g lark-channel-bridge

# 首次启动（进入扫码向导）
lark-channel-bridge run

扫码成功后，凭据将保存至 ~/.lark-channel/config.json。

3. 后台常驻（推荐）

为了让 Bot 在后台稳定运行并支持开机自启，建议使用服务层命令：

# 注册并启动后台 daemon
lark-channel-bridge start

# 查看状态
lark-channel-bridge status

# 停止服务
lark-channel-bridge stop

注：daemon 模式支持 macOS (launchd)、Linux (systemd) 和 Windows (Task Scheduler) 的自动拉起。

飞书中的常用命令

其他非斜杠命令将直接发送给 Claude 处理。

权限管理与安全控制

默认情况下，Bot 对所有人开放。为了保障安全，特别是团队使用时，建议通过 /config 配置访问控制：

1. 用户白名单 (allowedUsers)：仅允许指定的 open_id 用户与 Bot 私聊或在群中触发响应。
2. 群白名单 (allowedChats)：仅允许 Bot 在指定的群聊中响应 @ 消息（私聊不受此限制，确保管理员可随时解锁）。
3. 管理员 (admins)：仅允许指定用户执行敏感命令（如 /config, /exit, /cd 等）。

如何获取 Open_ID 和 Chat_ID？
让目标用户或群组给 Bot 发送一条消息，然后在终端查看日志：

grep '"event":"enter"' ~/.lark-channel/logs/$(date +%Y-%m-%d).log | tail -5

日志中将包含 senderId (用户 ID) 和 chatId (群 ID)。

常见问题排查

• Claude 不回复？
  • 检查 claude CLI 是否已正确登录。
  • 使用 /status 确认当前工作目录是否存在。
  • 尝试 /new 重置会话。
• 子进程假死？
  • 从 v0.1.20 起支持 idle 探活。可通过 /timeout 10 设置当前会话 10 分钟无输出自动终止，或在 /config 中设置全局默认值。
• 图片无法识别？
  • 确保升级到最新版本（v0.1.0+ 修复了文件名去重 Bug）。