故障排除

本章按症状编排。每个条目都会说明可能的原因和修复步骤。请先从第一站：时间线、日志和健康检查开始——下面几乎所有诊断都依赖其中一个来源——然后跳到与你所见情况相符的部分。

以下大部分内容都建立在两个事实之上。第一，机器（在设置编辑器中称为工作区）是持久的沙箱：它的系统磁盘（disk.img）和 Linux 主目录（home.img）会在每次启动之间保留，因此其中之一出了问题，单纯重新启动并不能解决。第二，Bromure Agentic Coding 在流量到达虚拟机之前，在宿主机上执行安全策略——所以看似出现在客户机“内部”的拦截和错误，通常是宿主机代理服务器所为，要在应用中解决，而不是在虚拟机中。

第一站：时间线、日志和健康检查

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

安全时间线

打开 窗口 › 安全…（或用 ⌘K 搜索）。它会记录 Bromure 的安全引擎为你的代理做出的每一项决定——凭据的代理和使用、防火墙与 OpenShell 的判定、客户机沙盒的拒绝、护栏、供应链检查、提示注入扫描、个人数据替换、代理委派消息，以及上游 TLS 问题。记录始终开启，重启后仍会保留，每天的事件保存 90 天。

• 概览 标签页汇总最近一段期间（默认为过去 24 小时）——已阻止、已允许、凭据中转、供应链、个人数据保护——显示每台机器的防护，并列出 最近的拦截。拦截通常是“代理的请求为什么失败？”最快的答案；点击它即可找出它发生的每一次。
• 时间线 标签页列出每一个事件。可用 过滤事件… 字段（软件包名称、主机、机器）、工作区、时间范围与引擎筛选器，以及在镜像远程主机时的机器筛选器（所有机器 / 此 Mac / 某台主机）缩小范围。
• 在有内核哨兵的机器上，双击 网络 行即可看到是哪个提示、工具调用与进程建立了这条连接（网络溯源链）。
• 导出… 会把事件——连同已应用的筛选——保存为 CSV 文件。可附加到错误报告中，或交给你的安全团队。
• 清空 只会隐藏窗口中的事件；磁盘上的每日文件仍会保留。

此窗口的完整说明请见安全概览与时间线。

应用日志

无论你是否从终端启动，应用都会把它写到标准错误输出的所有内容另存一份到 ~/Library/Logs/BromureAC/bromure-ac.log。每次运行都以一行注明构建版本和 macOS 版本的 === … launch pid … 开始，并以一行 exit 结束；崩溃时会留下一行注明致命信号的记录。文件超过 8 MB 时，会在下次启动时轮转，并保留一个之前的文件 bromure-ac.log.1。

遇到以下情况时，请查看这里：

• 机器已保存的状态无法恢复（该行会注明自挂起以来改变了什么——请参阅挂起的机器没有从中断处恢复）；
• 无人值守的启动被拒绝，或运行了文件系统修复；
• 应用意外退出。如果 macOS 没有显示崩溃报告，日志的最后几行就是发生经过的最佳记录。内嵌的终端引擎也可能把崩溃细节保存在 ~/Library/Caches/com.mitchellh.ghostty/sentry。

要实时查看日志，或添加调试输出，请从终端启动应用：

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

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

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

健康检查

应用运行时，会在 ~/Library/Application Support/BromureAC/control.sock 提供一个仅限所有者的控制套接字。向它询问健康状态，即可确认应用仍在运行并有响应：

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 会按需启动后台代理，也是另一个快速的存活检查。安装 bromure-cli 的方法请参阅 CLI、API 与 MCP。

安装控制台

安装基础镜像期间——在引导向导的 安装 步骤，或在 重新构建基础镜像… 之后——进度视图中有一个折叠的 控制台输出 部分，会流式显示安装程序的原始日志，并附有 拷贝 按钮。屏幕上只保留最后 100 行，因此如果需要附加到报告中，请在窗口关闭前拷贝日志。

设置与基础镜像安装

在 Linux 基础镜像存在之前，任何机器都无法运行。首次启动时，引导向导会打开在 欢迎使用 Bromure；点按 开始使用 会进入 安装 步骤，执行与 bromure-ac init 相同的安装。完整流程请见安装与首次运行；本节说明失败时该怎么做。

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

