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

# 安装 SDK

> 为 TypeScript 和 Node.js 项目配置 @hitheo/sdk。

## 安装

<CodeGroup>
  ```bash npm theme={null}
  npm install @hitheo/sdk
  ```

  ```bash yarn theme={null}
  yarn add @hitheo/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @hitheo/sdk
  ```
</CodeGroup>

**环境要求：** Node.js 18+，需支持原生 `fetch`。

## 初始化客户端

```typescript theme={null}
import { Theo } from "@hitheo/sdk";

const theo = new Theo({
  apiKey: process.env.THEO_API_KEY!,
  // 可选：
  // baseUrl: "https://www.hitheo.ai",   // 默认值（规范的 `www` 主机）
  // timeoutMs: 30_000,                  // 默认值
  // maxRetries: 2,                      // 默认值 — 在 429/5xx 时重试
});
```

## 配置选项

| 选项 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `apiKey` | `string` | **必填** | 你的 `theo_sk_...` API 密钥 |
| `baseUrl` | `string` | `https://www.hitheo.ai` | API 基础 URL（请始终指向 `www` —— 顶级域名会重定向，且部分 HTTP 客户端在 3xx 跳转时会剥离 `Authorization` 头） |
| `timeoutMs` | `number` | `30000` | 请求超时时间（毫秒） |
| `maxRetries` | `number` | `2` | 在 429/5xx 错误时的最大重试次数 |

## 重试行为

SDK 会在以下情况下自动重试：

* **429 请求过多** — 遵循 `Retry-After` 响应头
* **5xx 服务器错误** — 指数退避（1 秒、2 秒、4 秒，上限 8 秒）

客户端错误（400、401、403、404）不会被重试。

## 其他可用工具

### CLI

SDK 附带一个可在终端中使用的 CLI 工具：

```bash theme={null}
npm install -g @hitheo/sdk
theo init        # 在项目中配置 Theo
theo status      # 检查连接与健康状态（同时探测 apex 和 www）
theo verify      # 机器可读的 JSON 诊断结果（适合 CI 使用）
theo complete "What is quantum computing?"
```

完整命令请参见 [CLI 参考](/cli-reference/overview)。

### MCP 服务器 —— IDE 集成

通过 MCP 在 Cursor、Claude Code、Warp、Windsurf 和 VS Code 中使用 Theo：

First, set your API key as an environment variable:

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

Then pick your IDE:

<Tabs>
  <Tab title="Cursor">
    Add to `.cursor/mcp.json` in your project root:

    ```json theme={null}
    {
      "mcpServers": {
        "theo": {
          "command": "npx",
          "args": ["-y", "@hitheo/mcp"],
          "env": {
            "THEO_API_KEY": "${env:THEO_API_KEY}"
          }
        }
      }
    }
    ```

    Or run:

    ```bash theme={null}
    theo mcp install --ide cursor
    ```
  </Tab>

  <Tab title="Claude Code">
    Run this in your terminal:

    ```bash theme={null}
    claude mcp add theo npx -y @hitheo/mcp
    ```

    Or run:

    ```bash theme={null}
    theo mcp install --ide claude-code
    ```
  </Tab>

  <Tab title="Warp">
    Add to `.warp/mcp.json` in your project root:

    ```json theme={null}
    {
      "mcpServers": {
        "theo": {
          "command": "npx",
          "args": ["-y", "@hitheo/mcp"],
          "env": {
            "THEO_API_KEY": "${env:THEO_API_KEY}"
          }
        }
      }
    }
    ```

    Or run:

    ```bash theme={null}
    theo mcp install --ide warp
    ```
  </Tab>

  <Tab title="Windsurf">
    Add to `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "theo": {
          "command": "npx",
          "args": ["-y", "@hitheo/mcp"],
          "env": {
            "THEO_API_KEY": "${env:THEO_API_KEY}"
          }
        }
      }
    }
    ```

    Or run:

    ```bash theme={null}
    theo mcp install --ide windsurf
    ```
  </Tab>

  <Tab title="VS Code">
    Add to `.vscode/mcp.json` in your project root:

    ```json theme={null}
    {
      "mcpServers": {
        "theo": {
          "command": "npx",
          "args": ["-y", "@hitheo/mcp"],
          "env": {
            "THEO_API_KEY": "${env:THEO_API_KEY}"
          }
        }
      }
    }
    ```

    Or run:

    ```bash theme={null}
    theo mcp install --ide vscode
    ```
  </Tab>

  <Tab title="All IDEs">
    Auto-detect and configure all installed IDEs at once:

    ```bash theme={null}
    npm install -g @hitheo/sdk
    theo init
    ```

    This detects Cursor, Claude Code, Warp, Windsurf, and VS Code, writes the correct config for each, and creates a `theo.config.json` for project-level settings.
  </Tab>
</Tabs>

Restart your IDE after adding the config.


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