---
title: "故障排查"
description: "常见问题、日志位置与启动开关。"
---

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

## 日志在哪

| 场景 | 位置 |
| --- | --- |
| 托盘模式（默认） | `.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`，注意不要贴密钥）