常见问题 FAQ

macOS / Windows 均可注册成后台服务、开机或登录自启、崩溃自动拉起。

「项目内只读 / 项目内读写」两档权限由 OS 沙箱强制。详见安全与权限。

都支持。项目定位就是把飞书 / Lark 桥接到你本机的 Codex 或 Claude Code。

Bridge 本身开源免费，MIT 协议。

你需要自备 AI 后端的使用资格：登录好的 Codex CLI 或 Claude Code——它们各自的账号 / 订阅费用由对应服务商收取，与 Bridge 无关。

最大区别是执行位置：Bridge 的 agent 跑在你自己的电脑上，在群绑定的本地目录里真实读写文件、跑命令，代码不用上传给任何第三方托管服务；推理、命令、改动、结果以流式卡片回到群里。

它不是多租户托管服务，而是给你（和你信任的小团队）自用的桥——机器、目录、权限档都在你手里。

能。只要本机的 Bridge 服务在跑（后台 daemon 常驻），你就可以在手机飞书里远程发起任务、看流式卡片、随时点 ⏹ 终止。

「☕ 咖啡一下」反向桥还能把本机正在跑的 Claude Code / Codex 的「需要审批 / 提问 / 任务完成」推到你的手机私聊，点一下它就继续跑。

产品品牌名为 feishu-agent-bridge；正式 npm 包名为 @modelzen/feishu-codex-bridge，CLI 命令为 feishu-codex-bridge。

安装时请认准：npm i -g @modelzen/feishu-codex-bridge。

Codex：默认后端，具备完整的 /goal、/compact、/resume、/context、新消息引导 / 排队能力，以及更细的项目沙箱边界。

Claude Code：SDK 随桥内置、复用本机 claude 登录态（首次按需下载约 265MB），流式消息、工具调用、/goal / /compact / /resume / /context 同样支持。

建项目时按需选，同一台机器可以混用；Codex 群和 Claude 群可以同时存在，互不影响。

每张运行卡片上都有 ⏹，点一下立刻终止当前轮；/goal 模式的运行卡上还有「🎯 结束目标」（本轮跑完停）。

卡死的会话有 watchdog 自动回收，异常不波及其他群。要停整个 Bridge 服务：feishu-codex-bridge stop。

所有本地状态都在 ~/.feishu-codex-bridge/（机器人配置、项目 / 会话注册表、AES-256-GCM 加密的密钥库）。

npm uninstall -g @modelzen/feishu-codex-bridge 卸掉命令，再删掉上面这个目录即可清干净。

Bridge 通过 codex app-server 子命令驱动 Codex——这个子命令只有 Codex CLI（npm i -g @openai/codex）才有：

• 桌面版（GUI 应用）完全不受 Bridge 控制，两者互不干涉，可以共用同一份 ~/.codex/auth.json 登录态；
• 如果两个安装互相抢 codex 命令名（典型现象：控制台点「启动」后桌面反复闪出黑框又消失），用环境变量 CODEX_BIN 指定 CLI 可执行文件的完整路径即可，Bridge 只读这个变量；
• 注意：无论项目选 Codex 还是 Claude 后端，Codex CLI 都是 Bridge 运行的硬依赖，必须先装好并登录。

个别环境下和 npm 的安装方式有关：后台服务（daemon）运行时 PATH 很精简，如果 npm 是用 Homebrew / nvm / fnm / Volta 装的，daemon 可能找不到它，点更新就会失败（Node 官方安装包装的 npm 一般没这个问题）。三种解决办法：

1. 给 launchd 补 PATH（macOS）：sudo launchctl setenv PATH "<npm所在目录>:/usr/local/bin:/usr/bin:/bin"，然后 feishu-codex-bridge restart，一劳永逸；
2. 前台更新：feishu-codex-bridge stop && feishu-codex-bridge update && feishu-codex-bridge start；
3. 手动更新：终端执行 npm i -g @modelzen/feishu-codex-bridge@latest 再 feishu-codex-bridge restart，效果和点按钮一样。

