来自社区交流群的高频实战坑，按出现频率与影响排序。
fetch，botmux setup 会报 fetch is not defined / fetch failed 且不写 bots.json。→ 升级到 Node ≥ 22。tmux send-keys ... Enter 报错。→ 卸载 Homebrew tmux，改用系统自带稳定版（如 3.3a）。tmux send-keys 错。→ 首次手动确认一次，之后不再出现。.bash_profile 拿不到：新 worker 用 bash -i 启动，bash -i 只读 .bashrc。→ 在 .bashrc 里 source ~/.bash_profile，或直接把变量写进 .bashrc（zsh 用户写 .zshrc）。这是 API Error 403 / 网关 token 报错的常见根因。--dangerously-skip-permissions：报 "cannot be used with root/sudo privileges"。→ export IS_SANDBOX=1（zsh 写 .zshrc、bash 写 .bashrc；PM2 / systemd / Docker 场景配在对应启动环境）。新版已自动对 root 场景注入。"$@" 正确透传，CLI 拿不到 --session-id 等参数。→ botmux logs 找 Spawning fresh CLI: 那行，复制完整命令本地复现定位。--settings、报 unknown option '--images'，会导致启动失败掉进 shell。→ 本地手动跑那条 spawn 命令定位，放行相关参数。\n、\t 当成 Enter / 补全键，逐行提交。→ 新版已把 Codex 输入改成 bracketed paste 规避（与 CoCo 一致）。自己写 botmux send 多行时也务必用 heredoc。botmux send：容易忘记调用、或一直重复调用停不下来。→ 用 SOTA 模型，或加更硬的 prompt 约束。botmux send --images ≥ 6 张可能 silent fail：→ 一次 ≤ 4 张、分批发。tmux kill-session 后会话又被拉起：daemon 仍认为 active。→ 走 botmux delete。defaultWorkingDir 配了之后每发一句就起新 session：这是"跳过选仓库"的副作用。→ 不想要就删掉该配置。features.apps 默认开启去连 desktop。→ botmux 已对其拉起的 Codex 加 --disable apps 规避。botmux restart：会把运行时变量（TMUX / LARK_* / BOTMUX_*）继承污染进 daemon，引发偶发的 token / 网关报错。→ 在干净的非 tmux shell 里重启 daemon。/repo 仓库编号会漂移：列表加了新仓库后编号偏移。→ 自动化别写死编号，用 /repo <项目名> 或路径唯一指定。tmux-server-*.log 撑爆磁盘：只有用 tmux -v/-vv 启动才会产生，无自动轮转，长跑能涨到上百 GB。botmux 自身从不带 -v，这种文件可安全清理，不影响 botmux 日志。BOTMUX_DASHBOARD_HOST=127.0.0.1。token 一次性，每跑一次 botmux dashboard 重新生成、旧链接立即失效。curl http://<host>:<port>/__health，返回 {"ok":true} 说明服务正常；问题多在浏览器代理 / host 不对（mac 连内网 IP 会变）/ 打开了旧 token 链接。任何「本机起不来 / 行为异常」先走这三步：
botmux logs 找 Spawning fresh CLI: 那行，复制完整命令在本地手动跑一遍复现（最快定位权限 / 参数 / 登录态问题）。