故障排查

常见问题、日志位置与启动开关。

Markdown 原文

出问题先看两处：日志和 启动参数。大多数问题都能在日志里定位。

日志在哪

场景	位置
托盘模式（默认）	`.bi/logs/web.log`（每次启动覆盖，历史不留）
控制台模式	终端输出
权限审批记录	`.bi/permissions.log`（每次工具调用的完整参数，JSONL）
网络活动记录	`.bi/logs/network/*.jsonl`（需开启 `network_log_enabled`）

启动开关与环境变量

开关	作用
`-no-tray`	禁用系统托盘，回到控制台模式（测试 / 无人值守 / 排障用）
`-dedupe-sessions`	清理重复与空会话后退出；默认只预览，加 `-apply` 才真正写库
`BI_NO_TRAY=1`	同 `-no-tray`
`PORT`	覆盖 `config.json` 里的端口

常见问题

端口被占用

服务启动时会自动尝试结束占用监听端口的外来进程（Windows 下用 netstat 判断）。如果启动仍失败，检查：

是否已有另一个 Bi 实例在运行
防火墙是否放行
手动换端口：改 config.json 的 port，或设 PORT 环境变量

界面打开了但页面是旧的

前端是单文件内联且随版本变化，请求带 Cache-Control: no-cache。若仍看到旧界面，硬刷新（Ctrl+Shift+R）一次。

中文乱码

终端面板输出会做 GBK→UTF-8 转换，一般不会乱码；乱码多出现在 Windows 控制台直接跑命令时，与代码页有关
命令输出进入上下文经过同样的转换

智能体不执行命令 / 卡在确认

默认情况下每次工具调用都要你确认。如果没有任何弹窗：

检查 permissions.json 是否把 enabled 设成了 false（那样整套审批机制关闭）
检查 disabled_tools 是否把对应工具关了
检查拦截规则是否把命令拦下了（[INTERCEPTED] 前缀会作为工具结果返回）

模型报错

固定模型模式（default: "<providerID>/<modelID>"）下不做故障转移，换到 auto 才有重试
auto 模式一旦开始输出 token 就不切换——错误会抛给上层，但下一轮会重新发起
401/429/5xx 会进入冷却（默认 120 秒），冷却中该模型不参与候选

会话不见了 / 消息丢失

会话数据在 .bi/bi.db，别删这个文件
-dedupe-sessions 会清理重复与空会话，运行前先预览输出确认影响面
导出功能：POST /api/user/sessions/{id}/export 会把会话写成工作区里的 Markdown

磁盘占用异常大

.bi/checkpoints/ 是「退回到这一步」的工作区影子 Git 仓库，随对话增长；每个快照包含工作区全量文件（含被忽略目录之外的内容）。清理方式：

确认不再需要旧检查点后，删除 .bi/checkpoints/ 下对应会话的快照
想控制体积，把大目录放进 fileutil 的忽略列表，避免它们进入快照

还是没解决

带着以下信息排查：

.bi/logs/web.log 的相关片段
bi --version 输出
复现步骤（哪一步触发的）
配置摘要（base_url、model、workspace，注意不要贴密钥）