coderover

把飞书 / Lark 消息和本地 Claude Code、Codex CLI 或飞书 CodeM 打通的轻量 bot。用一条命令启动，扫码绑定 PersonalAgent 应用，然后在飞书里和本机编程助手对话，让它读图、处理文件、改代码。

English README

关于能实现的效果，详情可以阅读飞书文档

主要功能

• 在飞书私聊直接发消息，或在群里 @bot，把任务转给本机 Claude Code / Codex CLI / CodeM。
• 流式卡片：文本回复和工具调用实时更新在同一张卡片上。
• COT 过程消息：可选先发一条过程消息展示 agent 的阶段性文本和工具调用，再单独发送最终答案。
• 会话延续：每个聊天、话题或文档评论有自己的会话，不会互相串。
• 排队与消息合并：短时间连续发送的消息会合并处理；任务运行中收到的普通消息会排队到下一轮，/new、/cd、/ws use、/stop 这类命令可以中断当前任务。
• 多工作空间：用 /cd 切换当前项目，用 /ws 保存和复用常用项目目录。
• 图片 / 文件：直接发给 bot，bridge 下载到本地后交给本机 agent 处理。
• 卡片按钮：/help、/ws list、/status 返回可点击的交互卡片。

前置条件

• Node.js >= 20.12.0
• 本机至少安装并登录一个 agent：
  • Claude Code：claude，安装说明：https://docs.anthropic.com/en/docs/claude-code/quickstart
  • Codex CLI：codex，安装说明：https://developers.openai.com/codex/cli
  • CodeM：codem，见下文用 CodeM 作为后端
• 一个飞书 / Lark PersonalAgent 应用。首次启动的扫码向导可以帮你创建并绑定。

安装

npm install -g coderover

首次启动

coderover run

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

1. 终端渲染二维码。
2. 用飞书 App 扫码。
3. 选择或创建 PersonalAgent 应用。
4. 如果终端提示，选择本次要初始化的 agent。
5. 成功后配置写入 ~/.lark-channel/config.json。

没有指定项目目录也可以启动。bridge 会创建一个 profile 托管的默认工作目录；启动后在飞书里发送 /cd <path> 切到实际项目。

如果已经有 PersonalAgent app，可以在初始化时传 --app-id 跳过创建应用流程；命令会提示输入 App Secret。

coderover run --app-id cli_xxx
# 或直接初始化并启动后台服务
coderover start --app-id cli_xxx

后台运行

run 适合首次配置和前台调试。确认 bot 能正常收发消息后，先用 Ctrl-C 停掉前台进程，再用系统服务常驻后台：

coderover start
coderover status
coderover stop

服务层命令必须先全局安装，不能直接用 npx。daemon 的 launchd plist / systemd unit / Windows 任务会记录 bridge CLI 的路径；如果这个路径来自 npm 临时缓存，缓存清掉后 daemon 就起不来。run 用 npx 单次启动没问题。

服务层命令按 profile 注册，每个 profile 有独立服务：

coderover start [--profile <name>]
coderover stop [--profile <name>]
coderover restart [--profile <name>]
coderover status [--profile <name>]
coderover unregister [--profile <name>]

平台映射：

• macOS：launchd 用户代理 ai.coderover.bot.<profile>
• Linux：systemd 用户单元 coderover.bot.<profile>.service
• Windows：Task Scheduler 任务 Coderover.Bot.<profile>，launcher 是 .cmd

daemon 日志在 ~/.lark-channel/profiles/<profile>/logs/daemon/。

多 profile：分别运行 Claude、Codex 和 CodeM

默认情况下，bridge 使用当前激活的 profile；可以通过 profile use <name> 切换。每个 profile 会维护独立的应用凭据、会话、工作目录和日志。只有在需要同时连接多个 PersonalAgent 应用，或分别运行 Claude、Codex 和 CodeM 时，才需要创建多个 profile：

coderover start --profile claude --agent claude
coderover start --profile codex --agent codex
coderover start --profile codem --agent codem

例如只重启 Codex bot：

coderover restart --profile codex
coderover status --profile codex

