診斷代理
本指南說明如何找出代理不再產生執行的原因。
請由上而下排查：先看代理本身的執行，再看它的後端，接著是伺服器，最後是主機。
1. 檢查代理的執行歷史
標題為「1. 檢查代理的執行歷史」的章節設定 → 工作區 → 代理 → 選取該代理 → 日誌。
每次執行都會顯示狀態徽章、時長（進行中時顯示「Running…」）、開始與完成時間、PID，以及它所使用的配接器。檢視 會開啟該次執行的原始事件串流。停止 會終止正在執行的程序，並將該次執行標記為「Killed by user」；標題列中的 終止執行中 會對該代理所有進行中的執行做同樣的事。
解讀方式如下：
- 完全沒有執行 —— 派送從未發生。編輯器中的提及由
@加上單字字元（字母、數字、底線）組成。解析方式為與代理名稱做精確或前綴比對，因此@code-reviewer會被解析為code，仍可喚醒名為code-reviewer的代理。名稱中若有空格，就無法以單一詞彙被提及。接著請前往步驟 2。 - 一開始就因錯誤而結束的執行 —— 請開啟 檢視。後端啟動失敗會在此顯示為程序錯誤。
- 卡在「Running…」的執行 —— 請先停止它，再檢查該代理在 設定 分頁中的 靜音逾時。未設定逾時時，會使用各模式的預設值。
- 已完成但沒有實用輸出的執行 —— 對於未交出所宣告交付項目的執行，執行日誌的狀態仍會維持
completed；真正可信的訊號是摘要文字，而非徽章。
日誌分頁不會顯示成本。若要查看花費，請使用 可觀測性 → 洞察 中依代理劃分的表格。
2. 檢查代理的後端
標題為「2. 檢查代理的後端」的章節設定 → 伺服器 → 模型供應商（/settings/server/providers）。
已偵測的執行器 清單會顯示每個配接器及其探測結果 —— 已安裝的版本、「檢查中…」或「找不到」—— 以及解析出的路徑，和已找到 CLI 的能力標籤。點選頁面標題列中的 重新整理 即可重新探測。
探測是在代管 cc_server 的機器上執行，而不是在你正檢視的機器上。若你使用 Web 用戶端或已配對的裝置，「找不到」表示伺服器主機上缺少該 CLI。
有兩件事需要確認：
- 該代理究竟有沒有設定配接器。 配接器為空的代理會被派送至 Control Center (built-in)，執行日誌會記錄
cc-harness，因此逐字稿會寫明實際執行的是什麼。若連模型也未設定，它會向 Anthropic 要求其預設模型 —— 除非你已連接 Anthropic 帳號，否則會以No credential for provider "anthropic"失敗。預先植入的專家發布時都沒有配接器。 - 內建配接器有沒有模型。 它的模型清單會即時來自本頁下方已連接的供應商，因此沒有儲存憑證的供應商不會貢獻任何模型。
配接器目錄本身是固定的 —— 無法註冊新的配接器。你在此可以依配接器變更的是它的啟動參數與環境變數。請注意，在解析憑證時，依配接器設定的環境變數覆寫會無聲地壓過已連接的供應商帳號。
3. 檢查伺服器
標題為「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. 檢查主機
標題為「4. 檢查主機」的章節設定 → 伺服器 → 診斷與隱私（/settings/server/diagnostics）是主機層級的頁面。它包含：
- 沙盒 —— 主開關、偵測到的後端與安裝提示。只有偵測到的後端來自伺服器；請參閱下方的警告。這裡沒有重設控制項。
- 語意搜尋 —— 裝置端嵌入模型的生命週期：已安裝、下載中並顯示百分比、未安裝，或安裝錯誤。在它安裝完成之前，記憶與程式碼搜尋都僅限關鍵字。
- 系統行為 —— 代理執行時讓電腦保持喚醒。
- 日誌層級 —— 在重現故障之前先調高它。
- 隱私 —— 是否可將原始 diff 內容轉送給代理的模型，以及是否傳送當機報告。
常見故障
標題為「常見故障」的章節執行始終未開始，且配接器顯示「找不到」
標題為「執行始終未開始，且配接器顯示「找不到」」的章節請 在伺服器主機上 安裝該 CLI，然後在模型供應商頁面點選 重新整理。或將該代理切換到內建配接器（不需要任何 CLI），並在同一頁面連接一個供應商。
代理無法推送或建立 pull request
標題為「代理無法推送或建立 pull request」的章節看看 git 或代理印出了什麼。Control Center policy: … 表示某條動作規則拒絕了它，或某個核准沒有得到回應：在 設定 → 工作區 → 代理權限 中檢查推送到遠端與開啟 pull request。若 git 表示 Control Center 沒有能推送的 GitHub 憑證，請在該儲存庫上安裝 GitHub App，或連接 GitHub。
語意搜尋傳回不了有用的結果
標題為「語意搜尋傳回不了有用的結果」的章節檢查 設定 → 伺服器 → 診斷與隱私 → 語意搜尋。在嵌入模型安裝之前，搜尋僅限關鍵字。在模型安裝之前寫入的資料列永遠不會被回填，因此即使之後仍只能以關鍵字搜尋。
伺服器完全無法啟動
標題為「伺服器完全無法啟動」的章節原生程式庫是必要的，而且沒有降級模式。缺少某個 dylib 會讓 cc_server 拒絕啟動，並在錯誤中指明是哪一個。請使用 scripts/natives/build_natives.sh 暫存原生元件，然後重新建置伺服器二進位檔。
動作遭到無聲拒絕
標題為「動作遭到無聲拒絕」的章節在未連接任何核准者的情況下，prompt 護欄決定會被拒絕，這是刻意設計。請在 設定 → 工作區 → 代理權限 下檢查該工作區的規則。