疑難排解

本章依症狀編排。每個項目都會說明可能的原因與修正步驟。請先從第一站：時間軸、記錄與健康檢查開始——下列幾乎所有診斷都仰賴其中一個來源——然後跳到與你所見情況相符的章節。

以下大部分內容都建立在兩個事實之上。第一，機器（在設定編輯器中稱為工作區）是持久的沙箱：它的系統磁碟（disk.img）與 Linux 家目錄（home.img）會在每次啟動之間保留，因此其中之一出了問題，單純重新啟動並不能解決。第二，Bromure Agentic Coding 在流量抵達 VM 之前，於主機上執行安全政策——所以看似出現在客體「內部」的封鎖與錯誤，通常是主機代理伺服器所為，要在 App 中解決，而不是在 VM 中。

第一站：時間軸、記錄與健康檢查

在變更任何設定之前，先了解應用程式本身回報了什麼。

安全性時間軸

開啟 視窗 › 安全性…（或用 ⌘K 搜尋）。它會記錄 Bromure 的安全引擎為你的代理程式所做的每一項決定——憑證的代理與使用、防火牆與 OpenShell 的判定、客體沙盒的拒絕、防護欄、供應鏈檢查、提示注入掃描、個人資料替換、代理程式委派訊息，以及上游 TLS 問題。記錄一律開啟，重新啟動後仍會保留，每天的事件會保存 90 天。

• 總覽 分頁會摘要最近一段期間（預設為過去 24 小時）——已封鎖、已允許、憑證中介、供應鏈、個人資料保護——顯示每台機器的防護，並列出 最近的封鎖。封鎖通常是「代理程式的請求為什麼失敗？」最快的答案；按一下它即可找出它發生的每一次。
• 時間軸 分頁會列出每一筆事件。可用 篩選事件… 欄位（套件名稱、主機、機器）、工作區、時間範圍與引擎篩選器，以及在鏡像遠端主機時的機器篩選器（所有機器 / 此 Mac / 某台主機）縮小範圍。
• 在有核心哨兵的機器上，按兩下 網路 列即可看到是哪個提示、工具呼叫與處理程序建立了這條連線（網路溯源鏈）。
• 輸出… 會把事件——連同已套用的篩選——存成 CSV 檔。可附加到錯誤回報中，或交給你的安全團隊。
• 清除 只會隱藏視窗中的事件；磁碟上的每日檔案仍會保留。

此視窗的完整說明請見安全性總覽與時間軸。

App 記錄

無論你是否從終端機啟動，App 都會把它寫到標準錯誤輸出的所有內容，另存一份在 ~/Library/Logs/BromureAC/bromure-ac.log。每次執行都以一行註明建置版本與 macOS 版本的 === … launch pid … 開始，並以一行 exit 結束；當掉時會留下一行註明致命訊號的記錄。檔案超過 8 MB 時，會在下次啟動時輪替，並保留一個先前的檔案 bromure-ac.log.1。

遇到以下情況時，請查看這裡：

• 機器已儲存的狀態無法還原（該行會註明自暫停以來改變了什麼——請參閱暫停的機器沒有從中斷處恢復）；
• 無人值守的啟動遭拒，或執行了檔案系統修復；
• App 意外結束。如果 macOS 沒有顯示當機報告，記錄的最後幾行就是發生經過的最佳紀錄。內嵌的終端機引擎也可能把當機細節保存在 ~/Library/Caches/com.mitchellh.ghostty/sentry。

若要即時查看記錄，或加入除錯輸出，請從終端機啟動 App：

"/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。

健康檢查

App 執行時，會在 ~/Library/Application Support/BromureAC/control.sock 提供一個僅限擁有者的控制 socket。向它詢問健康狀態，即可確認 App 仍在運作並有回應：

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

連線遭拒代表 App（或其無介面代理程式）沒有在執行；bromure-cli vm ls 會視需要啟動背景代理程式，也是另一個快速的存活檢查。安裝 bromure-cli 的方式請參閱 CLI、API 與 MCP。

安裝主控台

安裝基礎映像檔期間——在引導精靈的 安裝 步驟，或在 重建基礎映像… 之後——進度檢視中有一個收合的 主控台輸出 區段，會串流顯示安裝程式的原始記錄，並附有 拷貝 按鈕。畫面上只保留最後 100 行，因此若需要附加到回報中，請在視窗關閉前拷貝記錄。

設定與基底映像檔安裝

在 Linux 基礎映像檔存在之前，任何機器都無法執行。首次啟動時，引導精靈會開在 歡迎使用 Bromure；點按 開始使用 會前往 安裝 步驟，執行與 bromure-ac init 相同的安裝。完整流程請見安裝與首次執行；本節說明失敗時該怎麼做。