两种方式任选：

• 点按钮：私聊机器人 → 控制台菜单「⬆️ 版本更新」，一键升级；
• 命令行：feishu-codex-bridge update（等价于用 npm 装最新版并自动重启服务），完成后 feishu-codex-bridge --version 确认版本号。

Windows 上如果提示命令找不到，试试 feishu-codex-bridge.cmd（支持 Tab 补全）。

项目名称随便起，只是给自己看的标签——机器人会用它自动建一个飞书群并把你拉进去（也可以把机器人拉进已有群）。之后的使用全在群里：

• 直接在群里 @ 机器人 + 你想做的事（比如「帮我写个脚本，统计目录里 CSV 的行数」），它就开始执行；
• 对某条消息「开话题」，话题内可以免 @ 连续聊；
• 图片、文件直接发给它就能读；输出太长或想改主意，点卡片上的 ⏹ 终止。

两种群模式在创建项目时选定：

• 👥 多话题群：主群区 @ 机器人开新话题，每个话题是一条独立会话——上下文隔离、可并行，支持 /resume，适合多人协作或一人并行多任务；
• 💬 单会话群：整个群是一条连续会话，全程免 @，适合个人单线深入。

创建多话题群只有一条正规路径：私聊机器人 → 「新建项目」→ 填表单 → 点「👥 创建·多话题群」。在群里 @ 机器人让 Codex 自己建群是建不出来的——Codex 没有权限调用飞书 API 建群。

• /context —— 查看当前会话上下文占用比例和已用 token；
• /compact —— 手动压缩上下文；占用到 70% / 85% / 95% 档位时卡片脚注会提示，95% 以上还会自动压缩（可在设置里关闭自动压缩）；
• /goal <目标描述> —— 启动长时程自治目标，围绕目标多轮推进到完成，运行卡带「⏹ 终止」和「🎯 结束目标」；
• /resume —— 恢复历史会话（多话题群、管理员可用，在主群区 @ 机器人发送）；
• /model、/settings 等，完整清单在群里发 /help 查看。

多话题群里 /context、/compact 在话题内发；单会话群直接发（免 @）。

它是反向桥：把你本机终端里跑的 Claude Code / Codex CLI 的「要审批 / 要你回答 / 任务完成」时刻，推送到你的飞书私聊——离开电脑后在手机上点一下，本地任务接着跑。

• 开启：私聊机器人 → 设置 → 「☕ 咖啡一下」开关，按需勾选接管 Claude Code / Codex CLI；
• 触发：任务运行中你离座（锁屏或键鼠静止约 2 分钟），需要你点头的环节会推卡片到私聊；
• 按钮：「直接回复」= 把你的话作为新指令喂回本地 agent；「✅ 收工」= 结束本次接管；不操作的话超时后自动放行，不会一直卡着。

收文件：可以。群里发的附件会自动下载到 ~/.feishu-codex-bridge/inbound/，绝对路径直接交给 agent 读取分析，不用手动复制内容。注意：

• 读取这个目录需要项目是「⚠️ 完全访问」权限档（只读 / 读写档的沙箱锁在项目目录内）；
• 单文件上限 50MB、单条消息最多 9 个附件，1 小时后自动清理；
• 图片走独立的多模态识图通道，任何权限档都能用。

发文件：agent 回复里的图片会自动上传到飞书渲染；非图片文件暂时只能给出本地路径——可以让它把关键内容截图输出，或在本机直接打开。

能。这是「假死看门狗」，监控的是 agent 多久没有输出（不是任务总时长）——只要还在持续输出工具调用 / 思考，就不会触发。

调整方式：私聊机器人 → 设置 → 「⏱ 假死超时」。默认 120 秒，可选 60 / 120 / 300 / 600 秒，也可以自定义（10–3600 秒）；填 0 完全关闭监控（不建议，真卡死就不会自动回收了）。改完对下一轮立即生效。