原因。 首选路径会从 https://dl.bromure.io 下载一个已签名并以 gzip 压缩的镜像，验证其 SHA-256 并展开。网络中断、CDN 异常或校验和不匹配都会使其中止。下载本身已会重试，并在每次尝试之间重新获取目录（每周的发布可能在下载途中替换之前的构建）。

修复。 留意状态和 控制台输出。下载端失败时，应用会显示 镜像下载失败 警报，提供 本地构建 或 取消：

1. 如果你在线且只是暂时性失败，请从应用菜单重试：重新构建基础镜像… → 下载预构建镜像。
2. 如果下载无法成功（受限的网络、CDN 被封锁），请选择 本地构建，改在你的 Mac 上构建镜像（约 10 分钟）。产出的是相同的镜像。
3. 在命令行中，bromure-ac init 会自动回退到本地构建。

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

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

修复。 构建会停在 构建基础镜像时出现网络问题 警报，提供 修复并重试（重启 macOS 的网络守护进程——会要求你输入管理员密码）或 取消。如果在 VPN 上持续失败，请在重试前降低客户机网卡的 MTU：

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

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

安装耗尽磁盘空间

原因。 每次安装镜像前，存放支持目录的卷都必须至少有 8 GB 可用空间，而构建途中的监控程序会在可用空间耗尽时中止构建，避免它卡到无法解释的超时。

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

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

原因。 在安装途中取消，或构建失败，都会留下临时文件：支持目录中的 base.img.partial、base.img.gz.partial、stock.img.partial 和 efivars.partial。它们存在就表示有安装正在进行或曾被中断。真正的镜像只会以原子方式替换，因此现有可用的镜像在整个过程中都能继续使用。

修复。 重新运行安装直到完成（重新构建基础镜像… 或 bromure-ac init）。如果要从头开始，bromure-ac reset 会在确认后删除基础镜像的文件（base.img、efivars.bin、base.version、image-state.json，以及保存的下载 stock.img / stock-state.json）——它不会动到你的机器。随时可用 bromure-ac info 确认已安装的内容。

有更新的基础镜像可用

可能会出现两种不同的提示：

• 基础镜像有可用更新（启动时）——应用内附的、或目录发布的基础镜像，比磁盘上的更新。现在更新 会下载它（并以本地重建作为后备）；稍后 会在下次启动时再问。在此期间，当前的镜像仍可继续使用。
• 有更新的基础镜像可用。（机器启动时）——磁盘上的基础比这台机器的系统磁盘当初克隆来源的基础更新。是，升级 会把机器的系统磁盘重置到新的基础上：虚拟机内用 apt 安装的一切都会被清除，主目录则会保留。否 会保留当前的基础，直到下一个版本推出；稍后提醒我 会在明天之后的第一次启动时再问。回答会按机器分别记住。

更新基础镜像本身绝不会改变已有机器的磁盘；每台机器只有在你回答 是，升级 时才会升级。

机器无法启动、引导或恢复

机器列在边栏的 虚拟机 下。机器行上的 ⋯ 按钮提供 启动（或 恢复，运行中则有 关机 / 挂起 / 重启）。当舞台上有会话时，工具栏中的机器菜单——带有机器名称的胶囊——提供 机器详情：含 CPU、内存、磁盘和运行时间卡片的仪表板、配置摘要以及电源按钮。机器的说明请见机器。

启动一直无法完成（“下潜失败”）

原因。 机器不会预先预热——它们会从写时复制的磁盘冷启动（或恢复挂起快照），这需要几秒钟。如果 30 秒后仍没有终端响应，启动屏幕会变成 下潜失败：“虚拟机可能卡住了，或者其系统磁盘可能已损坏。”

修复。

1. 点按一次 继续等待——镜像更新后的首次启动，或较慢的 Mac，可能需要更久。
2. 如果仍然无法启动，请从机器的 ⋯ 菜单重启（重启）。
3. 如果原因是系统磁盘上有损坏的文件，请参阅救回因损坏文件而无法启动的机器，或点按 重置系统磁盘… 从基础镜像重新克隆系统磁盘。你的主目录——项目、dotfiles、.ssh 密钥、shell 历史——会保留；用 apt 安装的一切和 /etc 下的更改则会丢失。

