Open Interpreter Subagent 多智能体实战指南：并行子代理、内置角色与自定义 Agent 配置
【免费下载链接】openinterpreterA coding agent for open models like Kimi K3 and GLM 5.3项目地址: https://gitcode.com/GitHub_Trending/op/openinterpreter
Subagent（子代理）是 Open Interpreter 中与主会话并行运行的独立 Agent 线程，专为隔离式调查、大规模代码检索、评审复盘与并行探索等场景设计。本指南以 docs/subagents.md 为核心脉络，结合仓库中 codex-rs/config/src/config_toml.rs 与 codex-rs/core/src/agent/role.rs 等实现源码，系统讲解多智能体功能的启用方式、TUI 中的/agent操作、三类内置角色、[agents]全局设置、自定义角色的两种定义方式以及权限与沙箱继承规则。读完你将能按需为 Open Interpreter 编排出"主 Agent 拆任务 + 子 Agent 并行干"的高效工作流。
Subagent 是什么：一个会话里的多线程 Agent
Subagent 本质上是独立的 Agent 线程，在主会话旁边并行推进。与把大量工作压进同一个上下文窗口不同，子代理拥有自己独立的线程、消息历史与运行状态，因此特别适合：
- 隔离式调查（isolated investigation）：某个问题需要在独立上下文中探索，不污染主线任务；
- 大规模代码检索与阅读总结（broad code search / read-heavy summarization）；
- 评审复盘（review passes）：让一个角色以只读视角对改动做独立检查；
- 并行探索（parallel exploration）：多个互不依赖的问题同时展开，互不阻塞。
主 Agent 在判断"任务适合并行拆解"时，会显式 spawn 子代理来完成委派，这也是多智能体特性的核心用法。
功能开关：多智能体特性默认开启
根据官方文档，当前构建版本中多智能体功能默认开启，对应 TOML 配置为：
[features] multi_agent = true从源码可以交叉印证这个开关体系：在 codex-rs/features/src/feature_configs.rs 中定义了MultiAgentV2ConfigToml等特性配置；codex-rs/features/src/lib.rs 中的特性键表包含multi_agent、multi_agent_v2、multi_agent_mode等条目。其中multi_agent属于兼容别名（codex-rs/features/src/tests.rs 中通过feature_for_key("multi_agent")测试断言其映射关系），而新一代多智能体后端对应multi_agent_v2特性，支持布尔开关或完整表结构两种写法。
与之并行的还有[agents]区下的enabled开关（默认开启），二者共同构成了多智能体能力的总闸。
在 TUI 中使用子代理
斜杠命令/agent
在 TUI 界面中，核心操作命令是：
/agent在 codex-rs/tui/src/bottom_pane/chat_composer.rs 中，"/agent"被映射到SlashCommand::Agent；在 codex-rs/tui/src/slash_command.rs 中，Agent与MultiAgents命令的用途描述为"switch the active agent thread"，即用于在主线程与各子代理线程之间切换视角。换言之，/agent不只是"创建"，更是你在多线程之间"来回切换"的入口——你可以随时查看某个子代理的最新进展，再切回主线继续推进。
主 Agent 的显式委派
除了手动操作，主 Agent 本身也会在任务受益于并行时显式 spawn 子代理。这种"委派"由底层工具层驱动：在 codex-rs/core/src/tools/handlers/multi_agents_v2/ 目录下，可以看到 spawn（生成）、list_agents（枚举）、wait（等待）、send_message（发消息）、interrupt_agent（中断）、followup_task（追加后续任务）等一整套面向模型的子代理编排工具。这解释了文档中"并行工作带来收益时主代理会主动派生子代理"的行为来源。
从模型使用的角度，一个典型场景是：主线 Agent 同时派发多个explorer去检索不同模块，派发一个worker去实现功能，然后主线通过 wait/send_message 与它们协同，而不是自己串行做完所有事情。
内置角色（Built-In Roles）
系统内置了若干常见角色，实际可用角色随构建版本与配置变化。基础角色如下：
| 角色 | 用途 |
|---|---|
default | 通用助手（General-purpose helper）。 |
worker | 聚焦的执行或调查（Focused execution or investigation）。 |
explorer | 重读取的发现与总结（Read-heavy discovery and summarization）。 |
结合 codex-rs/core/src/agent/role.rs 中built_in::configs()的实现，可以更精确地理解各角色的使用约束：
default：内置描述为 "Default agent."，不绑定任何特殊配置，作为未指定agent_type时的默认角色（常量DEFAULT_ROLE_NAME = "default"）。explorer：内置提示词要求它只做"具体、范围明确的代码库问答"，强调快速与权威；鼓励主线在拥有多个互不依赖的问题时并行派生多个 explorer，并在等待结果的同时继续其他本地工作——这正是文档"并行探索"价值的工程化体现；同时建议复用已有的 explorer 处理相关问题，避免重复劳动。其底层关联一个explorer.toml内置配置层。worker：面向执行与生产性工作（实现功能片段、修 bug/测试、拆分大型重构），其提示词要求主线必须显式分配任务所有权（哪个 worker 负责哪个文件/模块），并提醒 worker"代码库里并非只有你一个"，禁止回退他人改动、需适配他人已做的修改——这套规则专门用于降低并行编辑时的冲突概率。
值得注意的是，源码中还保留了一个被临时移除的角色awaiter（用于等待超长命令、期间并行处理其他事务），目前处于注释状态，这说明内置角色确实会随构建版本增减，与文档"Available roles can vary by build and config"的说法一致。
全局并发设置：[agents] 区段
对子代理的并发规模进行全局约束，示例配置：
[agents] max_threads = 6 max_depth = 1 job_max_runtime_seconds = 1800对应字段语义：
| Key | 含义 |
|---|---|
max_threads | 最大并发 Agent 线程数。 |
max_depth | Agent 可以派生其他 Agent 的嵌套深度。 |
job_max_runtime_seconds | CSV/批处理 worker 任务的默认超时。 |
从 codex-rs/config/src/config_toml.rs 的AgentsToml结构体看，配置体系比文档表格更细，字段解释如下：
max_threads：这是字段max_concurrent_threads_per_session（每会话可同时打开的派生线程上限）的serde 别名，即 TOML 里写max_threads与写max_concurrent_threads_per_session等价，且 schema 约束最小值>= 1。当该项未设置时，由当前选用的多智能体后端采用自身默认值。max_depth：源码注释明确指出这是V1 Agent 线程的嵌套深度上限，V2 会忽略该字段——因此若你运行在新一代多智能体后端上，约束层级的是每会话并发线程数而非嵌套深度。job_max_runtime_seconds：源码注释为 "Removed agent-job setting retained as a no-op for compatibility"（已移除、仅为兼容保留的空操作），并带#[schemars(skip)]。也就是说，该键在当前代码中仅保证旧配置文件能继续加载，不再产生实际调度效果。- 此外还支持
enabled（总开关，默认 true）、default_subagent_model（spawn 时未显式选择模型时的默认子代理模型）、default_subagent_reasoning_effort（默认推理强度）以及interrupt_message（Agent turn 被中断时是否向模型可见地记录一条消息，默认 true）等实用字段。
完整的[agents]可配置项可对照 codex-rs/core/config.schema.json 校验。
自定义角色：从"借用"到"定制"
当内置角色不满足需求时，可以在 config 中定义专属角色。文档给出的内联示例：
[agents.explorer] description = "Inspect code and report findings without editing." developer_instructions = "Stay read-only. Prefer rg and direct file references." model = "gpt-5.1-codex" model_reasoning_effort = "medium" sandbox_mode = "read-only"该示例在只读调查场景中非常典型：description负责让 spawn 工具理解该角色适合什么任务；developer_instructions注入角色专属系统指令（如"保持只读、优先用 rg 与直接文件引用"）；model与model_reasoning_effort锁定该角色所用模型与推理强度；sandbox_mode = "read-only"则从沙箱层面强制"不能编辑"。
文档还提示，其他有用的可选字段还包括：
nickname_candidates：派生出的 Agent 昵称候选列表，让子代理在 TUI 中更容易被辨认；mcp_servers：该角色可访问的 MCP 服务器，用于按角色裁剪外部工具能力；- skill 配置：为该角色挂载特定技能集。
从源码层面，自定义角色机制由两层组成，值得展开说明：
第一层是角色声明。在AgentsToml中，所有[agents.<角色名>]子表通过 flatten 收集为roles: BTreeMap<String, AgentRoleToml>，而AgentRoleToml的结构化字段为description（必填，spawn 工具引导文案）、config_file（指向角色专用配置层文件，相对路径基于定义它的 config.toml 解析）与nickname_candidates。例如源码注释中的模式：
[agents.researcher] description = "Research-focused role." config_file = "./agents/researcher.toml" nickname_candidates = ["Herodotus", "Ibn Battuta"]第二层是配置层应用（role as a config layer）。codex-rs/core/src/agent/role.rs 是整个机制的实现核心：角色在 spawn 时被选中，并通过apply_role_to_config以**高优先级配置层（session-flag 优先级）**的方式压入当前会话配置栈（ConfigLayerStack），从而可以覆盖持久化配置中的模型、指令等设置。其中有两个关键的行为细节：
- 调用方粘性保留：若角色配置层没有显式设置
model_provider、service_tier、model、model_reasoning_effort，则沿用调用方当前的运行时选择，避免子代理静默回退到默认设置； - 角色查找优先级：
resolve_role_config先查用户定义角色、再回退到内置角色，即同名用户角色可覆盖内置角色；未知角色名会报 "unknown agent_type" 错误。
权限与审批：子代理继承主会话态势
文档强调了一个容易被忽视的运维事实：子代理默认继承当前激活的沙箱（sandbox）与审批（approval）态势，除非其角色配置显式收窄。同时，即使子代理并非当前可见线程，审批提示也可能照常弹出——例如某个后台子代理请求执行高权限命令时，审批请求会浮现在界面上等待处理。
TUI 侧有专门支撑这一体验的实现，例如 codex-rs/tui/src/bottom_pane/pending_thread_approvals.rs 会对挂起的审批请求以"/agent"提示引导你切换过去处理。这意味着在多智能体场景下，你需要把"审批"视为会话级而非线程级的注意力资源。
对权限敏感的角色，官方推荐用自定义角色的sandbox_mode = "read-only"把子代理"焊死"在只读模式，再配合developer_instructions中的行为约束（如只用rg、直接引用文件路径而不修改），形成"制度 + 习惯"双重防线。
从源码与测试验证完整调用链
若想确认这套机制的端到端行为，仓库中沉淀了大量可读证据：
- 编排工具层：codex-rs/core/src/tools/handlers/multi_agents_v2/spawn.rs 展示了 spawn 时如何解析
agent_type、应用角色配置（apply_spawn_agent_role）并生成带昵称的任务；同目录的list_agents.rs、wait.rs、send_message.rs、interrupt_agent.rs等补齐了子代理生命周期管理。 - 角色注册表：codex-rs/core/src/agent/registry.rs 与 codex-rs/core/src/agent/role.rs 共同定义"哪些角色可用、角色如何变成配置层"。
- 会话执行控制：codex-rs/core/src/agent/control.rs（及其
spawn.rs、execution.rs、residency.rs子模块）负责子代理线程的实际运行与驻留。 - 集成测试：核心套件中的 codex-rs/core/tests/suite/multi_agent_mode.rs、codex-rs/core/tests/suite/multi_agent_resume.rs 与 codex-rs/core/tests/suite/subagent_notifications.rs 覆盖了并行执行、断点恢复与子代理通知等关键路径；TUI 侧还保留了大量
.snap快照（如 codex-rs/tui/src/snapshots/），直观记录多智能体协作时的界面转录效果。
实践建议与注意事项
综合文档与源码，落地多智能体工作流时有几点值得注意：
- 先想清楚"是否需要并行"：互不依赖、可独立验证的问题才值得 spawn；强依赖顺序的任务直接在主线程做更省资源。
- 善用角色约束而非事后补救：只读调查用
explorer（或自建sandbox_mode = "read-only"角色），并行写代码用worker并明确文件/模块所有权，把冲突风险消灭在委派阶段。 - 区分 V1/V2 语义差异：
max_depth只约束 V1 线程嵌套、V2 忽略；job_max_runtime_seconds当前仅为兼容性空操作，不要依赖它做超时控制；需要限制并发时应关注max_threads（别名max_concurrent_threads_per_session）。 - 关注后台审批：子代理的审批请求可能在非当前线程弹出，多代理高并发时注意检查挂起的
/agent提示。
把文档、配置 schema 与源码结合起来看，Subagent 并不是一个"花哨的开关"，而是一套从 TUI 操作（/agent）、模型工具（spawn/list/wait/send/interrupt）、角色系统（内置 + 用户自定义 + 配置层栈）到权限继承的完整工程机制——理解其分层设计后，你就能让 Open Interpreter 在主线程之外同时驱动多路调查与执行，把原本串行的大任务真正跑成并行流水线。
【免费下载链接】openinterpreterA coding agent for open models like Kimi K3 and GLM 5.3项目地址: https://gitcode.com/GitHub_Trending/op/openinterpreter
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
