Agent 配置

Agent profile 决定 Agent 的工作方式和工具集。North Coder 内置以下 profile：

为 Profile 指定默认模型

建议为每个 profile 设置默认模型：在设置页选中一个 profile 后，为它指定对应的 LLM Profile。这样切换 Agent Profile 时会自动使用匹配的模型，无需每次手动切换。典型搭配：

• General profile → GPT、Claude 或 N2-Pro 等 coding LLM Profile
• RFC / Plan profile → 与其职责匹配的 LLM Profile

内置子 Agent

设置页的「子 Agent」面板用于为每个子 Agent 单独指定模型。默认情况下子 Agent 跟随主 Agent 使用的模型，但你可以覆盖为其他 LLM Profile。

North Coder 默认由 root 直接执行，不会为普通搜索、简单修改或严格顺序任务主动启动 Worker。需要委派时可以为 Worker 指定独立模型；未指定则跟随主 Agent。

这里的模型覆盖用于 North Coder 内置或原生子 Agent。下面介绍的 TOML Agent 使用文件中的 model，不会读取这个旧的模型覆盖设置。

用 TOML 自定义 Agent

North Coder 兼容 Codex 的 standalone Agent TOML：一个 .toml 文件定义一个具名 Agent。定义既适用于主 Agent 发起的普通子 Agent 委派，也适用于 Workflow 里的 agent()；两种入口按同一个 name 查找，使用同一份 instructions、模型、sandbox、MCP 和 skills 配置。

• 普通委派指定 reviewer，会选择 name = "reviewer" 的定义。
• Workflow 使用 agent(prompt, { name: "reviewer" })，会选择同一个定义。
• Workflow 省略 name 时使用 North Coder 内置 Worker。
• 如果显式指定 name: "worker" 且存在同名导入定义，则使用导入的 worker，不是省略名称时的内置 Worker。
• 名称精确匹配；名称不存在、已禁用或配置不可用时直接报错，不会回退到其他 Agent。
• Workflow 创建的子 Agent 仍可调用普通 Agent，但 Workflow 工具本身只向根 Agent 开放，子 Agent 不能继续启动 Workflow。

配置全局或项目 Agent

North Coder 专用配置优先放在 .north-coder；希望同一份 Agent 被其他兼容工具复用时，放在通用的 .agents。已有 Codex 配置可以继续使用 .codex，无需迁移。

CODEX_HOME 未设置时默认为 ~/.codex。Windows 下 ~ 对应 %USERPROFILE%。服务器模式读取的是服务器上运行 North Coder 的系统用户目录，不是浏览器所在电脑的目录。

standalone Agent 文件不需要额外控制文件。只有需要 [agents] 全局控制或 Codex 的声明式 config_file 时，才使用 $CODEX_HOME/config.toml 或项目 .codex/config.toml；North Coder 当前不会把 .north-coder/config.toml 或 .agents/config.toml 当作 Codex 控制文件读取。例外是显式把 CODEX_HOME 指向其中某个目录，此时该目录会作为 Codex 配置根处理。

项目定义覆盖全局定义；从项目根到当前执行目录的每一层都会参与解析，越接近执行目录优先级越高。同一目录层级中，.north-coder 高于 .codex，.codex 高于 .agents。Agent 的身份由 TOML 中的 name 决定，不是文件名。

同一层中，config.toml 声明先于目录扫描文件；同名定义保留先发现的一个。高优先级定义即使无效也会遮蔽低优先级定义，不会自动回退。高层定义覆盖低层定义时只可能补用低层的 description 和 nickname_candidates，不会合并 instructions、模型、sandbox、MCP 或 skills。

项目 TOML 会在下一轮主 Agent 开始执行时自动生效，不额外弹出“信任配置”确认。项目定义的 MCP 命令会在对应 Agent 首次启动时执行，因此只应运行可信项目中的配置。

最小可用配置

创建 .agents/agents/reviewer.toml：

name = "reviewer"
description = "检查代码正确性、安全风险和缺失测试。"
developer_instructions = """
只做代码审查，不修改文件。
先报告会影响行为的问题，并给出文件和行号证据。
忽略纯格式偏好。
"""

model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

独立使用的 standalone 文件应提供非空的 name、description 和 developer_instructions。model 是模型的原始 ID；如果不配置，先使用 [agents].default_subagent_model，仍未配置时才跟随直接父 Agent。

通过 config.toml 声明 Agent

目录扫描已经足够发现 TOML。只有需要把名称、说明和配置文件分开时，才需要在全局或项目 .codex/config.toml 中声明：

[agents]
enabled = true
max_concurrent_threads_per_session = 8
default_subagent_model = "gpt-5.6-terra"
default_subagent_reasoning_effort = "medium"

[agents.reviewer]
description = "检查代码正确性、安全风险和缺失测试。"
config_file = "agents/reviewer.toml"

config_file 相对声明它的 config.toml 解析，并且允许通过 .. 指向声明目录之外的文件。声明表只放 description、config_file 和可选的 nickname_candidates；模型、instructions、MCP 和 skills 等行为配置应放进引用的 Agent 文件。不要在 standalone Agent 文件中使用 config_file，该位置目前会被接受但不产生行为。

