Wiki AI

常见问题与踩坑

13分钟阅读

官方 FAQ 与社区高频踩坑的合并提炼，按主题归类。遇到「装完 / 升级后行为异常」先扫已知坑，多数不是新问题。

1. 机器人不回复（最高频）：按症状对号

症状大概率根因
完全没反应（连表情都没有）事件订阅 / 发版 / 长连接没通
只有 owner 能触发，别人 @ 弹授权卡 / 不回只配了操作权，没配对话权
群里必须 @ 才回 / 想免 @ 自动回群 @ 策略
🟡「工作中」但结果没发出来（终端有输出）模型没调 botmux send（codex-app 例外，自动转发）
会话起不来 / 首条消息报 zsh: parse error登录 shell 启动文件里有跳转逻辑

A. 完全收不到消息，按顺序自查：

  1. 事件订阅：开放平台应订阅 im.message.receive_v1 + card.action.trigger，方式为「长连接 (WebSocket)」，且 daemon 在跑；
  2. 机器人能力已开通；
  3. 应用创建并发布过版本——改完权限 / 事件必须重新发版才生效；
  4. 长连接独占：Bot 没被别的应用同时抢（两应用抢长连接表现为时好时坏）；
  5. 在干净 shell 里 botmux restart。

B. 别人不能用：对话权 / 操作权分层见第 6 节。给 bot 配 allowedChatGroups（群全员可对话）或 /grant 授权指定群；群 @ 策略可配话题内免 @ / 全群免 @；「1 人 + 1 bot」的 1v1 群本就免 @。每工单一个新群、全员免 @ 的 oncall 场景见 oncall。

C. 终端有输出但没发飞书：仅针对需显式发送的终端 CLI（Claude Code / Codex CLI / Gemini / CoCo 等）——stdout ≠ 已发飞书，必须显式执行 botmux send（带 --mention-back / --mention / --no-mention 之一），多行用 heredoc 别写 "a\nb"。例外 codex-app：最终 assistant message 由 botmux 自动转发，常规回复不要调 botmux send（否则重复发送），仅中途推送 / 发附件 / 跨 bot @ 时用。相关模型侧坑：弱模型 / 套壳模型容易忘调或重复调用（用 SOTA 模型或加硬约束）；无持久 system prompt 的 CLI（CoCo / Codex / Gemini / OpenCode）上下文压缩后会丢 routing 块，新版已对每条 follow-up 重注入。

2. 应用创建与权限（最常见坑）

  • 复用旧应用 / 未走最新 setup / 权限不全：症状五花八门（CLI 像中途退出、收不到消息、botmux history 报 400），根因多是机器人权限不全。→ 用最新版 botmux setup 扫码重新创建应用（自动配齐全部权限并发版），创建流程见 setup-flow。
  • botmux history 400：机器人权限缺失（如缺 im:message.group_msg）→ 权限 JSON 全开。
  • botmux history 411：飞书网关对带空 body 的 GET 更严格，旧版 SDK 给 GET 带 {} body 触发 → 升级新版已修。

3. 环境与安装

  • Node 太老：v18 等没内置全局 fetch，botmux setup 报 fetch is not defined 且不写 bots.json → 升级 Node ≥ 22。
  • 首次启动卡人工确认：CLI（如 Claude Code）首次「信任目录 / bypass 权限」需人工点一次，否则卡住并报 tmux send-keys 错。
  • 截图中文 / emoji 是方块：缺 CJK 字体。Debian / Ubuntu daemon 尝试自动装 fonts-noto-cjk fonts-noto-color-emoji（需免密 sudo 或 root）；其它 Linux 手动装 Noto 字体后重启 daemon。
  • Windows：原生未验证，WSL2 应该问题不大。

macOS：claude 报 Please run /login 的双存储分裂