机器启动时因磁盘错误而停止

原因。 系统磁盘未通过启动时的文件系统检查——通常是因为虚拟机在写入途中被停止（强制退出、崩溃、断电）。客户机无法自行越过这一步。

修复。 机器的舞台会显示 磁盘错误——“系统磁盘未通过启动时的文件系统检查，启动无法继续。”——以及触发它的控制台行：

1. 点按 修复磁盘。Bromure 会停止虚拟机，用其内置检查器在 Mac 上重放磁盘的日志，然后再次启动。不会删除任何东西。
2. 如果修复后启动仍然失败，请点按 重置系统磁盘… 并确认 重置为基础。主目录会保留。

在富客户端上，同样的选择会以提示的形式出现：““‹machine›” can't boot — disk error”，一开始是 修复磁盘 / 暂不，尝试过修复后则是 Reset System Disk / 暂不。你也可以在机器停止时自行运行修复：bromure-cli vm fsck <machine> --repair。请参阅高级。

挂起的机器没有从中断处恢复

原因。 恢复会把已保存的内存（vm.state）还原到机器完全相同的虚拟硬件上。当配置自挂起以来有所改变——内存增减、共享文件夹不同、应用或基础镜像有新的构建——已保存的状态就无法再恢复。

会发生什么。 Bromure 不会让机器卡住：恢复失败时，它会丢弃已保存的状态，并以相同的磁盘和主目录重新启动机器。你的文件都还在；只有挂起会话中正在运行的程序和打开的终端会丢失。应用日志会注明原因，说明改变了什么——例如 configuration changed since the suspend: memoryGB: 8 → 6 — booting fresh。启动挂起机器的自动化和委派也会有相同的行为。

几个相关情况：

• 挂起期间更改了共享文件夹。 保存机器的设置时会询问 丢弃“‹machine›”的已挂起虚拟机？——请选择 丢弃并保存；下次启动会冷启动。主目录和共享文件夹中的文件不受影响。
• 重置或清除磁盘始终会丢弃已保存的状态：全新的磁盘搭配旧的内存会立即损坏。
• 开发者构建版本。 某个应用构建版本保存的状态，常常无法由另一个本地构建版本恢复。切换构建版本之前，请把机器关机，而不是挂起。

机器被标记为“已入侵”

原因。 代理服务器看到某台机器的替代凭据正发往一台并非为其签发的主机——这是外泄的特征。请求会被阻止、虚拟机会被暂停，而 此环境可能已被入侵 警报会列出泄漏内容，并提供四个选项：

在富客户端或无界面的 Mac 上，提示会提供 关机 / 阻止 / 允许，无人回答时则回退到 关机。如果你在机器的 防护栏 面板中打开了 凭据外泄时不弹出警报，就不会出现警报：泄漏仍会被阻止并记录在时间线中。

修复。 被标记为已入侵的机器会显示“已入侵 — 启动时会提示清除磁盘和主目录”，并在你于 ⛔ “‹machine›”已被标记为已入侵 中确认清除之前拒绝启动。清除并启动 会移除磁盘、主目录和已保存的状态，然后启动一台全新的虚拟机——你的凭据、SSH 密钥和机器设置都会保留。共享的项目文件夹位于 Bromure 的存储之外，不会被清除，因此请手动检查其中是否有被污染的文件。自动化或委派无法确认清除：其启动会以“The workspace is marked compromised — start it yourself to confirm the wipe.”被拒绝。检测模型的说明请见凭据与传输边界。

“The workspace did not boot in time”/“did not start in time”

原因。 某个会话、自动化或编码任务一直等待其机器启动，最后放弃了。常见原因：

• 机器确实启动失败——请在其舞台上查找 下潜失败 或 磁盘错误（见上文）。
• 无人值守的启动因为需要你的回答而被拒绝。自动化的运行历史会显示原因，而不是超时：“The workspace is marked compromised — start it yourself to confirm the wipe.”或““‹model›” is still downloading — the workspace can't start until it has.”。
• Mac 处于睡眠状态或负载过重。

