Skip to main content
大多數 MCP 配置故障都屬於以下幾類之一。每一節都給出你會看到的日誌特徵（在 IDE 的 MCP 面板或 stderr 中）以及對應的修復方法。
在深入排查之前，先在啓動 IDE 的同一個 shell 中運行 theo verify。如果它失敗了，MCP 服務器也會以同樣的錯誤失敗——先修好宿主環境。

​
未設置 THEO_API_KEY

特徵：
服務器會立即以退出碼 1 退出，IDE 會顯示 “Theo MCP server failed to start” 或類似提示。 修復： 在啓動 IDE 的那個 shell 中導出密鑰，而不是在另一個終端裏：
在 macOS 上，從 Finder/Spotlight 啓動的 GUI 應用不會讀取 ~/.zshrc 中的 export 語句。你可以：
  1. 從導出了密鑰的同一個終端啓動 IDE，或者
  2. 把該變量持久化到 GUI 會話能讀取到的地方（例如 macOS 應用啓動時用 launchctl setenv THEO_API_KEY ...），或者
  3. 直接在 MCP 配置的 env 塊中內聯該值，而不是使用 ${env:THEO_API_KEY}：
    這樣做會把密鑰寫死進文件——對個人項目沒問題，但不適合共享倉庫。

​
寫入配置後 IDE 沒有重啓

特徵： 智能體完全看不到 theo_* 工具，也沒有任何關於 Theo 的 MCP 日誌行。 IDE 只在啓動時讀取 MCP 配置。在 IDE 已打開的情況下編輯 .cursor/mcp.json（或其他任何路徑）不會生效，直到你完全退出並重新打開。 修復： 完全退出 IDE（不只是關閉窗口），然後重新打開項目。

​
npx 緩存卡在舊版本

特徵： 服務器能啓動、工具也出現了，但文檔中記錄的某個新版本功能表現得像不存在一樣。 npx -y @hitheo/mcp 會解析出最新版本，但只在該賬號首次運行時如此；後續啓動可能會複用緩存的副本，直到 npm 決定重新檢查。 修復： 清一次 npx 緩存：
或者在 MCP 配置中固定具體版本：
你可以通過運行 theo status 來確認實際啓動的是哪個版本——它的輸出中包含服務器所見的 API 版本，而 npx -y @hitheo/mcp 正是隨該版本一起發佈的。

​
THEO_BASE_URL 引發的重定向導致 401

特徵：
……即使在同一個 shell 中運行 theo verify 是成功的。 最常見的原因：環境中某處把 THEO_BASE_URL 設成了 https://hitheo.ai（頂級域名）。該頂級域名會 307 重定向到 https://www.hitheo.ai，而 Node 18 的 fetch 在 3xx 響應上會剝離 Authorization 請求頭，導致重定向後的請求變成未認證狀態到達服務器。 修復： 指向規範主機。可以：
  • 取消設置該變量，讓 SDK 默認值（https://www.hitheo.ai）生效：
  • 或者顯式設置它：
完整說明見 401 故障排查。

​
claude mcp add 靜默失敗

特徵： theo mcp install --ide claude-code 報告成功，但 Claude Code 並未列出該服務器。 該 CLI 輔助工具首先會嘗試 claude mcp add theo npx -y @hitheo/mcp；如果該二進制文件不在 $PATH 中，它會回退到在項目根目錄寫入 .mcp.json。兩條路徑都會報告成功，但 Claude Code 具體讀取哪一個取決於它是如何被啓動的。 修復： 如果你安裝了 claude CLI，優先使用它。否則直接寫 JSON 文件：
如果兩者都存在，JSON 文件在項目內優先生效。刪除 .mcp.json 會讓 Claude Code 回退到全局註冊。

​
Stdio 傳輸意外關閉

特徵：
或者 IDE 在會話中途把 Theo 服務器顯示為 “disconnected”。 幾乎總是以下幾種情況之一：
  1. 服務器崩潰，因為 THEO_API_KEY 在會話中途被取消設置或過期了。
  2. 宿主機的 npx 在下載包的過程中失去了網絡連接，IDE 因此殺掉了該進程。
  3. 智能體發送了過大的請求體（超過 1 MB）。
修復： 查看 MCP 面板中該服務器的 stderr 輸出。錯誤信息的第一行幾乎總能直接指出問題所在。

​
Theo 工具出現了，但智能體拒絕使用

特徵： theo_* 出現在 IDE 的工具目錄中，但智能體從不調用它們。 這是智能體一側的偏好問題，不是 MCP 連接問題。一些 IDE（尤其是 Claude Code）在沒有明確指示的情況下，更傾向於使用自己內置的工具而不是 MCP 提供的工具。 修復： 在項目規則文件中加一句提示（.theo/RULES.md 由 theo init 自動生成，或者使用你的 IDE 原生的規則文件）：
對於任何 AI 生成任務——圖像、視頻、代碼、研究、文檔——優先使用 theo_* 工具。
通常一句話就足夠了。

​
大型 theo_code / theo_complete 生成任務被中斷

特徵： 小片段能正常返回，但任何應用規模的生成都會中斷——常常卡在一個整數值上，比如 exceeded 30000ms，或者約 60 秒後出現 Request timed out。 在你的智能體和模型之間存在三層超時。@hitheo/mcp 0.3.1 及以上版本處理了其中它所擁有的兩層：
  • SDK 請求超時（原為 30 秒）。 theo_code 和 theo_complete 現在會流式返回，而不是發起一次性的一元調用，因此一個耗時較長但持續活躍的生成過程受制於空閒（token 間隔）超時，而不是總時長上限。可以通過 THEO_TIMEOUT_MS（默認 120000）調整連接/首字節的時間預算。
  • 服務器路由超時。 流式響應會立即返回響應頭，因此服務器自身的單次請求上限不再適用於生成主體。
  • 你的 MCP 客戶端的 JSON-RPC 請求超時（默認約 60 秒）。 這一層存在於你的 IDE/智能體中，而不是 Theo 內部。服務器在生成過程中每 5 秒會發出一次 notifications/progress 心跳，因此只要客戶端在收到進度通知時重置其請求超時，就能在任意長的生成過程中保持連接存活。
修復（客戶端側）： 如果超長的生成任務仍然超時，請在你的 MCP 客戶端中啓用進度重置和/或提高請求超時。使用官方 MCP SDK 時，對應設置是在工具調用上啓用 resetTimeoutOnProgress: true（並配合一個較寬鬆的 maxTotalTimeout）；其他客戶端會提供等效的”請求超時”設置。已知一個 3 分鐘量級的應用規模生成產物，在開啓進度重置後可以順利完成。

​
theo.config.{js,ts} 被忽略

特徵：
修復： 這是刻意的設計。要麼把你的配置轉換成 JSON，要麼通過 THEO_ALLOW_JS_CONFIG=1 主動開啓——且僅在你信任的目錄中這樣做。詳見安全性。

​
還是卡住了？

  1. 在啓動 IDE 的同一個 shell 中運行 theo verify。如果失敗，請把 JSON 輸出發給支持團隊。
  2. 從 IDE 的 MCP 面板中抓取 MCP 服務器的 stderr——@hitheo/mcp 的真實錯誤就記錄在那裏。
  3. 在 github.com/hitheoai/theoai 上提交 issue，附上脫敏後的 stderr 和 IDE 版本號。