claude 登录 token 有 keychain（条目 Claude Code-credentials）与文件（~/.claude/.credentials.json）双存储：GUI 跑 claude 和 botmux 默认（非隔离）配置走 keychain；SSH 里跑 /login 只写文件。只要 keychain 条目存在就只读 keychain，于是出现「SSH /login 成功了、GUI / 非隔离 bot 却仍报 /login」；叠加 refresh token 轮换，谁先刷就把对方的 token 作废。推荐收敛到文件单一源：禁止在 GUI 下用 claude code；统一 SSH 跑 /login 更新 token；删掉 keychain 残留旧条目。若是模型网关侧 403 则与飞书授权无关，多为环境变量问题（见第 4 节）。

4. 环境变量丢失（高频）

  • bash 用户把变量写在 .bash_profile 拿不到：新 worker 用 bash -i 启动，只读 .bashrc → 在 .bashrc 里 source ~/.bash_profile，或直接写进 .bashrc（zsh 用户写 .zshrc）。这是 API Error 403 / 网关 token 报错的常见根因。机制见 env。
  • root 下 Claude 拒绝 --dangerously-skip-permissions：报 “cannot be used with root/sudo privileges” → export IS_SANDBOX=1（PM2 / systemd / Docker 配在对应启动环境）；新版已自动对 root 场景注入。

5. 会话起不来：zsh: parse error near '\n'

登录 shell 启动文件里有「切到另一个 shell」的逻辑（典型是 ~/.bashrc 里 if [ -t 1 ]; then exec zsh; fi）。botmux 在 tmux 里用 <$SHELL> -i -c '…' 拉起会话，-i 会 source 启动文件，exec zsh 把 shell 顶替掉，真正启动 CLI 的命令没机会执行——pane 停在空 shell，首条消息打进去就报 parse error。v2.95.0 起 botmux 会检测并发诊断卡。修复二选一：

  • 配 launchShell（推荐）：/config launchShell zsh，或 Dashboard「机器人默认设置 → 启动 Shell」，或 bots.json 加 "launchShell": "zsh"；PATH / nvm 等要放进所选 shell 的启动文件。
  • 给启动文件的跳转加守卫：[ -z "$BASH_EXECUTION_STRING" ] && [ -t 1 ] && exec zsh，仅手动开终端时才切换。

改完 botmux restart 重发消息。仅 tmux / zellij 后端涉及；pty 后端直接启动 CLI 不受影响。

6. 权限与群使用

  • 三层权限：allowedChatGroups / globalGrants 给对话权（群内全员可问）；allowedUsers 给操作权（/cd /restart /close、卡片按钮）。配了 allowedChatGroups 时 allowedUsers 至少要有一个 owner。
  • 机器人拉进新群能看之前的聊天记录：能，直接说「看下历史聊天」或引用消息即可，前提是机器人权限开全（含群消息读取）。
  • 普通群改话题群：需群主 / 管理员操作：群设置 → 群管理 → 群消息形式 → 「话题消息」；机器人不能替群改设置。
  • 运行中会话追问 / 打断：默认不打断当前轮，新消息排队（type-ahead），本轮结束依次输入；想立即纠偏先在卡片 / Web 终端点 Esc 打断。CoCo 的 type-ahead 依赖 CoCo ≥ 0.120.32（低版本忙时发消息会丢）。

7. 工作目录与仓库选择

  • workingDir 从该目录向下找 git 仓库（最多 3 层），不向上扫；指向集合根（如 ~/projects）列全部，指向单仓库只列该仓库（含 worktree）；别设成 ~，遍历太多。
  • 临时切目录用 /cd <path>；defaultWorkingDir 跳过选仓库卡片直连——副作用是每发一句起一个新 session，不想要就删掉该配置。
  • /repo 编号会漂移，自动化别写死编号，用 /repo <项目名> 或路径指定。