修复。 从机器的 ⋯ 菜单自行启动机器并留意其舞台，回应它提出的任何提示，然后重试会话或运行。启动时的提示（镜像更新、新的推荐软件包）会以表单形式出现在主窗口上，绝不会阻止机器启动。

如果新会话改为显示“代理始终没有出现…”，机器可能正在运行较旧的虚拟机内代理：请从其 ⋯ 菜单 重启，然后再试一次。

可用磁盘空间不足

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

修复。 释放空间（请参阅磁盘空间），然后再次启动机器。

救回因损坏文件而无法启动的机器

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

修复。 在机器已停止的情况下，使用内置的 ext4 浏览器：

1. 工作区 › 打开 ext4 文件…，然后在 ~/Library/Application Support/BromureAC/profiles/<uuid>/ 下选择该机器的 disk.img 或 home.img。
2. 浏览到出问题的文件。右键单击可 预览 或将其 提取… 到你的 Mac 上。
3. 如果要就地修补，请点按 启用编辑…（切勿编辑运行中虚拟机已打开的镜像），然后右键点按 → 替换…，用你 Mac 上已修正的副本替换。
4. 如果浏览器报告日志需要恢复，请先点按 运行 fsck…。检查器是内置的，无需安装任何东西。

如果损坏在主目录中——代理删除或弄坏了某些东西——机器 ⋯ 菜单中的 回退主目录… 可以把主目录回退到之前某次启动时的状态。请参阅高级。

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

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

原因。 机器运行时，这些破坏性操作会被拒绝。

修复。 先把机器关机（工具提示为“Close the session window first.”），然后再试一次。

Kubernetes 节点与镜像仓库

集群和镜像仓库在各自的机器中运行，列在 虚拟机 › Kubernetes 和 镜像仓库 下。请参阅 Kubernetes 集群与注册表。

退出应用或停止后，节点或镜像仓库没有回来

Bromure 的做法。 退出应用会挂起集群节点和镜像仓库，下次启动时会恢复它们；无法恢复的快照会回退到全新启动，与任何机器相同。明确的 停止 会以最多 60 秒的宽限时间将它们干净地关机。

如果节点的启动仍然停在文件系统检查上，Bromure 会在控制台上捕获到，停止虚拟机，对节点的系统磁盘和数据磁盘运行其内置检查器，如果仍不够，则从一台一次性机器对它们运行 Linux 的 e2fsck。它会再重试启动一次；如果也失败，集群会显示清楚的错误。

修复。 查看集群的 日志 标签页以了解发生了什么。如果自动修复已放弃，请从集群的 集群操作 菜单重启集群；最后手段是删除后重新创建。

工作区看不到某个集群或镜像仓库

原因。 访问权限是按机器设置的。不在集群或镜像仓库访问列表上的机器，不会获得 ~/.kube/config 上下文，也不会有 $BROMURE_REGISTRY。

修复。 打开集群或镜像仓库的 访问 标签页（集群另有 集群操作 › 工作区访问…），然后添加该机器。一旦你更改集群的访问权限，其上下文就会推送到运行中机器的 ~/.kube/config。

登录和模型问题

这项设计让真正的凭据远离虚拟机：客户机以替代（“假的”）令牌运行，而宿主机代理服务器会在传输途中换上真正的机密。大部分“认证”症状都可以追溯到这条边界。请参阅凭据与传输边界和模型与提供方。

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

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

修复。 什么都不用做——不要试图在虚拟机内“纠正”密钥。如果真正的请求在提供方处因认证错误而失败，问题出在宿主机上的真正机密：请在 偏好设置 › 模型（如果机器有自定义模型设置，则在机器自己的 模型 面板）重新输入提供方的 API 密钥。出现在发往错误主机的请求中的假令牌，会触发入侵检测，而不会通过认证。

订阅停止工作（“登录已过期”）

原因。 订阅登录（Claude、ChatGPT、Grok、Kimi）会加密保存在宿主机上，并由宿主机负责刷新。如果提供方撤销了刷新令牌，或账户的会话结束，宿主机就无法再签发有效的令牌，所有使用该登录的会话都会失败。

修复。