不能，这是核心设计：一个群 = 一个项目 = 一个固定工作目录，创建时确定、之后不可改。想覆盖多个目录：

• 为每个目录各建一个项目群，项目之间互不干扰；
• 或者在同一台机器上注册多个机器人（bot init / bot use），每个机器人各管各的项目列表和会话。

不能直接转：群类型和后端一样，都是创建项目时选定、运行中不可更改。想换一种玩法：

• 新建一个项目、把工作目录指向同一个本地路径，新旧群独立运行；
• 一定要复用同一个群的话，把机器人移出群（触发自动解绑）再重新拉进去，绑定时选另一种群类型——注意旧群的会话历史不会带过来。

私聊机器人（需要自己是 owner 或已被加为管理员）→ 「📁 项目列表」→ 选项目 → 「⚙️ 设置」→ 「🔐 权限」，「管理员档」和「普通用户档」分开下拉选择：🔒 项目内只读 / ✏️ 项目内读写 / ⚠️ 完全访问。两档设成不同值时，管理员和普通用户各走独立会话线程，沙箱和对话历史互不相通。

添加 / 移除管理员在同一个设置菜单的「👑 管理员」里；扫码创建机器人的人（owner）默认就是管理员。改完权限后，活跃会话会被驱逐，下次 @ 机器人按新权限重新开始。

管理员 / owner 信息存在本机配置文件里（~/.feishu-codex-bridge/），不在飞书服务端——换电脑后配置是全新的，桥自然认不出你。解决办法：

1. 推荐：把旧电脑的 ~/.feishu-codex-bridge/ 整个目录拷到新电脑同路径，重启桥——项目绑定、会话记录会一并带回；
2. 或在新电脑跑 feishu-codex-bridge web 打开网页控制台（走本地 token 鉴权，不受此限制），在管理员设置里把自己加回去。

建议平时定期备份 ~/.feishu-codex-bridge/，换机直接整体还原。另外不要把同一个机器人的 App ID / Secret 同时配到多个桥实例上，容易互相覆盖身份状态。

沙箱和审批是两层独立机制：

• 沙箱档位（bypass / 只读 / 读写）管「能碰哪里」——文件系统、网络等；
• guardian 审批管「碰之前要不要先问你」——它默认开启，跟沙箱档位无关。

「咖啡一下」接管的正是本机终端里 Codex 自己弹的审批请求，所以沙箱全开也会有卡片。想彻底关掉本机的逐条审批，需要在 Codex CLI 自身配置里关闭 guardian——但 bypass 沙箱 + 免审批意味着它可以无提示执行任何命令，请确保运行环境可控。

通过飞书群发起的任务不受影响：桥统一使用 approvalPolicy: never，从不弹审批卡。

用的是 Anthropic 官方 @anthropic-ai/claude-agent-sdk，不是另起一套配置体系，也不是网页模拟登录：

• 登录态：复用本机 claude login 的凭据；
• 配置：MCP、skills、hooks 都是同一份本地 .claude/ 配置在生效；
• 会话：双向共享——桥里开的话题会出现在终端 claude --resume 列表里，终端里开的会话也会出现在飞书 /resume 里；
• System prompt：Claude Code 原生 preset 完整保留，桥只在末尾追加一小段飞书卡片渲染说明。

差异只有权限模型：通过桥运行时 permissionMode 为 bypassPermissions，靠 OS 沙箱做硬边界，所以不会弹审批提示。

桥本身的实现不会带来额外风险：消息先到本机 bridge，再由 bridge 调用本机官方 CLI / SDK 执行，飞书只是协作入口和卡片层，不是网页模拟登录。

真正要注意的是使用方式：把一个人的个人订阅给团队多人高强度共用，这种模式据观察有被检测的风险。推荐的团队用法是每人用自己的账号，通过桥共享工作流、项目上下文和过程记录，而不是共享订阅额度。