8. 进程与连接

  • daemon 重启丢上下文吗：装 tmux 就不会——CLI 常驻 tmux session，botmux restart 后下一条消息自动 re-attach，无需 --resume。没装 tmux 不会自动降级 pty，而是硬拦截弹卡让装 tmux；只有显式 BACKEND_TYPE=pty（或 per-bot backendType: "pty"）才用 pty，且 pty 会话不跨 daemon 重启存活。见 tmux。
  • 会话不关会一直跑，目前无空闲 TTL 自动回收：用 /close、Dashboard 批量关、botmux delete stopped / all 清理。
  • tmux kill-session 后又被拉起：daemon 仍认为 active → 走 botmux delete。
  • Codex 0.131+ headless 报 desktop attach socket 错：features.apps 默认开启去连 desktop → botmux 已对其拉起的 Codex 加 --disable apps 规避。
  • 在 botmux 自己的 tmux pane 里 botmux restart：运行时变量（TMUX / LARK_* / BOTMUX_*）被继承污染进 daemon，引发偶发 token / 网关报错 → 在干净的非 tmux shell 里重启。
  • tmux-server-*.log 撑爆磁盘：仅 tmux -v / -vv 启动才产生，无自动轮转，长跑能涨到上百 GB；botmux 自身从不带 -v，该文件可安全清理。

9. 自定义 wrapper / 网关

  • ccr / 自定义网关 / wrapper 可用：写一个把 "$@" 透传的 wrapper 脚本，在 botmux setup 编辑机器人时把 cliPathOverride 配成该脚本路径。
  • wrapper 没透传参数：CLI 拿不到 --session-id 等 → botmux logs 找 Spawning fresh CLI: 行，复制完整命令本地复现定位。
  • wrapper 把 botmux 参数加进黑名单：如屏蔽 --settings、报 unknown option '--images'，导致启动失败掉进 shell → 本地手动跑 spawn 命令定位，放行相关参数。

10. 输入与协作

  • 多行消息被拆成多条提交：部分 TUI（Codex / CoCo）把 \n / \t 当 Enter / 补全键；新版已把 Codex 输入改成 bracketed paste 规避（与 CoCo 一致）。自己写 botmux send 多行务必用 heredoc。
  • botmux send --images ≥ 6 张可能 silent fail → 一次 ≤ 4 张、分批发。
  • 两个 bot 互相 @ 死循环：通常一方主动停即解；本质是模型多嘴行为，加约束。协作机制见 multi-bot。

11. Dashboard 与安全

  • 别把带 token 的 dashboard URL 发到群里（等于公开临时访问凭证）；安全敏感场景把 host 绑本机：BOTMUX_DASHBOARD_HOST=127.0.0.1。
  • token 是轮换式而非单次消费：轮换前同一 URL 可重复使用；只有 botmux dashboard rotate 生成新 token 并让旧链接立即失效，裸命令和 botmux dashboard current 都不轮换。
  • dashboard 打不开：先 curl http://<host>:<port>/__health，返回 {"ok":true} 说明服务正常；问题多在浏览器代理 / host 变化（mac 连内网 IP 会变）/ 打开了旧 token 链接。见 dashboard。

12. 其它

  • Lark 国际版（larksuite.com）：支持。扫码建应用自动识别租户类型并记住；手动粘 AppID / Secret 时选一次。每个机器人按所属版本独立连对应域名，同一台机器可同时跑飞书和 Lark 机器人，凭证按应用隔离。
  • 升级：botmux upgrade；会话内的 botmux wrapper 版本始终与 daemon 一致，无需单独升级。

排查通用手法

任何「本机起不来 / 行为异常」先走三步：

  1. botmux logs 找 Spawning fresh CLI: 行，复制完整命令本地手动跑一遍复现（最快定位权限 / 参数 / 登录态问题）；
  2. 进 Web 终端一眼看模型 / 网关的真实报错，见 web-terminal；
  3. 把现象丢给本机 agent 让它自查。

配置层面的推荐姿势（专用 Devbox、角色边界、多 bot 互审等）见 best-practices。

关系图谱

反向链接