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

# 项目配置 (defineConfig)

> 为项目配置 Theo，使用带类型的设置项。

<Note>
  本页是 SDK 辅助工具的说明。要了解完整的模式定义、合并语义以及仅支持 JSON 的沙箱设计理由，请参阅 [MCP / 项目配置](/mcp/project-config)。
</Note>

## `defineConfig(config)`

创建一个带类型的 `TheoProjectConfig`，用于 `theo.config.ts`。MCP 服务器会自动读取该配置。

```typescript theme={null}
// theo.config.ts
import { defineConfig } from "@hitheo/sdk";

export default defineConfig({
  persona: "You are Nova, an operations assistant for WarehouseOS.",
  skills: ["inventory-check", "data-extraction"],
  defaultMode: "auto",
  tools: [
    {
      name: "check_stock",
      description: "Look up current stock levels for a SKU",
      input_schema: {
        type: "object",
        properties: { sku: { type: "string" } },
        required: ["sku"],
      },
    },
  ],
  temperature: 0.7,
  metadata: { team: "warehouse-ops" },
});
```

## TheoProjectConfig

| 字段 | 类型 | 说明 |
| - | - | - |
| `persona` | `string` | 用于每次补全请求的自定义系统提示词 |
| `skills` | `string[]` | 每次请求都会激活的技能 slug |
| `defaultMode` | `ChatMode` | 默认执行模式 |
| `tools` | `ToolDef[]` | 内联工具定义 |
| `temperature` | `number` | 默认温度 |
| `metadata` | `Record<string, unknown>` | 附加到每个请求上的元数据 |

## 文件格式

MCP 服务器默认优先使用 **JSON** 配置：

1. `theo.config.json` — 存在时始终会被加载（安全：使用 `JSON.parse` 解析）。
2. `theo.config.js` / `theo.config.ts` — **默认会被忽略。** 加载这些文件会执行当前工作目录中的任意代码，当 IDE 在一个你并不完全信任的项目中启动 MCP 服务器时，这是不安全的。

若要重新启用 JS/TS 配置加载，请在启动 MCP 服务器之前设置一个环境变量：

```bash theme={null}
export THEO_ALLOW_JS_CONFIG=1
```

设置该标志后，服务器会先加载 `theo.config.js`，再加载 `theo.config.ts`，最后才回退到 `theo.config.json`。如果在未设置该标志的情况下发现了 JS/TS 配置文件，MCP 服务器会记录一条警告日志并跳过该文件。

<Warning>
  仅在你自己编写或信任的目录中启用 `THEO_ALLOW_JS_CONFIG=1`。任何包含恶意 `theo.config.js` 的仓库，都可能在 MCP 服务器启动时在你的 shell 会话中执行任意代码。
</Warning>

## 工作原理

当 `@hitheo/mcp` 服务器启动时，它会：

1. 从环境变量中读取 `THEO_API_KEY`
2. 加载 `theo.config.json`（如果已启用，也可加载 JS/TS 配置）
3. 将 `persona`、`skills` 和 `tools` 注入到每一次 MCP 工具调用中
4. 使用 `defaultMode` 作为回退模式


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