12.2 常见问题 · BANZ 文档

按你遇到的情况查办法：装不上、登录不了，看“安装和登录”；工作台右上角出现提示图标，看“右上角的提示”；会话出了错，看输入框下方的状态，对照“会话出错”。

安装和登录

问题	怎么办
没有注册码，或注册码过期了	注册要用注册码，找管理员要一个新的（见 1.2 注册与登录）
收不到邮箱验证码	先看垃圾邮件；60 秒后可以重发（见 1.2 注册与登录）
macOS 提示应用“已损坏”或无法打开	手动下载的应用要先在终端执行一次 `xattr -dr com.apple.quarantine /Applications/banz.app`（见 1.1 安装）
终端里找不到 `banz` 命令	一行命令把 `banz` 放在 `~/.local/bin`，把这个文件夹加进 PATH 后重新打开终端（见 1.1 安装）
Ubuntu 24.04 上用一行命令装的桌面应用打不开	改用 .deb 安装（见 1.1 安装）
恢复码和验证器都丢了	请管理员核实身份后重置第二因素，下次登录时重新设置

工作台出问题时，窗口右上角会出现一个带 ✕ 的圆形图标。鼠标停在上面会显示提示，格式是“说明 — 下一步”，比如“本主机未登录 — 登录”。点一下图标就执行下一步。

提示里的“主机”指你电脑上在后台运行的 banz。

提示	怎么办
本主机未登录	点提示登录（见 1.2 注册与登录）
服务器不再接受本主机的登录	重新登录。可能是改了密码、设备被吊销，或登录过期
你的另一台设备断开了本设备	点提示在这里重新连接，或执行 `banz device reconnect`
本机的 banz 与账号服务器版本不兼容	更新 banz（`banz update apply`，见 1.4 更新与卸载）

主机已重启时，除了右上角的图标，页面上方还会出现横幅：在终端运行 banz web 重新打开此页。横幅上有“复制命令”按钮。

下面几条只在命令行里出现，工作台里看不到：

提示	怎么办
本设备的主机没有响应	稍候，会自动重试；或启动它：运行 `banz web`，或在前台运行 `banz serve`
无法连接服务器：你看到的是本主机的副本，写入需等服务器恢复	检查网络，稍候；或运行 `banz sync now` 立即同步
无法连接服务器，本主机也没有保存副本可供查看	稍候

工作台和服务器的连接断开时，右上角会显示“正在重新连接服务器…”，页面上的内容停在断开前，连上后它自己消失。一分钟后还没连上，会变成“连不上服务器”，banz 会继续自动重试，点一下立即重试。这段时间里发消息等写入不会发出，会提示“没有发出：正在重新连接服务器”，连上后再试一次。

输入框下方的状态写明了原因：

状态	原因和办法
出错：还没登录	agent 程序自己没登录。在终端运行一次 `claude` 或 `codex` 登录
出错：凭据被拒绝	agent 程序的账号或密钥有问题，检查它的登录或配置档
出错：连不上网关	连不上模型服务（网关），多半是网络或代理问题，检查本机能否访问模型服务
出错：模型不可用	换一个模型（见 3.3 模型、思考强度、模式与指令）
出错：上下文已满	用 `/compact` 压缩上下文，或 `/clear` 开始新对话
出错：达到用量上限	agent 程序的额度用完了，等额度恢复或换账号
出错：被安全分类器拒绝	模型服务拒绝了这次请求，换个说法，或换个模型
出错：运行失败	其他原因。用 `banz session diagnostics 会话ID` 看细节（见 12.1 体检与日志）
就绪 · 上一轮失败：…	上一轮出了错，会话本身还能用，直接发下一条消息即可
停止未确认（已过 … 秒）	agent 程序没有及时响应停止，可以在会话的右键菜单里点“关闭运行”
设备离线	会话所在的电脑没开或没联网，等它上线

新建 agent 时 agent 程序是灰的，或体检显示“在搜索路径中找不到 claude”：

体检会提示“请在某文件夹腾出空间”。banz 的数据在数据文件夹里（位置见“状态与关于”的“数据目录”）；会话的 worktree 也在那里，设置的“智能体与会话”里可以调小“保留的 worktree”数量。

把 banz host doctor 和 banz host logs --level warn 的输出，以及出问题的会话 ID 发给你们组织的管理员。发之前先检查里面有没有密码或密钥。