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

# 配置

> 使用 YAML、TypeScript 和环境变量配置 Runtime。

# 配置

Runtime 默认读取 `agents.yaml`，也支持 `agent.config.ts`。YAML 适合部署生成与静态配置；TypeScript 适合需要代码组合的场景。两者同时存在时，`agent.config.ts` 优先于 `agents.yaml`。

```yaml theme={null}
agents:
  - id: researcher
    name: Research Assistant
    model: claude-sonnet-4-6
    systemPromptFile: ./prompts/researcher.md
    maxTurns: 10
    maxSessionTurns: 50
    allowedTools: [WebFetch, WebSearch, Read]

  - id: coder
    model: claude-sonnet-4-6
    systemPromptFile: ./prompts/coder.md
    maxTurns: 20
    allowedTools: [Bash, Read, Write, Edit]
    mcpServers:
      github:
        transport: stdio
        command: mcp-server-github
        args: ["--owner", "myorg"]
    datasets:
      docs: Internal knowledge base for the project
```

`systemPrompt` 与 `systemPromptFile` 互斥。相对文件路径以配置目录为基准。

## Agent 字段

| 字段                   | 必填 | 默认值                 | 说明                                                                                                                   |
| -------------------- | -- | ------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `id`                 | 是  | —                   | 唯一标识，用于 API 路由                                                                                                       |
| `name`               | 否  | —                   | 展示名称                                                                                                                 |
| `model`              | 否  | `claude-sonnet-4-6` | LLM 模型名                                                                                                              |
| `systemPrompt`       | 否  | —                   | 内联 system prompt                                                                                                     |
| `systemPromptFile`   | 否  | —                   | `.md` 文件路径（相对配置目录）                                                                                                   |
| `maxTurns`           | 否  | `10`                | 单次 Agent loop 最大轮数                                                                                                   |
| `maxSessionTurns`    | 否  | 不限                  | 发送给 LLM 的最大对话轮数（上下文窗口）                                                                                               |
| `allowedTools`       | 否  | 全部工具                | 工具名白名单                                                                                                               |
| `disallowedTools`    | 否  | —                   | 工具名黑名单                                                                                                               |
| `settingSources`     | 否  | —                   | 扫描哪些 Skill 目录：`user`（`~/.openagent/skills/`）、`project`（`<cwd>/.openagent/skills/`）、`local`（无操作）。扫描到的 Skill 全部暴露，无白名单 |
| `extraUserSkillDirs` | 否  | —                   | 额外的 user 级 Skill 目录（在默认目录之后扫描）                                                                                       |
| `mcpServers`         | 否  | —                   | MCP server 配置                                                                                                        |
| `permissionMode`     | 否  | `default`           | 权限策略：`default`、`acceptEdits`、`bypassPermissions`、`plan`、`dontAsk`、`auto`                                             |
| `subagents`          | 否  | —                   | 供 `Task` 工具使用的 Subagent 定义                                                                                           |
| `datasets`           | 否  | —                   | dataset-id 到描述的映射，以 `<datasets>` 块注入 system prompt                                                                   |

## Subagent 字段

Subagent 定义在 Agent 的 `subagents` 键下：

| 字段                | 必填 | 默认值       | 说明                                   |
| ----------------- | -- | --------- | ------------------------------------ |
| `description`     | 是  | —         | 展示给父 Agent 的简短描述                     |
| `prompt`          | 是  | —         | Subagent 的 system prompt             |
| `tools`           | 否  | 全部工具      | 工具名白名单                               |
| `disallowedTools` | 否  | —         | 工具名黑名单                               |
| `model`           | 否  | 继承父 Agent | LLM 模型名                              |
| `mcpServers`      | 否  | —         | MCP server 名称或 `{ name, tools? }` 对象 |
| `maxTurns`        | 否  | `10`      | 单次 Agent loop 最大轮数                   |

## TypeScript 模式（agent.config.ts）

TypeScript 配置通过 `defineConfig` 导出，可在代码中组合 SDK 的 Tool 定义：

```typescript theme={null}
import { defineConfig } from "@zerone-agent/agent-runtime";
import { defineTool } from "@zerone-agent/agent-sdk";

const weatherTool = defineTool({
  name: "GetWeather",
  description: "Get weather for a city",
  inputSchema: {
    type: "object" as const,
    properties: { city: { type: "string" } },
    required: ["city"],
  },
  isReadOnly: () => true,
  isConcurrencySafe: () => true,
  async call(input: { city: string }) {
    return `${input.city}: 22°C, partly cloudy`;
  },
});

export default defineConfig({
  server: { port: 3000 },
  agents: [
    {
      id: "smart",
      model: "claude-sonnet-4-6",
      systemPrompt: "You are a smart assistant with weather and calculator tools.",
      maxTurns: 15,
      allowedTools: ["Bash", "Read", "Write", "Edit"],
    },
  ],
});
```

## 配置发现顺序

Runtime 按以下顺序查找配置：

1. `--config <path>` CLI 参数
2. 配置目录中的 `agent.config.ts`
3. 配置目录中的 `agents.yaml`
4. 当前工作目录
5. `~/.openagent/`