故障排除

本章按症状组织。每个条目都说明了可能的原因以及修复步骤。先从首先查看：日志、健康状况与应用状态开始——下面几乎每一项诊断都依赖于这三个来源之一——然后跳转到与你所见情况相符的章节。

下文大部分内容基于两个事实。第一，工作区是一个持久化的沙箱：它的系统磁盘（disk.img）和 Linux 主目录（home.img）会在多次启动之间保留，因此仅仅重新启动并不能修复其中的问题。第二，Bromure Agentic Coding 在流量到达虚拟机之前，就已在宿主机上强制执行安全策略——因此看似出现在客户机“内部”的拦截和错误，通常是宿主机代理服务器在起作用，应在应用中而非虚拟机中解决。

首先查看：日志、健康状况与应用状态

在做任何更改之前，先弄清楚应用本身报告了什么。

安全日志

打开 窗口 → 安全日志…。这是宿主机代理服务器发出的每一条安全事件的实时滚动记录：供应链查询与 451 拦截、安装脚本剥离、提示注入检测、凭据交换与泄露警告、Fusion 与路由变更，以及远程访问事件。使用 过滤… 字段可将范围缩小到某个包名、主机或工作区，取消勾选 自动滚动 可在阅读时固定位置。

注意： 安全日志是一个约 5,000 行的内存环形缓冲区，不会在应用重启后保留。如果你需要持久副本——或你正在追查一个会导致应用崩溃的问题——请从终端启动 bromure-cli（见下一节）；每一条日志都会同时镜像到 stderr。

从终端捕获 stderr

应用会将其日志镜像到标准错误输出。从终端启动应用可以获得一份持久的、可复制的记录，即使应用重启或崩溃也不会丢失：

"/Applications/Bromure Agentic Coding.app/Contents/MacOS/bromure-cli" run

若需更深入的细节，可在命令前设置调试变量（参见附录）：

• BROMURE_AC_DEBUG=1 — 为自动化引擎、注入分类器和追踪管线提供带时间戳的调试信息。
• BROMURE_CLI_DEBUG=1 — CLI 命令的控制套接字连接诊断。
• BROMURE_REPAIR_DEBUG=1 — 本地推理修复代理服务器诊断，追加写入 /tmp/bromure-repair.log。

自动化健康检查（GET /health）

应用在运行时会在 ~/Library/Application Support/BromureAC/control.sock 上运行一个仅限所有者访问的控制套接字。你可以通过向它询问健康状况来确认应用处于活动状态并正在响应，它会返回一个小的 JSON 对象：

curl --unix-socket "$HOME/Library/Application Support/BromureAC/control.sock" http://localhost/health

{ "status": "ok", "service": "bromure-ac-automation", "debugEnabled": false }

如果你已开启环回自动化服务器（偏好设置 → 自动化，默认关闭），同一端点也可通过 TCP 在配置的端口上访问——默认为 9223：

curl http://127.0.0.1:9223/health

连接被拒绝意味着应用（或其无界面代理）未在运行；bromure-cli vm ls 会按需启动后台代理，是另一种快速的存活检查。debugEnabled 标志报告 BROMURE_DEBUG_CLAUDE 是否已解锁调试端点。

设置控制台日志

在基础镜像安装过程中，设置窗口有一个折叠的 控制台输出 展开项，用于流式显示原始安装程序日志，并带有一个 复制 按钮。展开它可查看进度，如果你需要将其附加到错误报告中，可复制整份日志。屏幕上只保留最后 100 行，因此请在窗口关闭前复制。

设置与基础镜像安装

在存在 Linux 基础镜像之前，应用无法运行任何工作区。首次启动会显示 欢迎使用 Bromure Agentic Coding 窗口；点击 开始使用 会运行与 bromure-cli init 相同的安装流程。完整流程记录在安装中；本节介绍安装失败时的应对方法。

预构建镜像下载失败或卡住