預建映像檔下載失敗或停滯

原因。 首選路徑會從 https://dl.bromure.io 下載一個已簽署並以 gzip 壓縮的映像檔，驗證其 SHA-256 並展開。網路中斷、CDN 異常或校驗和不符，都會使其中止。下載本身已會重試，並在每次嘗試之間重新取得目錄（每週的發佈可能在下載途中取代先前的建置）。

修正。 留意狀態與 主控台輸出。下載端失敗時，App 會顯示 映像檔下載失敗 警示，提供 本機建置 或 取消：

1. 如果你在線上且只是暫時性失敗，請從 App 選單重試：重建基礎映像… → 下載預建映像檔。
2. 如果下載無法成功（受限的網路、CDN 被封鎖），請選擇 本機建置，改在你的 Mac 上建置映像檔（約 10 分鐘）。產出的是相同的映像檔。
3. 在命令列中，bromure-ac init 會自動退回本機建置。

「基底映像檔建置期間發生網路問題」

原因。 本機建置會啟動一個用完即棄的 Alpine 安裝程式 VM，它需要 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 確認已安裝的內容。

有更新的基礎映像可用

可能會出現兩種不同的提示：

• 基礎映像檔有可用更新（啟動時）——App 內附的、或目錄發佈的基礎映像檔，比磁碟上的更新。現在更新 會下載它（並以本機重建作為備援）；稍後 會在下次啟動時再問。在此期間，目前的映像檔仍可繼續使用。
• 有更新的基礎映像可用。（機器啟動時）——磁碟上的基礎比這台機器的系統磁碟當初複製來源的基礎更新。是，升級 會把機器的系統磁碟重置到新的基礎上：VM 內以 apt 安裝的一切都會被清除，家目錄則會保留。否 會保留目前的基礎，直到下一個版本推出；稍後提醒我 會在明天之後的第一次開機時再問。回答會依機器分別記住。

更新基礎映像檔本身絕不會改變既有機器的磁碟；每台機器只有在你回答 是，升級 時才會升級。

機器無法啟動、開機或恢復

機器列在側邊欄的 虛擬機器 之下。機器列上的 ⋯ 按鈕提供 啟動（或 恢復，執行中則有 關機 / 暫停 / 重新開機）。當舞台上有工作階段時，工具列中的機器選單——帶有機器名稱的膠囊——提供 機器詳細資訊：含 CPU、記憶體、磁碟與運作時間卡片的儀表板、設定摘要以及電源按鈕。機器的說明請見機器。

開機一直無法完成（「下潛失敗」）

原因。 機器不會預先暖機——它們會從寫入時複製的磁碟冷開機（或還原暫停快照），這需要幾秒鐘。如果 30 秒後仍沒有終端機回應，開機畫面會變成 下潛失敗：「虛擬機器可能已卡住，或其系統磁碟可能已損壞。」

修復。

1. 點按一次 繼續等待——映像檔更新後的首次開機，或較慢的 Mac，可能需要更久。
2. 如果仍然無法啟動，請從機器的 ⋯ 選單重新開機（重新開機）。
3. 如果原因是系統磁碟上有損壞的檔案，請參閱救回因損壞檔案而無法開機的機器，或點按 重置系統磁碟… 從基礎映像檔重新複製系統磁碟。你的家目錄——專案、dotfiles、.ssh 金鑰、shell 歷史——會保留；以 apt 安裝的一切與 /etc 下的變更則會遺失。

機器開機時因磁碟錯誤而停止

原因。 系統磁碟未通過開機時的檔案系統檢查——通常是因為 VM 在寫入途中被停止（強制結束、當機、斷電）。客體無法自行越過這一步。

修正。 機器的舞台會顯示 磁碟錯誤——「系統磁碟未通過開機時的檔案系統檢查，無法繼續開機。」——以及觸發它的主控台行：

1. 點按 修復磁碟。Bromure 會停止 VM，以其內建檢查器在 Mac 上重播磁碟的日誌，然後再次開機。不會刪除任何東西。
2. 如果修復後開機仍然失敗，請點按 重置系統磁碟… 並確認 重置為基礎。家目錄會保留。

在完整用戶端上，同樣的選擇會以提示的形式出現：「“‹machine›” can't boot — disk error」，一開始是 修復磁碟 / 暫時不要，嘗試過修復後則是 Reset System Disk / 暫時不要。你也可以在機器停止時自行執行修復：bromure-cli vm fsck <machine> --repair。請參閱進階。