用 CodeM 作为后端

CodeM 是飞书原生的 AI 开发 agent，bridge 把它当作第三种 agent 后端。接进来之后用法与其他两种完全一致：飞书里发消息、/cd、/resume、/stop、权限档位、卡片按钮都照常。

安装与登录

curl -fsSL https://codem-public.tos-cn-beijing.volces.com/codem/install.sh | bash
export PATH="$HOME/.codem/bin:$PATH"   # 建议写进 ~/.bashrc 或 ~/.zshrc
codem login                            # 只需一次，设备绑定

安装脚本默认拒绝以 root 身份运行，确有需要时用 CODEM_ALLOW_ROOT=1 显式放行。

然后创建 profile 并启动：

coderover profile create codem --agent codem
coderover start --profile codem

首次启动的扫码向导里也可以直接选 CodeM。

daemon 不是前置条件

bridge 每次运行都直接拉起 CodeM 的 launcher，不需要 codem daemon 常驻。如果你另外想要 CodeM 自带的飞书入口或自动更新，再自行 nohup codem daemon &，两者互不干扰。

权限档位

read-only 档下 agent 动不了你的文件，但每一步都会多一次往返（CodeM 的授权请求没有超时，bridge 作为应答方必须逐个回）。

状态目录与身份

CodeM 自己的状态放在 $CODEM_HOME（默认 ~/.codem），不在 ~/.lark-channel 下。用它登录过一次之后：

• 必须用 $CODEM_HOME 的属主用户运行 bot。 换个用户跑（例如 root 启动、但 ~/.codem 属于别人）会写出错误属主的产物，并干扰 CodeM 自身的 daemon。/doctor 会检查这一点。
• CodeM 的访问 token 只有 1 小时，但由 launcher 每次运行时自动续期，bridge 不需要干预。/doctor 报 token 临期只是告警；refresh token 过期才是需要重新 codem login 的情况。
• bridge 会在工作目录下写入 .codem-plugin/plugin.json 和 agents/bridge/AGENT.md，用来把 coderover 的桥接身份作为系统提示词注入 CodeM。这两个文件是 bridge 托管的，不用手工改。

已验证版本与授权

bridge 针对 CodeM 0.1.227 做过端到端验证，版本漂移时 /doctor 会提示。