原因。 首选路径会从 https://dl.bromure.io 下载一个已签名的 gzip 压缩镜像（约 3 GB），验证其 SHA-256，然后解压。网络中断、CDN 故障或校验和不匹配都会使其中止。下载本身最多会重试三次，并在两次尝试之间重新获取目录（每周发布可能会在下载中途删除上一个构建）。

修复。 观察设置窗口中的状态标记和 控制台输出。发生下载端故障时，图形界面会显示一条 镜像下载失败 提示，提供 本地构建 或 取消：

1. 如果你已联网且这是一次暂时性故障，请关闭提示并从应用菜单重试：重新构建基础镜像… → 下载预构建。
2. 如果下载无法成功（网络受限、CDN 被封锁），请选择 本地构建，改为在你的 Mac 上构建镜像（约 10 分钟）。这会生成相同的镜像。
3. 在命令行中，bromure-cli init 会自动回退到本地构建，无需提示。

“基础镜像构建期间出现网络问题”

原因。 本地构建会启动一个一次性的 Alpine 安装程序虚拟机，它需要一个 DHCP 租约和出站访问权限。在某些 VPN 和严格锁定的网络上，它无法获得租约，或其下载因 MTU 不匹配而被黑洞丢弃。

修复。 构建会停止并显示一条 基础镜像构建期间出现网络问题 提示，提供 修复并重试（通过网络修复器重启 macOS 网络守护进程——会要求输入你的管理员密码）或 取消。如果在 VPN 上持续失败，请在重试前钳制客户机网卡的 MTU（WireGuard 类隧道通常需要 1280 或更低）：

defaults write io.bromure.agentic-coding vm.mtu -int 1280

MTU 已默认为 1280；仅在企业 PMTU 路径确有需要时才进一步降低。

安装耗尽磁盘空间

原因。 每次镜像安装都要求存放支持目录的卷上预先至少有 8 GB 可用空间，且构建过程中的监控会在可用空间降至 1 GB 以下时中止（这样 apt/debootstrap 就不会一直重试直到出现无法解释的超时）。

修复。 释放空间后重试。关于哪些内容占用最多，参见磁盘空间。

基础镜像处于部分完成状态

原因。 在安装中途取消，或构建失败，会在支持目录中留下临时文件：base.img.partial、base.img.gz.partial 和 efivars.partial。它们的存在意味着某次安装正在运行或曾被中断。真正的镜像始终是原子性提升的，因此现有可用镜像在整个过程中保持可用。

修复。 重新运行安装直至完成（重新构建基础镜像… 或 bromure-cli init）。若要彻底重新开始，bromure-cli reset 会在确认后删除四个基础镜像产物（base.img、efivars.bin、base.version、image-state.json）——它不会触及你的工作区、缓存的 Alpine 文件或缓存的目录。任何时候都可以用 bromure-cli info 确认已安装的内容，它会打印版本标记、逻辑大小与物理大小以及路径（或“尚无基础镜像”）。

工作区无法启动或恢复

在侧边栏中选择工作区可查看其仪表板：状态标记（关闭、已挂起、运行中）、CPU / 内存 / vCPU / 磁盘 / 运行时长卡片、配置 摘要，以及 启动 或 恢复 按钮。工作区生命周期在工作区中介绍；下面的症状是那些会使虚拟机卡住的情况。

启动无反应，或虚拟机始终无法完成启动

原因。 与浏览器窗格不同，工作区虚拟机不会预热——它们从各自的写时复制磁盘冷启动（或从挂起快照恢复），这需要几秒钟。CLI 连接会在启动过程中等待最多约 60 秒。真正卡住的启动通常意味着客户机文件系统损坏，或有一个客户机无法处理的配置文件。

修复。

1. 给它一些时间，然后查看仪表板上的 CPU 迷你图——一分钟后若仍平稳保持在零，说明它没有取得进展。
2. 从仪表板操作栏原地重启（重启 → 硬重启 会立即拆除它）。
3. 如果它仍无法启动，磁盘本身可能已损坏。从工作区的回滚界面恢复到最近的良好状态，或使用 重置磁盘 从基础镜像重新克隆（这会保留主目录；但会丢弃任何已保存的内存快照和标签页状态）。重置到基础镜像… 是终极手段。
4. 若要修复而非重置，请用 ext4 浏览器检查已停止的磁盘——参见恢复因坏文件而无法启动的工作区。