暫停的機器沒有從中斷處恢復

原因。 恢復會把已儲存的記憶體（vm.state）還原到機器完全相同的虛擬硬體上。當設定自暫停以來有所改變——記憶體增減、共享檔案夾不同、App 或基礎映像檔有新的建置——已儲存的狀態就無法再還原。

會發生什麼。 Bromure 不會讓機器卡住：還原失敗時，它會捨棄已儲存的狀態，並以相同的磁碟與家目錄重新啟動機器。你的檔案都還在；只有暫停的工作階段中正在執行的程式與開啟的終端機會遺失。App 記錄會註明原因，說明改變了什麼——例如 configuration changed since the suspend: memoryGB: 8 → 6 — booting fresh。啟動暫停機器的自動化與委派也會有相同的行為。

幾個相關情況：

• 暫停期間變更了共享檔案夾。 儲存機器的設定時會詢問 要丟棄「‹machine›」的暫停虛擬機嗎？——請選擇 丟棄並儲存；下次啟動會冷開機。家目錄與共享檔案夾中的檔案不受影響。
• 重置或清除磁碟一律會捨棄已儲存的狀態：全新的磁碟搭配舊的記憶體會立即損毀。
• 開發者建置版本。 某個 App 建置版本儲存的狀態，常常無法由另一個本機建置版本還原。切換建置版本之前，請把機器關機，而不是暫停。

機器被標記為「已入侵」

原因。 代理伺服器看到某台機器的替代憑證正前往一台並非為其簽發的主機——這是外洩的特徵。請求會被封鎖、VM 會被暫停，而 此環境可能已遭入侵 警示會列出外洩內容，並提供四個選項：

在完整用戶端或無介面的 Mac 上，提示會提供 關機 / 封鎖 / 允許，無人回答時則退回 關機。如果你在機器的 防護欄 窗格中開啟了 憑證外洩時不發出警示，就不會出現警示：外洩仍會被封鎖並記錄在時間軸中。

修正。 被標記為已入侵的機器會顯示「已入侵 — 啟動時會提示清除磁碟與家目錄」，並在你於 ⛔「‹machine›」已被標記為已入侵 中確認清除之前拒絕開機。清除並啟動 會移除磁碟、家目錄與已儲存的狀態，然後開機一台全新的 VM——你的憑證、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 處於睡眠狀態或負載過重。

修正。 從機器的 ⋯ 選單自行啟動機器並留意其舞台，回應它提出的任何提示，然後重試工作階段或執行。啟動時的提示（映像檔更新、新的建議套件）會以表單形式出現在主視窗上，絕不會阻擋機器啟動。

如果新的工作階段改為顯示「代理程式始終沒有出現…」，機器可能正在執行較舊的 VM 內代理程式：請從其 ⋯ 選單 重新開機，然後再試一次。

可用磁碟空間不足

原因。 建立任何寫入時複製的複本或家目錄映像檔時，若磁碟區上的可用空間少於 1 GB 便會拒絕繼續，會以磁碟已滿的錯誤快速失敗，而非在工作階段途中卡死。

修正。 釋放空間（請參閱磁碟空間），然後再次啟動機器。

救回因損壞檔案而無法開機的機器

原因。 寫入客體的錯誤設定——損壞的 /etc/fstab、毀損的點檔——可能會讓 VM 在您能登入修復之前就無法開機。由於 macOS 無法掛載 ext4，您無法直接在 Finder 中開啟該磁碟。

修正。 在機器已停止的情況下，使用內建的 ext4 瀏覽器：

1. 工作區 › 打開 ext4 檔案…，然後在 ~/Library/Application Support/BromureAC/profiles/<uuid>/ 下選擇該機器的 disk.img 或 home.img。
2. 瀏覽至有問題的檔案。以滑鼠右鍵按一下可 預覽，或將其 擷取… 至您的 Mac。
3. 若要就地修補，請點按 啟用編輯…（切勿編輯執行中 VM 已開啟的映像檔），然後按右鍵 → 取代…，以你 Mac 上已修正的副本取代。
4. 如果瀏覽器回報日誌需要復原，請先點按 執行 fsck…。檢查器是內建的，不需要安裝任何東西。

如果損壞在家目錄中——代理程式刪除或弄壞了某些東西——機器 ⋯ 選單中的 回復個人檔案夾… 可以把家目錄回復到先前某次開機時的狀態。請參閱進階。

警告： 就地取代只有在新內容能容納於檔案既有已配置區塊時才有效——放大檔案會被拒絕（「That file would need to grow」）。請用它來修正設定與取出檔案，而非新增資料。