1. 打开 偏好设置… › 模型（⌘,）。提供方会显示 登录已过期 和“‹提供方› 拒绝了已保存的登录（‹日期›）。在你重新登录之前，会话无法使用它。”
2. 点按 重新登录，并在浏览器中完成登录。机器内的替代密钥永远不会变，因此运行中的代理会接手新的登录。
3. 如果有一台机器在其他机器正常时仍然失败，它很可能有自己的登录。从机器内部开始的登录会询问 与每个工作区共享？——选择 仅此工作区 会给该机器一个遮蔽共享登录的私有登录。请检查该机器的 模型 面板：在那里重新登录，或点按 使用全局提供方，让机器继承共享的登录。

在聊天中，无法认证的代理会显示一张卡片：登录 ‹代理›，附有 打开登录页面 和 粘贴代码 字段。边栏的该行会显示“需要登录”。从卡片登录会在宿主机上捕获凭据，与模型面板完全相同。

代理需要模型提供方

原因。 你选择的代理在这台机器上没有任何可用的运行来源——没有 API 密钥、没有登录、没有自定义服务器或设备端模型。聊天会显示“‹代理› 需要一个模型提供方”和“‹代理› 在此机器上还没有模型提供方。请在机器设置中添加 API 密钥或本地模型，然后重新开始会话。”

修复。 点按卡片中的 机器设置…，或在 偏好设置 › 模型 中设置提供方，然后重新开始会话。在新会话屏幕上，处于此状态的代理会标示为“启动时登录”或“启动时选择模型提供方”。

代理卡在首次运行、信任或登录屏幕

原因。 编程代理有自己的首次运行屏幕——主题选择、文件夹信任问题、登录菜单——聊天无法原样显示。Bromure 会在代理启动前回应引导屏幕，并把其余的转成聊天中的卡片：

• 登录菜单会变成登录卡片（Claude 的“Not logged in”、Codex 的 ChatGPT 选择、Grok 的设备代码、Kimi 的登录）；
• 代理等待你信任文件夹时，会显示 信任此文件夹并继续；
• 代理无法认证、达到使用上限或因错误而停止时，会显示红色卡片；
• 对于没有自有登录的 Oh My Pi，会显示一张指向机器设置的提供方卡片。

修复。 回应卡片。如果聊天看起来仍然卡住——“正在思考…”却毫无动静——请按工具栏中的 Linux（⌥⌘U）查看代理的真正终端，处理屏幕上的内容，再按 会话 返回。卡片上的“切换到终端解决后再发送一次。”也是同样的意思。

对于 Kimi Code，Bromure 会登录 Kimi 的国际服务（kimi.ai）。在此变更之前完成的 Kimi 登录可能会停止工作并显示登录卡片；请重新登录。

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

原因。 当代理在虚拟机内用真正的令牌登录时，代理服务器会检测到，并提议把它移到宿主机上，让真正的机密离开客户机。这个选择会按机器和提供方分别记住。

修复。 在机器的 跟踪 面板中，Claude 订阅令牌替换 和 Codex 订阅令牌替换 行会显示当前状态，并附有重置控件——忘记交换（下次会话重新提示） 或 重新启用提示。

虚拟机内的网络

客户机中的 IPv6 无法工作

原因。 这是有意的设计。Bromure 的宿主机网络路径只支持 IPv4，而宣告 IPv6 却没有可用 IPv6 出口的局域网，会让每一次 AAAA 查询都卡住。较新的基础镜像会在客户机内关闭 IPv6，而 apt 在每次启动时都会被强制使用 IPv4。

修复。 请使用 IPv4 地址和主机名。客户机中的 localhost 只会解析为 127.0.0.1。

机器的子网与你使用的网络冲突

原因。 新安装会把机器放在 172.16.0.0/12 内一个随机的私有 /24 上（跳过 Docker 常用的 172.17–172.20，以及 Mac 已经所在的任何范围）。较旧的安装可能仍使用 192.168.64.0/24。两者都可能与 VPN 或办公室网络冲突。

修复。 打开 偏好设置… › 资源。在 工作区子网 下，使用私有子网（避免多个远程实例之间的冲突） 会切换到随机的 172.16/12 子网，而 随机生成 会挑选一个新的。更改会在你的机器下次启动时应用。

机器的流量在 VPN 上失败

原因。 VPN 隧道会缩小可用的数据包大小；MTU 太大会让下载石沉大海。