已挂起的工作区拒绝恢复

原因。 恢复会还原已保存的内存（vm.state）和标签页布局（tabs.json），这需要工作区的持久化机器标识和 MAC。如果工作区的共享文件夹在其挂起期间发生了变化，恢复将不安全。

修复。 当共享发生变化时，应用会询问 放弃“…”的挂起虚拟机？——请选择 放弃并存储；下次启动将干净地冷启动。你的主目录和共享文件夹文件不受影响。请注意，在磁盘被重置或擦除时，已保存的内存快照始终会被丢弃：全新的磁盘搭配旧的内存会立即损坏，因此这是有意为之的设计。

工作区被标记为“已受损”

原因。 代理服务器检测到一次出站尝试，企图将会话凭据泄露给一个并非为其铸造的主机，而你选择了 关闭 或 保存以供调查。工作区被标记 compromised.flag，选择器会为其加上徽章“已受损——启动时将提示擦除磁盘和主目录”。

修复。 下次启动会拒绝引导，直到你确认擦除为止。擦除并启动 会移除磁盘、主目录、内存快照和标签页状态，然后立即引导一个全新的虚拟机——你的令牌、SSH 密钥和工作区设置会被保留。共享项目文件夹位于 Bromure 存储之外，不会被擦除，因此请手动检查它们是否有受污染的文件。完整的检测流程见凭据。

可用磁盘空间不足

原因。 创建任何写时复制克隆或主目录镜像时，如果卷上可用空间少于 1 GB，就会拒绝继续，并以磁盘已满错误快速失败，而不是在会话中途卡死。

修复。 释放空间（参见磁盘空间）后再次尝试 启动。

恢复因坏文件而无法启动的工作区

原因。 写入客户机的一处错误配置——损坏的 /etc/fstab、损坏的 dotfile——可能会在你登录修复之前就使虚拟机无法启动。由于 macOS 无法挂载 ext4，你不能直接在访达中打开该磁盘。

修复。 在工作区虚拟机已停止的情况下，使用内置的用户态 ext4 浏览器：

1. 工作区 菜单 → 打开 ext4 文件…，然后在 ~/Library/Application Support/BromureAC/profiles/ 下选择工作区的 disk.img 或 home.img。
2. 浏览到出问题的文件。右键单击可 预览 或将其 提取… 到你的 Mac 上。
3. 若要就地修补，请点击 启用编辑…（有一条明确警告——切勿编辑正在运行的虚拟机已打开的镜像），然后右键单击 → 用你 Mac 上修正后的副本 替换…。
4. 如果浏览器报告日志需要恢复，请先运行 运行 fsck…（需要 e2fsprogs；如果缺失，应用会建议 brew install e2fsprogs）。

警告： 就地替换仅在新内容能容纳于文件已分配的块内时才有效——增大文件会被拒绝（“该文件需要增大”）。请用它来修复配置和取出文件，而不是添加数据。

“重置磁盘” / “擦除主目录…” 呈灰色不可用

原因。 当工作区的会话窗口打开时，这些破坏性操作会被拒绝。

修复。 先关闭会话窗口（按钮提示写着“请先关闭会话窗口。”），然后重试。

代理身份验证失败

该设计将真实凭据置于虚拟机之外：客户机以占位（“假”）令牌运行，宿主机代理服务器在传输过程中换入真实机密。大多数“身份验证”症状都可追溯到那个边界。完整模型见凭据。

代理——或你——看到一个假的 API 密钥

原因。 这是预期行为。虚拟机内诸如 ANTHROPIC_API_KEY、OPENAI_API_KEY、XAI_API_KEY、GH_TOKEN 以及各 AWS 变量都是刻意设置的诱饵。代理服务器会在宿主机端为允许的目的地替换真实值，因此泄露的假密钥毫无价值。

