子代理
当一个任务能被干净地切分——可并行的编辑、机械重复的改动、或只读的调查——主代理可以通过 task 工具把子任务交给短生命周期的子代理。每个子代理在自己独立的上下文里运行；跨文件的推理和最终结果仍由主代理掌控。task 工具默认开启。
两种子代理
| 类型 | 能做什么 |
|---|---|
| explore 探索 | 只读调查——读取、搜索代码库来回答「在哪 / 怎么做」，返回结论。不能改文件。 |
| worker 执行 | 执行一个被精确指定的改动。可自由读取，但写入被限制在声明的 scope 范围内。 |
它们如何运行
- 子代理并行运行，同时最多
max_concurrent个，各自独立上下文。 - 每个子任务带一个难度：
simple路由到你的快速模型，hard路由到能力更强的模型——依据你所配置各 provider 的capable_model档位来选。只有单个 provider 时，子代理使用当前模型。 - 主代理在继续前会审阅每个结果——子代理提议，主代理定夺。
Worker 范围与安全
worker 子任务必须声明一个 scope：一组相对工作目录、允许写入的 glob，例如 ["src/auth/**", "Cargo.toml"]。这是强制的，不是建议：
- 范围之外的写入（
edit_file、write_file、search_replace）会被 WorkerScopeGate 直接拒绝——不弹审批。 - 读取和
bash不受范围限制。 - 只要一次派发里含有
worker，就被视为 Risky 操作，会先走审批并展示各自的范围。 - 多个 worker 同时跑时，给它们互不重叠的范围，避免相互覆盖。
配置
在 ~/.atomcode/config.toml 中调整子代理池：
[subagent]
max_concurrent = 3 # 同时并行的子代理数（最小 1）
max_rounds = 0 # 每个子任务的模型轮次上限（0 = 不限）默认不限制子任务轮数；已有配置中的正数预算会保留。要取消旧的 200 轮限制，请设置 [subagent] max_rounds = 0，或使用环境变量 ATOMCODE_SUBAGENT_MAX_ROUNDS=0。正数预算耗尽时最多增加一次纯文本收尾；并发数、取消和重复调用保护独立生效。外部 Codex/Claude 子代理使用各自的运行策略。
| 键 | 默认 | 含义 |
|---|---|---|
max_concurrent | 3 | 并行运行的子代理数 |
max_rounds | 0 | 每个子任务的模型轮次上限；0 = 不限 |
环境变量覆盖：ATOMCODE_SUBAGENT_MAX_ROUNDS 优先于配置值。
自定义团队角色
团队（team）派活时按角色挑成员。除了内置角色，你可以用 Markdown 文件自己定义，放在下面两个目录之一：
<项目>/.atomcode/agents/<角色名>.md——只在这个项目里生效；~/.atomcode/agents/<角色名>.md——所有项目通用。
文件名（不含 .md）就是角色名。和内置角色同名的文件会替换它；两个目录有同名文件时，用户目录的生效。
文件由 --- 包住的头部字段和后面的角色说明（人设）组成：
---
permission: explore # 必填：explore（只看、不改任何东西）| worker（可以改文件、跑命令）
difficulty: hard # 必填：simple（用快模型）| hard（用强模型）
effort: high # 可选：思考强度，low | medium | high | xhigh | max
model: glm-4.6 # 可选：指定模型（选择 id），优先于 difficulty
when: 需要做架构设计时 # 可选：一句话说明什么时候派给它
tools: read_file, grep # 可选：限定可用工具，只能从 permission 允许的工具里选
---
你负责架构设计。先读现有代码，再给出方案，列出取舍。| 字段 | 是否必填 | 取值 |
|---|---|---|
permission | 必填 | explore（只读调查）或 worker（受范围限制的写入执行） |
difficulty | 必填 | simple（快模型）或 hard（强模型） |
effort | 可选 | low / medium / high / xhigh / max |
model | 可选 | 模型选择 id；不写则按 difficulty 选 |
when | 可选 | 一句话：什么时候该派给这个角色 |
tools | 可选 | 逗号分隔的工具名，只能是 permission 默认工具的子集 |
注意两点：
- 这里的
permission和命令行的--permission-mode（plan/accept_edits/auto）是两回事，只是名字相同：前者决定这个成员能不能动手，后者是整个会话的审批方式。 - 它不是 Claude Code 的 agent 文件格式。
name、description、allowed_tools、user_invocable这些字段不会被读取：角色名取自文件名，可用工具用tools限定。
格式不对的角色文件会被跳过，不影响会话启动。会话里会提示一次哪个文件被跳过、缺了或写错了哪些字段（一次列全），同一个会话里不会重复提示；和内置角色同名的文件被跳过时，继续使用内置角色。
关闭该功能
task 工具默认开启。若要彻底移除它，设置：
ATOMCODE_SUBAGENT=0 atomcode0、false、off 任一都会关闭；不设置（或其它值）则保持开启。