> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障排查

> 在 IDE 中運行 @hitheo/mcp 時的常見故障，附日誌特徵和修復方法。

大多數 MCP 配置故障都屬於以下幾類之一。每一節都給出你會看到的日誌特徵（在 IDE 的 MCP 面板或 stderr 中）以及對應的修復方法。

<Tip>
  在深入排查之前，先在啓動 IDE 的同一個 shell 中運行 `theo verify`。如果它失敗了，MCP 服務器也會以同樣的錯誤失敗——先修好宿主環境。
</Tip>

## 未設置 `THEO_API_KEY`

**特徵：**

```text theme={null}
[theo-mcp] ERROR: THEO_API_KEY environment variable is required.
  Get one at https://api.hitheo.ai → API Keys.
  Then set it: export THEO_API_KEY=theo_sk_...
```

服務器會立即以退出碼 1 退出，IDE 會顯示 "Theo MCP server failed to start" 或類似提示。

**修復：** 在啓動 IDE 的那個 shell 中導出密鑰，*而不是*在另一個終端裏：

```bash theme={null}
export THEO_API_KEY=theo_sk_live_a1b2c3...
```

在 macOS 上，從 Finder/Spotlight 啓動的 GUI 應用不會讀取 `~/.zshrc` 中的 `export` 語句。你可以：

1. 從導出了密鑰的同一個終端啓動 IDE，或者
2. 把該變量持久化到 GUI 會話能讀取到的地方（例如 macOS 應用啓動時用 `launchctl setenv THEO_API_KEY ...`），或者
3. 直接在 MCP 配置的 `env` 塊中內聯該值，而不是使用 `${env:THEO_API_KEY}`：

   ```json theme={null}
   "env": { "THEO_API_KEY": "theo_sk_live_a1b2c3..." }
   ```

   這樣做會把密鑰寫死進文件——對個人項目沒問題，但不適合共享倉庫。

## 寫入配置後 IDE 沒有重啓

**特徵：** 智能體完全看不到 `theo_*` 工具，也沒有任何關於 Theo 的 MCP 日誌行。

IDE 只在啓動時讀取 MCP 配置。在 IDE 已打開的情況下編輯 `.cursor/mcp.json`（或其他任何路徑）不會生效，直到你完全退出並重新打開。

**修復：** 完全退出 IDE（不只是關閉窗口），然後重新打開項目。

## `npx` 緩存卡在舊版本

**特徵：** 服務器能啓動、工具也出現了，但文檔中記錄的某個新版本功能表現得像不存在一樣。

`npx -y @hitheo/mcp` 會解析出最新版本，但只在該賬號首次運行時如此；後續啓動可能會複用緩存的副本，直到 `npm` 決定重新檢查。

**修復：** 清一次 npx 緩存：

```bash theme={null}
rm -rf ~/.npm/_npx
```

或者在 MCP 配置中固定具體版本：

```json theme={null}
"args": ["-y", "@hitheo/mcp@0.3.0"]
```

你可以通過運行 `theo status` 來確認實際啓動的是哪個版本——它的輸出中包含服務器所見的 API 版本，而 `npx -y @hitheo/mcp` 正是隨該版本一起發佈的。

## `THEO_BASE_URL` 引發的重定向導致 401

**特徵：**

```text theme={null}
[theo-mcp] Theo error: TheoApiError: 401 invalid_api_key
```

……即使在同一個 shell 中運行 `theo verify` 是成功的。

最常見的原因：環境中某處把 `THEO_BASE_URL` 設成了 `https://hitheo.ai`（頂級域名）。該頂級域名會 307 重定向到 `https://www.hitheo.ai`，而 Node 18 的 `fetch` 在 3xx 響應上會剝離 `Authorization` 請求頭，導致重定向後的請求變成未認證狀態到達服務器。

**修復：** 指向規範主機。可以：

* 取消設置該變量，讓 SDK 默認值（`https://www.hitheo.ai`）生效：

  ```bash theme={null}
  unset THEO_BASE_URL
  ```

* 或者顯式設置它：

  ```bash theme={null}
  export THEO_BASE_URL=https://www.hitheo.ai
  ```

完整說明見 [401 故障排查](/troubleshooting/401-errors)。

## `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 文件：

```bash theme={null}
which claude   # if empty, fall back to .mcp.json
```

如果兩者都存在，JSON 文件在項目內優先生效。刪除 `.mcp.json` 會讓 Claude Code 回退到全局註冊。

## Stdio 傳輸意外關閉

**特徵：**

```text theme={null}
MCP error: server connection closed
```

或者 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}` 被忽略

**特徵：**

```text theme={null}
[theo-mcp] Ignored theo.config.js: JS/TS config is disabled by default.
Set THEO_ALLOW_JS_CONFIG=1 to enable it (arbitrary code execution — only do
this in trusted directories). Use theo.config.json for safe config.
```

**修復：** 這是刻意的設計。要麼把你的配置轉換成 JSON，要麼通過 `THEO_ALLOW_JS_CONFIG=1` 主動開啓——且僅在你信任的目錄中這樣做。詳見[安全性](/mcp/security#the-json-only-config-sandbox)。

## 還是卡住了？

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.