診斷代理

本指南說明如何查明某個代理為何不再產生執行。

請由上而下排查：先看代理自身的執行，再看它的後端，接著是伺服器，最後是主機。

1. 檢查代理的執行紀錄

設定 → 工作區 → 代理 → 選擇該代理 → 日誌。

每筆執行都會顯示狀態徽章、時長（進行中時顯示「Running…」）、開始與完成時間、PID，以及它所使用的配接器。檢視會開啟該筆執行的原始事件串流。停止會終止正在執行的程序，並把該筆執行標記為「Killed by user」；頁首的 終止執行中 會對該代理所有仍在進行中的執行做同樣的事。

可以這樣解讀：

完全沒有執行——派發從未發生。編輯器中的提及由 @ 加上單詞字元（字母、數字、底線）組成。解析方式是與代理名稱做完全相符或前綴比對，因此 @code-reviewer 會被解析成 code，仍可喚醒名為 code-reviewer 的代理。名稱中若有空格，就無法以單一詞元被提及。這時請前往第 2 步。
一開始就報錯結束的執行——開啟檢視。啟動後端失敗會在這裡顯示為程序錯誤。
卡在「Running…」的執行——先停止它，再檢查該代理在設定分頁中的 靜音逾時。逾時未設定時，會採用各模式的預設值。
已完成卻沒有可用輸出的執行——對於未交出所聲明交付項目的執行，執行日誌的狀態仍會停留在 completed；可信的訊號是摘要文字，而不是徽章。

日誌分頁不會顯示成本。要查看支出，請使用 可觀測性 → 洞察 中按代理劃分的表格。

2. 檢查代理的後端

設定 → 伺服器 → 模型供應商（/settings/server/providers）。

已偵測的執行器清單會顯示每個配接器及其探測結果——已安裝的版本、「檢查中…」或「找不到」——以及解析出的路徑，和為已找到的 CLI 顯示的能力標籤。按一下頁首的 重新整理 即可重新探測。

探測是在託管 cc_server 的那部機器上執行，而不是在你正看著的這部機器上。如果你使用的是 Web 用戶端或已配對的裝置，「找不到」意味著伺服器主機上缺少該 CLI。

有兩件事要確認：

該代理到底有沒有設定配接器。 配接器為空的代理會被派發到 Control Center (built-in)，執行日誌會記錄 cc-harness，因此逐字稿會列明實際執行的是什麼。若連模型也沒有，它會向 Anthropic 要求其預設模型——除非你已連接 Anthropic 帳戶，否則會以 No credential for provider "anthropic" 失敗。預置的專家代理出廠時都沒有配接器。
內建配接器有沒有模型。 它的模型清單即時來自本頁下方已連接的供應商，因此沒有儲存憑證的供應商不會貢獻任何模型。

配接器目錄本身是固定的——無法註冊新的配接器。你在此可以逐個配接器更改的是它的啟動參數與環境變數。請注意，在解析憑證時，按配接器設定的環境變數覆寫會靜默地壓過已連接的供應商帳戶。

3. 檢查伺服器

設定 → 伺服器 → 連線與狀態（/settings/server/connection）會顯示此用戶端正在與哪部伺服器通訊，以及它報告了什麼。

對於無介面伺服器，GET /healthz 不需用戶端就能提供同樣的資訊。它按設計不要求驗證，並且對 CORS 開放：

curl http://localhost:9030/healthz

它會傳回伺服器的狀態、以秒計的運作時間、即時連線數、繫結的連接埠、建置版本與 git SHA、工作區 schema 版本、RPC 目錄版本、伺服器 id、名稱與身分指紋、繫結是否不安全，以及一個帶有 watching / indexing / pending 計數的 codeGraph 區塊。當某個快取有過流量時，它也會包含一個 caches 區塊；示範伺服器會加上 demo: true。

當某項改動「在測試裏行得通，在應用程式裏卻不行」時，有兩件事值得了解：

桌面應用程式會優先啟動 預先建置 的 cc_server 二進位檔，而不是原始碼。新的 RPC 操作或 MCP 工具要等到二進位檔重新建置後才會出現，而當子程序的 git SHA 與應用程式的不一致時，開機日誌會記錄一則警告。
若衍生出的伺服器未在 20 秒內印出就緒橫幅，桌面應用程式會將它終止，並退回錯誤畫面。

4. 檢查主機

設定 → 伺服器 → 診斷與隱私（/settings/server/diagnostics）是主機層級的頁面。它包含：

沙箱——總開關、偵測到的後端與安裝提示。只有偵測到的後端來自伺服器；請參閱下方的注意事項。這裡沒有重設控制項。
語意搜尋——本機嵌入模型的生命週期：已安裝、下載中並顯示百分比、未安裝，或安裝失敗。在它安裝之前，記憶與程式碼搜尋一直只靠關鍵字。
系統行為——代理執行時保持電腦喚醒。
日誌層級——在重現失敗之前先把它調高。
隱私——原始 diff 內容可否轉送給代理的模型，以及是否傳送當機報告。

偵測與強制執行如今已經一致：凡偵測器回報有原生後端的主機，該主機上的代理執行確實會被包裹在其中。但偵測器是這一節裏唯一即時生效的東西。總開關與後端選擇器都是儲存在你裝置上的偏好設定，伺服器一個都不會讀取——伺服器自己的開關是 --sandbox（預設 on，用 off 主動退出）。

因此這裡的警告值得處理，不過它通常不是代理失敗的原因。要確認伺服器處於哪種狀態，請讀它的啟動日誌：它會印出 agent sandbox ON 並附上後端說明、no OS-native agent sandbox on this host 並附上安裝提示，或 agent sandbox DISABLED by --sandbox off。GET /healthz 不帶任何沙箱欄位。

在沒有後端的地方——Windows 一向如此，以及缺少 bwrap 與 socat 的 Linux 或 WSL2——執行不會被沙箱包裹，約束它們的是對話自身的檢出、唯讀的程式碼託管權杖與推送閘道、操作護欄、環境清理，以及它的模式所允許的工具集。

常見故障

執行始終不開始，而配接器顯示「找不到」

請在伺服器主機上安裝該 CLI，然後在模型供應商頁面按一下 重新整理。或者把該代理切換到內建配接器——它不需要任何 CLI——並在同一頁面連接一個供應商。

代理無法推送或建立 pull request

看看 git 或代理印出了甚麼。Control Center policy: … 表示某條動作規則拒絕了它，或某個核准沒有得到回應：在 設定 → 工作區 → 代理權限 中檢查推送到遠端與開啟 pull request。若 git 表示 Control Center 沒有能推送的 GitHub 憑證，請在該程式庫上安裝 GitHub App，或連接 GitHub。

語意搜尋找不出有用的結果

檢查 設定 → 伺服器 → 診斷與隱私 → 語意搜尋。在嵌入模型安裝之前，搜尋只靠關鍵字。在模型安裝之前寫入的資料列永遠不會被回填，因此即使日後安裝了，它們仍然只靠關鍵字。

伺服器完全無法啟動

原生程式庫是必需的，而且沒有降級模式。缺少某個 dylib 會令 cc_server 拒絕啟動，並在錯誤中指名缺失的那一個。請用 scripts/natives/build_natives.sh 暫存原生組件，然後重新建置伺服器二進位檔。

某項操作被靜默拒絕

在未連接任何審批人的情況下，prompt 護欄決定會被拒絕，這是刻意如此。請在 設定 → 工作區 → 代理權限 下檢查該工作區的規則。