CodeM 由飞书提供（@lark-codem/*），分发包标注 All rights reserved，使用需遵循飞书用户服务条款，不是开源许可。是否在你所在的环境中使用，请自行确认。

命令速查

宿主 CLI

coderover run [--profile <name>] [--agent claude|codex|codem] [--workspace <path>] [-c <config>]
coderover migrate [--profile <name>] [--agent claude|codex|codem]
coderover ps
coderover kill <id|#>
coderover --help

profile use <name> 会切换后续默认启动使用的 profile。需要同时跑 Claude / Codex / CodeM 多个 bot、连接多套 PersonalAgent 应用，或做脚本化部署时，再使用这些 profile 管理命令：

coderover profile create claude --agent claude
coderover profile create codex --agent codex
coderover profile create codem --agent codem
coderover profile list
coderover profile use <name>
coderover profile remove <name>
coderover profile remove <name> --purge --yes
coderover profile export <name> [--output ./profile.json] [--force]
coderover profile export <name> --include-secrets --yes

profile remove 默认归档本地状态，也可以删除当前激活的 profile。若还剩其他 profile，会自动切到下一个；若这是最后一个 profile，会清空 root config，之后可以用同名重新创建。只有加 --purge --yes 才会永久删除。profile export 默认脱敏 app secret；只有加 --include-secrets --yes 才会导出敏感配置。

如果某个 profile 被建成了错误的 agent 类型，先 stop 或 unregister --profile <name> 清理对应后台服务，再 profile remove <name>，然后用正确的 --agent 重新创建。

飞书内斜杠命令

私聊不需要 @。群和话题群默认必须 @bot；@all 会被忽略。支持的云文档评论里 @bot 就会触发回复。

回复展示与 COT

/config 可以调整三类展示选项：

• 消息回复方式：消息卡片 流式更新最终回复；纯文本 在 run 完成后一次性发送。
• 工具调用显示：控制最终回复卡片 / markdown 中是否展示工具块。
• COT 过程消息：关闭 只发送最终回复；简略 先用 COT 消息展示 agent 的过程文本和工具摘要；详细 还会展示工具参数和截断后的输出。

开启 COT 后，bridge 会把过程消息和最终答案拆成两条消息。过程消息用于追踪 agent 做了什么；最终答案仍由 agent 原始文本生成，bridge 不做启发式过滤。若 agent 把最终答案也作为普通流式文本输出，COT 过程消息中可能会出现对应片段。

lark-cli 身份策略

每个 profile 都使用当前 profile 的 lark-cli 目录：~/.lark-channel/profiles/<profile>/lark-cli。agent 子进程会收到指向这个目录的 LARKSUITE_CLI_CONFIG_DIR，所以一个 profile 里的个人授权不会共享给另一个 profile。

默认策略是 bot-only：lark-cli 使用应用 / bot 身份，不访问个人资源。当用户为了日历、邮箱、云盘等个人资源完成授权后，当前 profile 可以切到 user-default，保留应用身份，同时允许已授权的用户身份。owner/admin 可以在 /config 查看或切换这个策略；/status 会用 lark-cli: app 或 lark-cli: user-ready 展示当前摘要。

工作目录

每个 profile 都可以有一个默认工作目录：workspaces.default。新建 profile 时可以传 --workspace <path> 作为初始目录；没传时 bridge 会创建一个 profile 托管的默认工作目录。

下面只是 profile 里的字段片段，不要整段覆盖 config.json；请改对应 profile 下的 workspaces 字段。

{
  "workspaces": {
    "default": "/Users/me/.lark-channel-workspaces/claude/default"
  }
}

bridge 会检查所选目录存在、是目录，并且不是 /、Home 根、系统目录或临时目录根这类范围过大的位置。工作目录只是 agent run 的当前目录，不是文件系统 sandbox；agent 实际能访问哪些文件仍取决于本机 agent 进程及其权限模式。

多用户工作空间

默认开启（Phase 3 起）。每个飞书用户（按 open_id 识别）在 workspaceRoot 下有一个独立的工作目录，目录名是用户的 open_id（全局唯一且不可变），不同用户的工作区、会话互不共享。用户第一次发言时自动注册并创建目录，之后会用真实姓名问候。

每个用户目录下维护一份独立的多用户 CLAUDE.md 区段（<!-- multi-user-managed-start/end --> 标记内），包含用户信息、工作目录和长期记忆约定（CC-Memory/）。该区段与 /add-repo 的 bridge 管理区段互不干扰。

关闭隔离、退回旧的共享工作区模式：

{
  "multiUser": {
    "enabled": false
  }
}

仓库管理（/add-repo）

/add-repo 把本地路径或 Git 仓库注册进当前工作区，入口追加到工作区 CLAUDE.md 的 bridge 管理区段（<!-- bridge-managed-start/end -->），agent 读 CLAUDE.md 时就能看到这些仓库。CLAUDE.md 中标记区段之外的内容是用户手写的，bridge 永不改动。

• /add-repo：打开交互式表单卡片填写，支持多行批量添加（最多 5 行）。每行填仓库路径或 Git URL（可选加描述）——本地路径会以 symlink 挂进工作区，Git URL 会 git clone。
• /add-repo list：列出工作区已注册的仓库。
• /add-repo remove：打开移除卡片，从 CLAUDE.md 删除仓库入口，并同步清理工作区里的磁盘产物——软链接只删链接本身（源目录保留），git clone 的目录会被删除，确保之后能重新添加同一仓库（否则残留目录会让 git clone 以 code 128 失败）。
• 添加统一走卡片：命令后直接带路径 / URL 不再快速添加，会打开卡片并把输入预填到第一行，确认后才生效。

权限模式

推荐给用户配置的是 permissions.defaultAccess 和 permissions.maxAccess。新 profile 默认两项都是 full，以保持 bridge 的本地工具、授权流程、文件写入等能力完整可用。如需收紧权限，可以改成 workspace 或 read-only；收紧后本地工具执行、登录 / 授权流程、文件写入等能力可能受限。

下面只是 profile 里的字段片段，不要整段覆盖 config.json；请改对应 profile 下的 permissions 字段。

{
  "permissions": {
    "defaultAccess": "full",
    "maxAccess": "full"
  }
}

模式映射：

旧版 sandbox 字段仍可读取。bridge 保存 profile 后，会把该设置迁移为 canonical permissions。

敏感信息过滤

默认开启。在把 agent 的最终回复发给飞书之前，bridge 会对文本做一次密钥脱敏：匹配到常见密钥模式的内容替换为 ***REDACTED***。这是最后一道防线——本机 agent 子进程可能从文件 / 环境变量 / 记忆里读到密钥并回显到回复里。

默认规则覆盖 Anthropic API key（sk-ant-*）、OpenAI key、GitHub token、AWS Access Key、Bearer / Basic 认证头等。自定义规则用 filters.sensitive.rules 配置（name / pattern / replacement?），无效的正则会被忽略并告警。完全关闭：

{
  "filters": {
    "sensitive": {
      "enabled": false
    }
  }
}

数据目录

设置 LARK_CHANNEL_HOME=/path/to/state 可以迁移整棵本地状态目录。LARK_CHANNEL_LOG_DAYS 可以调整日志保留天数。CODEM_HOME 同理，但它只影响 CodeM 后端，且必须指向运行 bot 的那个用户能读到的 CodeM 目录。

访问控制

聊天访问默认是私有的：开箱即用时，只有"你"能在私聊和群聊里用这个 bot。 这里的"你" = 创建 / 拥有这个飞书应用的人（也就是扫码把 bot 建起来的那位）。bot 会自动从飞书查出谁是应用 owner，所以一个人用聊天入口完全不用配置——你私聊它、在任意群里 @它都正常工作，其他人的聊天消息会被静默忽略（bot 不会回"你没权限"，免得暴露自己的存在）。云文档评论按文档权限生效，见下文。

想让别的同事或某些群也能用，就把他们加进下面三类名单：

/invite、/remove 这些命令只有你（创建者）和管理员能发。命令里 @ 的是对方（不是 @ bot），bot 会自动把 @ 解析成对应的人，你不用手动去找 ID。

两种"畅通无阻"的身份

• 你（创建者）：不受任何名单限制——私聊、任意群、所有命令都能用，而且永远锁不死自己：哪怕名单配乱了，回到 bot 私聊发 /config 总能进来。在飞书后台把应用 owner 转给别人后，bot 也会自动跟着切换。
• 管理员：能私聊、能用 /config 等管理命令，而且不受"响应的群"名单限制——无论群在不在名单里，bot 都会回他们。适合给一起维护 bot 的同事。

几种常见配置

• 只给自己用 → 什么都不用做，默认就是。
• 让某个同事能私聊 bot → /invite user @他
• 让某个工作群里所有人都能用 → 在那个群里发 /invite group
• 第一次配，想把 bot 已经在的群一次性全开放 → 发 /invite all group 一键拉取 bot 所在的全部群加入名单，之后再用 /remove group 删掉不想要的
• 再拉个人一起当管理员 → /invite admin @他

还需要知道的

• 改完下一条消息就生效，不用重启。
• 群里默认要先 @bot 才会回（私聊不用 @）。这是另一个独立开关（/config →"群里需要 @ bot"），和上面的名单是两回事。
• 陌生人发消息一律静默丢弃，不会有任何回复。唯一的例外：有人在一个还没开放的群里 @bot，bot 会回一句友好提示，告诉他可以让管理员发 /invite group 开放这个群。
• 云文档评论按文档权限生效：能在支持的文档里评论并 @bot 的人可以触发回复。

高级：直接改配置文件

不想在飞书里点的话，/invite、/config 背后写的是 ~/.lark-channel/config.json 中对应 profile 的 access 字段。空白名单表示这个名单没人，不表示所有人都能用。下面只是 profile 里的字段片段，不要整段覆盖 config.json：

{
  "schemaVersion": 2,
  "profiles": {
    "claude": {
      "agentKind": "claude",
      "access": {
        "allowedUsers": ["ou_xxxxxxxxxxxxx"],
        "allowedChats": ["oc_xxxxxxxxxxxxx"],
        "admins": ["ou_xxxxxxxxxxxxx"],
        "requireMentionInGroup": true
      }
    }
  }
}

allowedUsers / admins 填用户 open_id，allowedChats 填群 chat_id。手动找 ID 最简单的办法：让对方给 bot 发条消息（群里就 @ 它一下），然后看当前 profile 的日志：

grep '"event":"enter"' ~/.lark-channel/profiles/<profile>/logs/bridge-$(date +%Y%m%d).jsonl | tail -5

每行都带 chatId（群 / 私聊 ID）和 senderId（用户 open_id）。手改完后重启 bridge，或在允许的 admin 上下文里发 /reconnect 让它生效。日常调整还是 /invite / /config 更省事，直接改文件主要用于部署脚本预填。

云文档评论

云文档评论不再需要单独绑定工作目录或维护文档白名单。支持的文档评论里 @bot 后，bridge 会在同一个评论线程里回复。评论运行复用文档级 session key；没有记录过文档 cwd 时回退到用户 home 目录。

常见问题

bot 没反应 / agent 不回复：通常是本机 claude、codex 或 codem CLI 没登录，或者当前会话指向了不存在的工作目录。发 /status 看当前状态；/new 重开会话往往就好。

用 CodeM 时报「未找到本地 CodeM」或「未登录」：先确认 bot 的运行用户和执行 codem login 的是同一个用户，且 $CODEM_HOME 指向该用户的 CodeM 目录（默认 ~/.codem）。用别的用户跑是最常见的坑——bridge 会读不到凭据，或写出错误属主的产物。发 /doctor 看具体是哪一项。

CodeM 的 token 显示临期：1 小时的访问 token 由 launcher 每次运行时自动续期，临期只是告警，不用管。只有 refresh token 过期才需要重新 codem login。

agent 子进程假死（卡片停在最后一帧不动）：支持 idle 探活。agent 一段时间没输出就会被 SIGTERM kill，卡片末尾会标出自动终止原因。默认关闭。开启方式：/config 设全局值（分钟），或 /timeout 10 只对当前会话生效；/timeout off 关掉当前会话的探活；/timeout default 清掉会话覆盖，回退到全局设置。

图片发过去 agent 说看不到：升级到最新版，0.1.0 之前的版本有文件名去重 bug。

测试与 CI

本地检查：

pnpm test
pnpm typecheck
pnpm build

pnpm test 包含 unit、integration 和 process-level adapter 测试。CI 在 macOS、Ubuntu、Windows 上执行 pnpm install --frozen-lockfile、pnpm test、pnpm typecheck 和 pnpm build。

可选：遥测（Telemetry）

默认情况下 bridge 不上报任何数据：没有指标、没有日志离开你的机器，也不引入任何遥测依赖。下面这个钩子在你主动开启前完全是空操作。

想接自己的监控时，用环境变量指向一个 default export（或导出 createAdapter）AdapterFactory 的模块：

LARK_CHANNEL_TELEMETRY_MODULE=your-telemetry-package coderover start

该模块会收到每一条 log.* 事件，以及错误 / 指标钩子，转发到任何你想要的地方。接口从包根导出：

import type { AdapterFactory, TelemetryAdapter, TelemetryEvent } from 'coderover';

const createAdapter: AdapterFactory = (meta) => ({
  emit(event) {/* 上报事件 */},
  recordError(err, ctx) {/* 上报异常 */},
  recordMetric(name, value, tags) {/* 上报指标 */},
  flush(timeoutMs) {/* 冲刷缓冲事件 */},
});
export default createAdapter;

模块不存在、工厂函数不合法、或者 adapter 抛错，都会降级为空操作——遥测永远不会阻止 bridge 启动，也不会打断日志。