「重設磁碟」／「清除家目錄…」呈現灰色無法使用

原因。 機器執行中時，這些破壞性動作會被拒絕。

修正。 先把機器關機（工具提示為「Close the session window first.」），然後再試一次。

Kubernetes 節點與登錄檔

叢集與登錄檔在各自的機器中執行，列在 虛擬機器 › Kubernetes 與 映像檔登錄 之下。請參閱 Kubernetes 叢集與登錄檔。

結束 App 或停止後，節點或登錄檔沒有回來

Bromure 的做法。 結束 App 會暫停叢集節點與登錄檔，下次啟動時會恢復它們；無法還原的快照會退回全新開機，與任何機器相同。明確的 停止 會以最多 60 秒的寬限時間將它們乾淨地關機。

如果節點的開機仍然停在檔案系統檢查上，Bromure 會在主控台上攔截到，停止 VM，對節點的系統磁碟與資料磁碟執行其內建檢查器，若仍不夠，則從一台拋棄式機器對它們執行 Linux 的 e2fsck。它會再重試開機一次；若也失敗，叢集會顯示清楚的錯誤。

修正。 查看叢集的 記錄 分頁以了解發生了什麼。如果自動修復已放棄，請從叢集的 叢集操作 選單重新啟動叢集；最後手段是刪除後重新建立。

工作區看不到某個叢集或登錄檔

原因。 存取權是依機器設定的。不在叢集或登錄檔存取清單上的機器，不會取得 ~/.kube/config 情境，也不會有 $BROMURE_REGISTRY。

修正。 開啟叢集或登錄檔的 存取 分頁（叢集另有 叢集操作 › 工作區存取…），然後加入該機器。一旦你變更叢集的存取權，其情境就會推送到執行中機器的 ~/.kube/config。

登入與模型問題

這項設計讓真正的憑證遠離 VM：客體以替代（「假的」）權杖執行，而主機代理伺服器會在傳輸途中換上真正的密鑰。大部分的「驗證」症狀都可以追溯到這條邊界。請參閱憑證與傳輸邊界與模型與供應商。

代理程式（或您）看到假的 API 金鑰

原因。 這是預期行為。VM 內像 ANTHROPIC_API_KEY、OPENAI_API_KEY、XAI_API_KEY、GH_TOKEN 這類環境變數，以及 AWS 變數，都是刻意設置的誘餌。代理伺服器會在主機端為允許的目的地替換為真正的值，因此外洩的假值毫無用處。

修正。 什麼都不用做——不要試圖在 VM 內「修正」金鑰。如果真正的請求在供應商端因驗證錯誤而失敗，問題出在主機上的真正密鑰：請在 偏好設定 › 模型（若機器有自訂模型設定，則在機器自己的 模型 窗格）重新輸入供應商的 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 登入可能會停止運作並顯示登入卡片；請重新登入。

「是否替換訂閱權杖？」持續出現，或誤按了拒絕

原因。 當代理程式在 VM 內以真正的權杖登入時，代理伺服器會偵測到，並提議把它移到主機上，讓真正的密鑰離開客體。這個選擇會依機器與供應商分別記住。

修正。 在機器的 追蹤 窗格中，Claude 訂閱權杖替換 與 Codex 訂閱權杖替換 列會顯示目前狀態，並附有重設控制項——忘記替換（下次工作階段重新提示） 或 重新啟用提示。

VM 內的網路

客體中的 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。

VM 內的 TLS 與憑證錯誤

「self-signed certificate」或「unable to get local issuer certificate」

原因。 所有客體 HTTPS 都會被主機的中間人（MITM）代理伺服器攔截，它會以各安裝專屬的根 CA 重新簽署流量。VM 內的工具透過 Bromure 為 node、python、go、rust、curl、deno 與 AWS SDK 設定的 CA 套件組環境變數，以及暫存於中繼共用區的 CA 檔案（bromure-ca.pem），來信任該 CA。若某個工具忽略了這些變數——或某個容器自備信任存放區——就會拒絕代理伺服器的憑證。

修復。

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 中。若您懷疑金鑰已外洩，可能會想輪替它。

修正。 結束 App，刪除 ca/ 目錄，然後重新啟動——會產生全新的 CA，並在機器下次啟動時重新部署到機器中。已擷取的追蹤內容不受影響，但任何釘選舊憑證的客體都必須重新信任新的憑證。

供應鏈封鎖

當代理程式的 npm install、pip install 或類似指令以特殊的錯誤失敗時，很可能是主機的供應鏈管線介入了。政策及其層級的說明請見供應鏈防護與供應鏈設定參考。

安裝以 HTTP 451 失敗

