飞书 Bot 突然不说话了怎么办lark-coding-agent-bridge 排查技巧与常见问题 FAQ【免费下载链接】lark-coding-agent-bridgeBot that bridges Feishu/Lark messenger with a local Claude Code or Codex CLI. Streaming cards, per-chat sessions, multiple workspaces项目地址: https://gitcode.com/gh_mirrors/fe/lark-coding-agent-bridgelark-coding-agent-bridge 是一个把飞书 / Lark 与本地 Claude Code 或 Codex CLI 打通的桥接机器人在聊天框里发消息就能调用本地编码智能体回复会以流式卡片实时更新。当你发现飞书 Bot 突然不说话了—— 了没反应、卡片卡在最后一帧、后台服务悄悄退出——本文教你按 4 步快速定位故障并汇总了最常见的常见问题 FAQ 与修复方法。一、先分清问题出在桥接层还是本地 CLIBot 不说话的原因通常只有三类先对号入座能省掉一半排查时间现象最可能的原因优先检查完全无回复私聊/群聊都沉默访问控制未放行、WebSocket 断连、进程没在跑/status、访问白名单有回复但卡在最后一帧本地 agent 子进程卡死/timeout看门狗、/stop报错未找到本地 claude/codex本地 CLI 没装、没登录或路径失效终端手动跑claude --version二、四步排查法 ️第 1 步发/status看当前状态在飞书里直接给 Bot 发/status它会回一张状态卡展示当前 profile、agent 类型、工作目录、会话状态、lark-cli 身份和运行状态。这是最快确认配置是否还是我以为的那套的方式。第 2 步发/doctor做全面体检/doctor会执行一组低敏感度的自动诊断实现在 src/commands/index.ts报告内容包含见 buildDoctorReportself-check / profile / agent桥接自检、当前 profile 与 agent 类型workspace / workspace check工作目录是否存在、是否可用access你当前这条消息是否被访问控制放行denied 时附带原因owner API应用 owner 身份识别状态queue / run executor进程池占用情况、执行器是否可用agent echo check让本地 agent 回复一个OK端到端验证 CLI 链路两个小细节同一用户 30 秒内只能触发一次/doctor在群里发起时诊断结果会私信发给你不会刷屏给群成员。第 3 步翻结构化日志桥接器为每条消息写入 JSONL 结构化日志src/core/logger.ts按天落盘在~/.lark-channel/profiles/profile/logs/bridge-YYYYMMDD.jsonl后台守护进程的日志在~/.lark-channel/profiles/profile/logs/daemon/想确认某个人有没有真的进门可以直接 grep 进入事件README 官方推荐写法grep event:enter ~/.lark-channel/profiles/profile/logs/bridge-$(date %Y%m%d).jsonl | tail -5每行都带chatId和senderId——如果日志里根本没有这条消息的enter事件说明消息压根没进来网络/白名单问题如果进来了却没有run.started问题在桥接内部。第 4 步重启或重连会话层异常发/new重建会话或/cd path切换工作目录会同时重置会话连接层异常发/reconnect强制重建 WebSocket进程层异常宿主机上用lark-channel-bridge status确认服务是否在跑不在就lark-channel-bridge restart三、常见问题 FAQ ❓Q1Bot 完全不响应像消失了一样最常见的三个真凶本地 CLI 没登录。在终端手动跑claude或codex确认能正常交互CLI 未登录时桥接会直接失败。工作目录失效。会话指向的目录被删除/改名后运行无法启动。发/new开新会话或/cd到有效路径。WebSocket 断连。若日志里看到network unreachable那是网络层故障——HTTP 探测都连不上飞书域名时强制重连也没用先修网络。桥接内置了 keepalive 机制每 15 秒独立探活连续 3 次确认 WS 失联才强制重连并能识别笔记本休眠唤醒、避免误判。Q2卡片卡在最后一帧agent 看起来冻结了启用空闲看门狗/config里全局开启或/timeout 10为当前会话设置 10 分钟静默阈值。超时后进程会被杀掉卡片上会标注自动终止原因你再/stop或/new即可恢复。/timeout off关闭会话级设置/timeout default清除会话覆盖。Q3我发的图片 / 文件agent 说看不到升级到最新版本。0.1.0 之前的版本存在附件文件名去重的 bug新版已修复。附件会先下载到本地缓存~/.lark-channel/profiles/profile/media/再交给 agent。Q4别人在群里 了 Bot 却没反应这是设计如此桥接默认私有访问只有应用创建者本人可以使用陌生人的消息会被静默忽略不会回拒绝以免泄露 Bot 存在。想让队友或群组用起来允许某人私聊/invite user 他开放当前群群里发/invite group一键纳入所有已加入的群/invite all group添加管理员可在任意群使用并发管理命令/invite admin 他另外注意群里必须 Bot才会触发私聊不需要all会被忽略。Q5启动时报未找到本地 claude / 不可执行 / 版本检查超时这些来自 preflight 预检 的标准化错误每个都带中文指引和错误码agent-binary-not-found先安装对应 CLI或修正可执行文件路径配置agent-binary-not-executable检查文件权限重装 CLIagent-version-check-timeout--version5 秒内没返回先在终端跑同一命令确认处理原则先在终端里手动把同一命令跑通再重启桥接。Q6多 Bot / 多 profile 场景下某个 Bot 挂了每个 profile 是独立服务独立凭据、会话、工作目录、日志单独重启即可不影响其他 Botlark-channel-bridge status --profile codex lark-channel-bridge restart --profile codex另提醒一点守护进程会记录 bridge CLI 的绝对路径如果当初是通过npx的临时缓存启动的缓存被清理后服务可能失效——请用npm i -g lark-channel-bridge全局安装后再start。四、防患于未然 ✅前台run适合首次配置与调试日常运行改用start交给系统服务托管macOS launchd / Linux systemd / Windows 任务计划用lark-channel-bridge ps查看本地所有桥接进程飞书里也能发/ps日志保留天数默认 30 天可用环境变量LARK_CHANNEL_LOG_DAYS调整整个状态目录可用LARK_CHANNEL_HOME迁移关键数据目录速查见 README.md 的 Data directories 一节五、还是解决不了把/doctor的报告、/status截图和日志片段准备好加入项目反馈群直接问维护者通常能得到最快的答复 本文涉及的核心源码命令与诊断 src/commands/index.ts、连接保活 src/bot/keepalive.ts、本地 CLI 预检 src/agent/preflight.ts、结构化日志 src/core/logger.ts、完整文档 README.md。【免费下载链接】lark-coding-agent-bridgeBot that bridges Feishu/Lark messenger with a local Claude Code or Codex CLI. Streaming cards, per-chat sessions, multiple workspaces项目地址: https://gitcode.com/gh_mirrors/fe/lark-coding-agent-bridge创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考