[agents] 支持以下全局控制：

[agents] 中其他未知标量不会被忽略，而会阻止根 Agent 启动。嵌套的 [agents.<name>] 是 Agent 声明表，只支持 description、config_file 和 nickname_candidates。

Agent TOML 字段

模型配置的优先级是：直接父 Agent → [agents] 默认值 → Agent 文件。Agent 文件只覆盖 model 时，会保留前一步已解析的推理强度。North Coder 当前不会预检 model/effort 组合；不受模型支持时，通常由 provider 在首次模型请求时返回错误。TOML 中的 model 不会按名称查找 North Coder 的 LLM Profile。

sandbox_mode = "read-only" 当前通过 capability 和工具白名单实施，只保留文件读取、搜索、目录列举和允许的委派工具。workspace-write 尚无独立子 Agent sandbox：父链原本可写时会返回 AGENT_SANDBOX_UNSUPPORTED，父链已经只读时仍按只读运行。danger-full-access 只是兼容解析，不会解除父链、当前 Mode 或宿主的硬限制。

这里的 sandbox 不是父 Agent 权限配置的完整复制。宿主 read-only 和 Plan/Test Mode 的硬限制会保留，但父 Agent 中普通 Ask 或具体 deny 规则不保证原样继承；不要依赖 Agent TOML 复刻完整的交互审批策略。

为 Agent 配置 MCP

每个导入 Agent 只获得自己 TOML 中声明的 MCP；不会自动继承主 Agent、全局设置或 plugin 的 MCP。没有 [mcp_servers] 就表示该 Agent 没有 MCP。连接会延迟到这个 Agent 真正启动时建立。

STDIO 示例：

[mcp_servers.repo]
command = "repo-mcp"
args = ["--stdio"]
cwd = "."
env_vars = ["GITHUB_TOKEN"]
enabled = true
required = false
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled_tools = ["search", "read_file"]
disabled_tools = ["delete_file"]

HTTP 示例：

[mcp_servers.docs]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "DOCS_MCP_TOKEN"
required = false

当前所有 MCP transport 都无法证明符合子 Agent 的 read-only 限制。因此 read-only Agent 不会挂载任何 MCP：可选 MCP 会在启动时跳过并记录诊断，required = true 的 MCP 会阻止 Agent 启动。设置页的静态预览仍可能把这类 MCP 显示为配置可用。

为 Agent 选择 skills

导入 Agent 的 skill 集合默认是空的，不继承主 Agent 的 skills。使用 [[skills.config]] 逐项启用：

[[skills.config]]
name = "code-review"
enabled = true

[[skills.config]]
path = "../skills/project-check/SKILL.md"
enabled = true

在 .agents/agents/reviewer.toml 中，上例的相对路径对应 .agents/skills/project-check/SKILL.md。

每条规则必须且只能提供 name 或 path 之一，并且必须提供布尔值 enabled。相对 path 从 Agent TOML 所在目录解析，必须直接指向 SKILL.md，不能只写目录，也不能借此引入尚未被 North Coder 发现的任意文件。enabled = true 找不到匹配项会使 Agent 不可用；enabled = false 用于移除前面已选中的匹配项，找不到匹配项时只记录无影响诊断。同名 skill 同时被选中会产生歧义并使 Agent 不可用，应改用 path 精确选择。

North Coder 会从当前执行目录、workspace 祖先、用户目录、已启用 plugin 和内置 skills 建立候选集。其中 .agents/skills、.codex/skills 等兼容目录会参与发现；workspace 祖先层目前只补查 .agents/skills 和 .codex/skills。导入 Agent 仍然只获得自己通过 [[skills.config]] 明确选中的候选。

skills.include_instructions 目前只会被解析和写入配置快照，不会改变运行时行为，不建议依赖。skills.bundled、skills.max_context_tokens 和其他未知的 skills 字段当前不支持，并会使 Agent 不可用。

生效时间和诊断

North Coder 在主 Agent 每一轮开始时读取配置并冻结快照。当前正在执行的子 Agent、后台 Agent 和 Workflow 后续步骤继续使用这一轮的旧快照；修改 TOML 后，新一轮才会读取新配置。

在「设置 → 子 Agent → 有效目录」中可以查看：

• 下一轮预览和当前运行中的快照。
• Agent 来自全局还是项目，以及最终选中的文件。
• 模型继承、MCP/skill 声明和静态可用状态。
• 无效字段、同名覆盖等定义级诊断。

设置页预览只做只读的静态 TOML 解析，不会绑定环境变量、验证 skill 是否命中候选、检查 model/effort 兼容性、实施 workspace-write 或连接 MCP。因此 available 只表示定义通过静态解析，不保证实际运行成功。MCP 连接结果等运行时诊断目前也不会回写为静态目录状态。

参考：Codex Subagents、Codex config.toml reference。

上下文压缩模型

「子 Agent」面板下方还有 上下文压缩模型 设置——当会话过长需要压缩历史时使用的模型。同样默认跟随主 Agent，也可以指定一个更快或更便宜的模型，避免长对话压缩时阻塞主流程。