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