修复。 无需处理——不要试图在虚拟机内“更正”密钥。如果真实请求在提供商处因身份验证错误而失败，问题出在宿主机上的真实机密：打开工作区的 凭据 窗格并重新输入。一个出现在发往错误主机的请求中的假令牌，会触发受损检测而不是通过身份验证。

订阅登录（通过 Claude / ChatGPT / Grok 注册）停止工作

原因。 在 订阅 身份验证模式下，OAuth 令牌是在一次性注册虚拟机中一次性捕获的，并加密存储在宿主机上（claude-subscription.enc、codex-subscription.enc、grok-subscription.enc）；宿主机负责刷新。如果刷新令牌被吊销、过期，或账户会话结束，宿主机将无法再铸造有效的持有者令牌，请求开始失败。

修复。 重新注册。在工作区的 代理 窗格中，忘记已存储的订阅，并再次运行 通过 Claude / ChatGPT / Grok 注册——这会启动一个全新的一次性虚拟机，捕获新令牌，并将其存储在宿主机端。工作区内的伪造密钥从不改变。

“交换订阅令牌？”反复出现，或被误拒

原因。 这是另一种订阅机制：当代理在虚拟机内用真实令牌登录时，代理服务器会检测到并提议将其移到宿主机，使真实机密离开客户机。该选择会按工作区、按提供商记住。

修复。 在工作区的 追踪 窗格中，Claude 订阅令牌交换 和 Codex 订阅令牌交换 行显示 已激活 或 已拒绝，并带有重置控件——忘记交换（下次会话重新提示） 或 重新启用提示。重置后将在下次会话时再次询问。许可和按会话授予仅存于内存，不会在应用重启后保留。

虚拟机内的 TLS 与证书错误

“self-signed certificate”或“unable to get local issuer certificate”

原因。 所有客户机 HTTPS 流量都被宿主机 MITM 代理服务器拦截，它会用每次安装独立的根 CA 重新签名流量。虚拟机内的工具通过 Bromure 为 node、python、go、rust、curl、deno 和 AWS SDK 设置的 CA 包环境变量来信任它，另外还有暂存到元数据共享中的 CA 文件（bromure-ca.pem）。忽略这些变量的工具——或自带信任库的容器——会拒绝代理服务器的证书。

修复。

1. 对大多数工具而言，无需任何操作。如果某个特定工具失败，请让它指向系统/导出的 CA 包，而不是禁用验证；CA 文件在客户机内可用，且标准的 *_CA_BUNDLE / SSL_CERT_FILE 类变量已经导出。
2. 对于需要访问网络的 Docker 容器，请使用 运行新容器 面板的 继承 HTTP 代理设置 开关，使 http_proxy/https_proxy 得以传播，并在容器工具查找 CA 的位置挂载或安装该 CA。
3. 如果证书错误仅在你删除或轮换 CA（见下文）之后出现，请重新启动受影响的会话，以便重新暂存新的 CA。

轮换根 CA

原因 / 何时执行。 根 CA 私钥位于 ~/Library/Application Support/BromureAC/ca/key.pem（模式 0600），其证书在 cert.pem 中。如果你怀疑密钥已泄露，可能需要轮换它。

修复。 退出应用，删除 ca/ 目录，然后重新启动——会生成一个全新的 CA，并在工作区下次启动时重新暂存。已捕获的现有追踪主体不受影响，但任何固定了旧证书的客户机都需要重新信任新证书。

供应链拦截

当代理的 npm install、pip install 或类似命令因一个独特错误而失败时，最可能是宿主机供应链管线进行了干预。该策略、其各层以及安全日志记录在供应链保护和供应链设置参考中。

安装因 HTTP 451 而失败

原因。 451（“因法律原因不可用”）是 Bromure 的供应链拦截——之所以选它，是为了让它能与护栏使用的 403 一眼区分开。包管理器会在其错误输出中逐字打印原因，例如：

Bromure Supply-Chain Security blocked this request: npm package [email protected]
published 4 hours ago — policy requires 2 days minimum

修复。 阅读原因。常见触发因素及其补救措施：

从安全日志中读取原因

