我花了两分钟，把飞书变成了Ai编程终端

bluebluesky
66 阅读5分钟

把飞书变成 Claude Code 的聊天窗口：lark-channel-bridge 接入全指南

前言

你是否想过，在飞书里发条消息就能操控电脑？让 AI 帮你写代码、改 Bug、管理文件，而你只需要像跟同事聊天一样在飞书里说句话？

lark-channel-bridge 就是干这件事的：它把飞书消息和本地 Claude Code CLI 打通，让你在任何地方用飞书遥控电脑上的 AI 干活。

本文以 macOS 真机实战 视角，从零开始带你完成接入全流程，附带踩坑记录和生产环境配置技巧。

它能干什么

  • 飞书私聊 bot 或群里 @bot，消息直通本地 Claude CLI
  • 流式卡片回复：Claude 的思考和工具调用实时出现在一张卡片上，不用干等
  • 会话延续：每个聊天独立 session，上下文不会丢
  • 文件 / 图片透传：直接发给 bot，Claude 能读
  • 多工作空间切换：不同项目来回切，session 自动隔离
  • 交互卡片：/help、/status 等命令返回按钮卡片，点就能操作
  • 访问控制：可配置白名单，限定谁能用

前置条件

条件说明
Node.js >= 20推荐用 nvm 管理版本
Claude Code CLInpm i -g @anthropic-ai/claude-code，并完成登录
飞书账号用于创建 PersonalAgent 应用

安装与首次启动

第一步：安装 bridge

npm i -g lark-channel-bridge

第二步：启动并扫码绑应用

lark-channel-bridge run

第一次运行会自动进入扫码向导：

  1. 终端显示二维码
  2. 用飞书 App 扫码
  3. 选择或创建一个 PersonalAgent 应用
  4. 凭据自动写入 ~/.lark-channel/config.json

整个过程不到两分钟，不需要去飞书开放平台手动配 App ID 和 Secret。

第三步：设为后台服务（推荐）

前台 run 模式关掉终端就没了。注册为系统服务：

lark-channel-bridge start

底层平台映射：

系统守护方式
macOSlaunchd 用户代理
Linuxsystemd 用户单元
WindowsTask Scheduler

设置为系统服务后，崩溃自动拉起 + 开机自启，不用再管它。

第四步：测试

在飞书里找到你的 bot，发一句 "你好"，看有没有回复。

架构原理

飞书客户端
    │
    ▼ (WebSocket 长连接)
飞书开放平台
    │
    ▼ (WebSocket 长连接，无需公网IP)
lark-channel-bridge (你的电脑)
    │
    ▼ (spawn 子进程)
Claude Code CLI
    │
    ▼ (系统调用)
你的电脑 / 文件 / 代码

几个关键点：

  • WebSocket 长连接：bridge 和飞书服务器之间用一个 WS 保持双向通信，不需要你电脑有公网 IP
  • Claude CLI 子进程：每个飞书聊天对应一个 Claude 进程，独立 session，互不干扰
  • 抢占式处理：会话中发新消息会中断旧任务，快速连发会合并成一次请求

日常使用

基本操作

在飞书里给 bot 发消息就行，跟聊天一样。Claude 会在你当前的工作目录里执行操作。

常用斜杠命令

命令作用
/new清空当前会话（相当于新开一局）
/cd <path>切换工作目录
/ws save <name>保存当前路径为命名工作空间
/ws use <name>快速切换到某工作空间
/status查看当前状态
/stop终止当前运行中的任务
/help帮助卡片
/config调整偏好设置

私聊 vs 群聊

  • 私聊：消息直接处理，无需 @bot
  • 群聊：默认需要 @bot 才响应（可在 /config 里改）
  • 话题群：同样需要 @bot

进阶配置

阻止电脑休眠（重要）

默认情况下电脑熄屏后会休眠，网络断开，飞书消息无法到达。

方法：用 caffeinate 包裹 bridge 进程

# 临时方案：启动时加 caffeinate
caffeinate -s lark-channel-bridge run

-s 参数：阻止系统休眠，但允许屏幕正常熄灭，网络保持活跃。

永久方案：创建独立的 launchd agent

在 ~/Library/LaunchAgents/ 下创建一个 plist，开机自启 caffeinate：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>ai.caffeinate-bridge</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/caffeinate</string>
        <string>-s</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

访问控制

在飞书里发 /config，可以设置：

  • 用户白名单：只有名单里的人能跟 bot 对话
  • 群白名单：只有指定群里的 @bot 才响应
  • 管理员：只有管理员能改配置

查 open_id 和 chat_id 的方法：

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

想让目标用户给 bot 先发条消息，日志里就会出现。

数据目录

路径内容
~/.lark-channel/config.json应用凭据
~/.lark-channel/sessions.json每个聊天的 session 状态
~/.lark-channel/workspaces.json工作空间映射
~/.lark-channel/logs/运行日志（按天滚动）

实战踩坑记录

坑 1：电脑熄屏后 bot 无响应

现象：手机飞书发消息，电脑没反应。

原因：macOS 休眠导致网络断开，WebSocket 长连接中断。

解决：用 caffeinate 保持系统唤醒（见上文「阻止电脑休眠」）。

坑 2：群聊里 bot 不回复

现象：群里发消息，bot 完全不理。

原因：默认群聊需要 @bot 才会响应。

解决：发消息时 @bot，或者在 /config 里关闭「群里需要 @bot」。

坑 3：bridge stop/start 会覆盖自定义 plist

现象：手动改了 launchd plist，执行 lark-channel-bridge start 后被覆盖。

原因：start 命令会重新生成 plist。

解决：需要额外启动的守护进程（如 caffeinate）用独立的 plist，别改 bridge 自带的。

坑 4：Claude 卡住不回复

现象：发消息后卡片停住不动。

排查：

  1. 发 /status 看当前状态
  2. 发 /new 重开会话
  3. 发 /doctor 自动诊断

扩展可能性

Bridge 本身是个通道，不只限于 Claude。可以在此基础上做：

  • 多模型路由：简单问题走免费模型，复杂问题走 Claude
  • 自定义 Agent：接到自己的 API 上，跑任何 LLM
  • 多端协作：多台电脑注册同一个 bot，不同工作环境切换

总结

lark-channel-bridge 把 AI 编程助手真正变成了「随时随地可用」的工具：

  • 安装简单：一条 npm 命令 + 扫码 = 完成
  • 运维省心：系统服务托管，崩溃自动恢复
  • 体验流畅：流式卡片 + 会话延续 + 抢占打断

我现在每天用它：在通勤路上用飞书让家里的电脑跑代码、改配置、查日志，到公司打开电脑结果已经在等着我了。

如果你也在用，欢迎交流踩坑经验。

avatar
文章
阅读
粉丝