原因。 451（「Unavailable For Legal Reasons」）是 Bromure 的供應鏈封鎖——之所以選用它，是為了一眼就能與 防護欄 所用的 403 區分開來。套件管理員會在其錯誤輸出中逐字列印原因，例如：

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

修復。 閱讀該原因。常見的觸發原因與對應解法：

在時間軸中找出原因

開啟安全性時間軸，選擇 供應鏈 引擎，然後重新執行安裝。每個檢查過的套件都會顯示為一列：通過的為綠色，被封鎖或剝除的為紅色。安裝期間時間軸一片安靜，通常代表一切都來自快取——總覽分頁上的 已檢查的套件 方塊會顯示檢查確實在進行。

覆寫封鎖

修正。 供應鏈的各層級是依機器設定的開關，會即時套用（不需重新啟動 VM）。若要放行特定套件，請在 供應鏈 窗格中加入豁免或允許清單項目，或為該機器調低或停用相關層級。

每次安裝都要求同意（離線，或 socket.dev + Cargo）

原因。 當 OSV 或 socket.dev 已啟用但無法產生結果時——網路中斷，或該生態系不受支援——Bromure 會失敗時封閉（fail closed），為每個套件保留待您同意，而非默默放行。有兩種情況會導致每個套件都出現提示：

• 離線作業 且啟用了 OSV 或 socket.dev：每個未快取的套件都會被保留。
• socket.dev 搭配 Cargo： socket.dev 不支援 Cargo，因此每個 crates.io 產物都無法產生結果。

修復。 若會離線一段時間，請停用 OSV 與 socket.dev——時效閘門在無網路連線的情況下仍可依已快取的中繼資料運作。若有大量 Rust 工作，可關閉 socket.dev，或直接回應提示（授權以 package@version 為索引鍵）。PyPI 發佈時間的後備檢查是唯一一項在純網路錯誤時會*失敗時開放（fail open）*的檢查。

提示注入誤判

提示注入偵測器會掃描傳回給代理程式的內容，並可以記錄、詢問或封鎖。其行為與調整方式請見提示注入偵測與防護欄與提示注入設定參考。

正當的請求被標記或封鎖

原因。 分類器給某段傳入內容的分數高於機器的門檻值——安全性文件、引用攻擊的網頁，或讀起來像是對代理程式下指令的片段，看起來都可能像是注入。

修復。

1. 檢查時間軸中的 提示注入 列，判斷這是否是真正的攻擊嘗試。
2. 如果是誤判且封鎖造成妨礙，請在 提示注入 窗格中，把機器的提示注入模式從 封鎖 改為 詢問（每次偵測由你決定）或 記錄（只記錄，絕不封鎖）。
3. 設定是依機器分別設定的，因此雜訊多的研究用機器可以用 記錄 模式執行，而正式環境的機器則維持 封鎖。

代理程式之間的訊息也會被掃描：被標記的委派訊息會顯示「已攔截 — 提示注入」，並記錄在 代理程式委派 之下。

事件觸發的自動化全部被封鎖

原因。 事件觸發的自動化需要 PromptGuard 模型。若缺少它，每次事件執行都會被封鎖並顯示「PromptGuard model not installed — event triggers require it (download in Settings).」。這是刻意設計，而非錯誤。

修正。 從 提示注入 窗格安裝 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（App 可以替你開啟該面板）。透過通道時，對遠端客體的 ICMP ping 會在本機得到回應，確認的是路由，而不是客體是否存活。

回報錯誤

當您在 bromure.io 提交報告時，請提供足以讓維護者重現問題的資訊：

1. App 與映像檔版本——App 版本（在 About Bromure Agentic Coding 中）與 bromure-ac info 的輸出（基礎映像檔的版本戳記、大小與路徑）。
2. App 記錄——~/Library/Logs/BromureAC/bromure-ac.log（若問題始於上次啟動之前，另加 bromure-ac.log.1）。若維護者要求更多細節，請從終端機以 BROMURE_AC_DEBUG=1 重新啟動。
3. 相關紀錄——設定失敗時，附上拷貝的 主控台輸出；與安全相關的行為，則附上從安全性時間軸以 輸出… 匯出的已篩選 CSV。
4. 你預期的結果與實際發生的情況，以及機器當時是關閉、暫停還是執行中。

請勿附上真正的密鑰——追蹤紀錄與記錄行已經把它們截短為簡短預覽，而且 App 的設計讓真正的憑證從一開始就不會進入 VM。如果你的 Mac 已註冊到 bromure.io 工作區，請透過組織的管理者提交回報。註冊的說明請見企業版。