打开 窗口 → 安全日志… 并重新运行安装。各行按颜色编码：蓝色表示出站查询，绿色表示干净的判定，红色表示拦截和失败，橙色表示被剥离的安装脚本，每次某项策略被启用时还有一条强调色的 [supply-chain] 行。一次完全干净的安装仍会为每个产物发出一行“inspecting pkg@ver”——这是刻意的，因此安静的日志意味着“一切已缓存”，而非“代理服务器被绕过”。

覆盖一个拦截

修复。 供应链各层是按工作区的开/关开关，可实时编辑（无需重启虚拟机）。若要放行某个特定包，可在 供应链 窗格中添加一条豁免/允许列表条目，或为该工作区降低/禁用相关层。存储会立即将更改推送到运行中的会话。

每次安装都提示许可（离线，或 socket.dev + Cargo）

原因。 当 OSV 或 socket.dev 已启用但无法给出判定时——网络中断，或生态系统不受支持——Bromure 会失败即关闭，为每个包等待你的许可，而不是静默放行。有两种情况会导致每个包都弹出提示：

• 离线工作 且启用了 OSV 或 socket.dev：每个未缓存的包都会被扣留。
• socket.dev 搭配 Cargo： socket.dev 不支持 Cargo，因此每个 crates.io 产物都得不到判定。

修复。 对于离线时段，请禁用 OSV 和 socket.dev——时效门槛无需连接即可继续依据已缓存的元数据工作。对于繁重的 Rust 工作，请关闭 socket.dev 或回应这些提示（授予按 package@version 键控）。PyPI 发布时间兜底检查是唯一一个在纯网络错误时失败即开放的检查。

提示注入误报

提示注入检测器会扫描返回给代理的工具结果区段，可以记录、询问或拦截。其行为与调优见提示注入和提示注入设置参考。

一个合法请求被标记或拦截

原因。 分类器为一个传入区段打出了高于工作区阈值的分数——安全文档、一个引用了攻击的页面，或一段读起来像是对代理的指令的代码片段，都可能看起来像注入。

修复。

1. 查看安全日志——本地行会带有被标记片段的简短预览，以便你判断它是否是一次真实的尝试。
2. 如果这是误报且拦截造成了妨碍，请在 提示注入 窗格中将工作区的提示注入模式从 拦截 改为 询问（每次检测由你决定）或 记录（仅记录，从不拦截）。
3. 模型下载和逐开关行为都是按工作区的，因此一个嘈杂的研究工作区可以在 记录 模式下运行，而一个生产工作区仍保持 拦截。

事件触发的自动化全部被拦截

原因。 事件触发的自动化需要 PromptGuard 模型。没有它，每次事件运行都会被拦截，并提示“未安装 PromptGuard 模型——事件触发需要它（在设置中下载）”。这是有意为之，并非缺陷。

修复。 从 提示注入 窗格（或 偏好设置 → 自动化）安装 PromptGuard 模型。如果某个检测器开关已打开但模型下载失败——例如磁盘已满——工作区将在无保护状态下运行，且该失败会被记录；空间可用后请重新下载。

磁盘空间：去向与回收方法

什么占用了空间

存储位于 ~/Library/Application Support/BromureAC/ 下（完整映射参见附录）。占用大户，从大到小：

注意： 仪表板的磁盘卡片优先采用客户机自身的 df 数字，而非宿主机克隆的分配量，因为写时复制克隆会高报使用量——在客户机内释放的块在克隆中仍保持已实体化状态。

回收空间

• 关闭 你未在使用的挂起工作区。完全关闭会清除 vm.state；工作区下次会冷启动。
• 用 bromure-cli model rm <id> 移除未使用的本地模型（会从新布局和旧版 Hugging Face 缓存中同时释放权重）。
• 用 重置磁盘 重置一个臃肿的工作区磁盘（从基础镜像重新克隆，保留主目录），或从回滚界面删除旧检查点。
• 用 bromure-cli trace clear 清除追踪——会同时擦除内存环和磁盘上的主体。
• 用 bromure-cli workspaces rm <workspace> 删除一个你不再需要的整个工作区（确认后移除磁盘和主目录）。
• 如果你想重新开始，用 bromure-cli reset 回收基础镜像（工作区不受影响，因此之后请重新 init）。