修复。 客户机网卡已限制为 1280 字节。如果企业网络路径需要更小的值，请按构建基础镜像时出现网络问题中的说明降低 vm.mtu。

虚拟机内的 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（位于 127.0.0.1:65534 的客户机内代理）得以传递，并把 CA 挂载或安装到容器工具会查找的位置。
3. 如果证书错误只在你删除或轮换 CA（见下文）之后才出现，请重启受影响的机器，让新的 CA 重新部署。

对于固定自身证书的主机，机器的 防护栏 面板可以针对单个请求绕过拦截（X-bromure-insecure）——请参阅护栏设置。

轮换根 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

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

在时间线中找出原因

打开安全时间线，选择 供应链 引擎，然后重新运行安装。每个检查过的软件包都会显示为一行：通过的为绿色，被阻止或剥离的为红色。安装期间时间线一片安静，通常表示一切都来自缓存——概览标签页上的 已检查的软件包 方块会显示检查确实在进行。

覆盖一个拦截

修复。 供应链的各层级是按机器设置的开关，会实时应用（无需重启虚拟机）。要放行特定软件包，请在 供应链 面板中添加豁免或允许列表条目，或为该机器调低或停用相关层级。

每次安装都提示许可（离线，或 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>。
• 用机器 ⋯ 菜单中的 重置磁盘 重置臃肿的系统磁盘（从基础重新克隆，保留主目录）。
• 用 bromure-cli trace clear 清除追踪——会同时擦除内存环和磁盘上的主体。
• 删除不再需要的会话（行菜单中的 删除会话），并用边栏的清理行删除机器或文件夹已不存在的对话。
• 删除不再需要的整台机器（⋯ › 删除工作区，或 bromure-cli workspaces rm <workspace>），这会移除其磁盘和主目录。
• 从各自的仪表板删除未使用的集群和镜像仓库。
• 如果想从头开始，可用 bromure-ac reset 回收基础镜像（机器不受影响，之后请重新运行 init）。

远程访问与富客户端

可选的 SSH 远程访问前门和富客户端镜像的说明，请见远程访问与客户端。以下是会阻止连接的症状。

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

原因。 远程前门默认关闭。它也是内嵌的服务器（不是系统的 sshd），因此启用 macOS 的远程登录对它没有作用，而且在任何基础镜像安装期间它都会暂停。

修复。

1. 用 bromure-cli remote status 检查状态——它会显示服务器是否已启用并在运行、绑定地址和端口、认证方式、主机密钥指纹、现成的 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）进行的，因此编辑已保存主机的地址或端口，理所当然会再次触发信任提示。端点未变却不匹配，表示远程主机的密钥已更改——或有东西在拦截连接。

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

远程偏好设置无法加载

原因。 镜像窗口打开时，偏好设置… 可以编辑远程主机的设置（设置对象： 选择器）。获取设置时会显示“正在从 ‹主机› 加载偏好设置…”，而在连接中断或远程主机为较旧版本时，会显示“无法加载远程偏好设置”。

修复。 确认镜像窗口已连接，然后点按 重试。在此期间，可在 设置对象： 中选择 此 Mac 来编辑自己的设置。

系统级隧道需要批准

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

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

报告缺陷

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

1. 应用和镜像版本——应用版本（在 About Bromure Agentic Coding 中）和 bromure-ac info 的输出（基础镜像的版本戳、大小和路径）。
2. 应用日志——~/Library/Logs/BromureAC/bromure-ac.log（如果问题始于上次启动之前，另加 bromure-ac.log.1）。如果维护者要求更多细节，请从终端用 BROMURE_AC_DEBUG=1 重新启动。
3. 相关记录——设置失败时，附上拷贝的 控制台输出；与安全相关的行为，则附上从安全时间线用 导出… 导出的已筛选 CSV。
4. 你预期的结果与实际发生的情况，以及机器当时是关闭、挂起还是运行中。

请勿附上真正的机密——追踪记录和日志行已经把它们截短为简短预览，而且应用的设计让真正的凭据从一开始就不会进入虚拟机。如果你的 Mac 已注册到 bromure.io 工作区，请通过组织的管理员提交报告。注册的说明请见企业版。