配置

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

​

配置

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

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 定义：

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/