远程访问与富客户端

可选的 SSH 远程访问入口和富客户端镜像在远程访问中介绍。下面的症状是那些会阻断连接的情况。

无法通过 SSH（端口 2222）连接

原因。 远程入口默认禁用。它还是一个嵌入式服务器（而非系统 sshd），因此启用 macOS 远程登录对它不起作用，而且在任何基础镜像安装或修订期间它都会被自动暂停。

修复。

1. 用 bromure-cli remote status 检查状态——它会打印服务器是否 ENABLED 且正在运行、绑定地址和端口、身份验证方法、主机密钥指纹、一个现成的 ssh -p <port> <user>@<host> 连接字符串，以及已授权密钥列表。
2. 用 bromure-cli remote enable 启用它（默认：端口 2222，绑定 0.0.0.0，两种身份验证方法均开启）。如果两种身份验证方法都被禁用、端口低于 1024，或基础镜像缺失或正在安装，它都会报错。
3. 用 bromure-cli remote key add <path-or-key> 添加你的公钥。添加或移除密钥会重启监听器并断开活动连接——这是预期行为。

主机密钥或指纹（TOFU）不匹配

原因。 富客户端会在首次连接时固定每个远程主机的主机密钥（首次使用即信任），存储在 ~/Library/Application Support/BromureAC/remote-client/known_hosts 中。固定是按端点（address:port）进行的，因此编辑已保存主机的地址或端口会使所携带的固定失效，并正确地重新触发信任提示。一个未更改的端点上出现不匹配，意味着远程主机的密钥变了——或有东西正在拦截连接。

修复。 如果你确实重建了远程主机，请移除其固定并重新连接以重新信任。如果你没有预期密钥会更改，请停下并在接受之前进行调查。

远程网格或浏览器窗格无法镜像

原因。 一个无界面远程主机——应用正在运行但没有打开统一窗口——无法接受或提供网格布局编辑，尽管其他一切都能镜像。某些由提示驱动的工作树操作（新建工作树、合并、解决）在 v1 中也无法从富客户端使用，而多主机子网别名是一项已记录的设计限制，而非已交付的行为：受支持的配置是单个远程主机。

修复。 在远程主机上打开一个会话窗口，使其有一个可供镜像的统一窗口。对于远程主机上的工作树创建/合并/解决，请改用 SSH/TUI 远程菜单，而非富客户端工具栏。

系统级隧道需要批准

原因。 富客户端的可选系统级隧道使用一个通过 SMAppService 注册的特权 launchd 守护进程。其首次注册会弹出一个后台项目批准开关。

修复。 在 系统设置 → 通用 → 登录项与扩展 下批准 Bromure Agentic Coding（应用可以为你打开该面板）。通过隧道，对远程客户机的 ICMP ping 会在本地得到应答，确认的是路由，而非客户机存活。

报告缺陷

当你在 bromure.io 提交报告时，请包含足够让维护者复现的信息：

1. 应用和镜像版本 — 应用版本（4.3.0）和 bromure-cli info 的输出（基础镜像版本标记、大小和路径）。
2. stderr 日志 — 如从终端捕获 stderr所示从终端启动 bromure-cli，复现问题，并附上输出。如果维护者要求更多细节，请添加 BROMURE_AC_DEBUG=1。
3. 相关窗口 — 对于设置失败，附上从设置窗口复制的 控制台输出；对于安全相关行为，附上经过过滤的 安全日志。
4. 你的预期与实际发生的情况，以及工作区当时是关闭、已挂起还是运行中。

不要包含真实机密——追踪记录和日志行已将它们编校为简短预览，而且应用的构建方式确保真实凭据从一开始就绝不会进入虚拟机。如果你的 Mac 已通过 bromure.io 工作区注册，请通过你所在组织的管理员来提交报告；与注册相关的状态对他们可见，而对 Bromure 本身不可见。注册在企业版中介绍。