> ## 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.