章节导航 第 4 章 / 共 21 章
第 4 章 第一部分：快速上手

使用和切换 Agent

16 种内置 Agent 全景图、Agent 配置详解、同一 Task 切换不同 Agent 的方法

Nexus Agent main_agent swe_agent claude_code Docker安全

内置 Agent 全景图

Nexus v1.1.3 内置了 16 种 Agent，大致分为四类。

Agent 生态分层

在理解 Nexus 的 Agent 分类前，先了解 2026 年 Agent 工具的生态分层：

层级代表与 Nexus 的关系
SDK 层OpenAI Agents SDK / Claude Agent SDK / Google ADK用 SDK 组装定制 Agent，Nexus 可通过 Installed Agent 适配
框架层LangGraph / CrewAI / AutoGen / PydanticAI编排逻辑，Nexus 不在这一层竞争
评测/训练层Nexus / OpenHands / verlNexus 的核心层——评测 + 训练一体化

Nexus 的 Installed Agent 模式的独特价值在于：在评测框架的沙箱内原样运行生产 Agent，只代理 LLM 请求。这使得 Nexus 可以用统一的轨迹采集和评分体系来比较任何 Agent——无论是自研的还是第三方的。

第一类：通用 Tool-Calling Agent

这类 Agent 自己实现推理循环，通过 LLM + 工具调用迭代完成任务。

Agent注册名定位适合场景
Main Agentmain_agent通用 tool-calling 循环大多数任务的默认选择
Demo Agentdemo_agent教学示例学习框架用
ToolCall Agenttoolcall_agent基于 base 框架的 tool-calling自定义工具组合

main_agent 是最常用的。它的核心参数：

agent_name: "main_agent"
agent_config:
  system_prompt: "You are a helpful assistant."
  max_iterations: 30
  tools:
    - "str_replace_editor"        # 文件编辑
    - "python_code_interpreter"   # Python 执行
    - "google_search"             # 网页搜索
  parallel_tool_calls: false      # 是否允许并行工具调用
  tool_output_truncation: 10000   # 工具输出截断长度
  observation_time_timeout: 300   # 单次工具执行超时（秒）
  inference_time_timeout: 120     # 单次 LLM 推理超时（秒）

tools 列表决定了 Agent 可以使用哪些工具。不在列表里的工具不会出现在 LLM 的 function schema 中。

第二类：代码修复 Agent

专为代码修复/生成任务设计，带有领域特定的工具和 prompt 工程。

Agent注册名定位典型搭配 Task
SWE Agentswe_agentSWE-bench 风格的代码修复swe_task
CodeAct Agentcodeact基于 CodeAct 范式（代码作为 action）swe_task、terminal_task

swe_agent 自带一套针对代码仓库操作优化的工具（str_replace_editor、search_stateful/*），prompt 经过精心调优。如果你要跑 SWE-bench，首选这个。

codeact 实现了 CodeAct 论文的范式——Agent 用 Python 代码作为 action，而不是预定义的工具调用。它自带的 codeact_tools.py 有 39KB，包含了文件操作、搜索、终端控制等全套实现。

第三类：Installed Agent（外部 Agent 适配器）

这类 Agent 在 Runtime 沙箱内安装和运行第三方 Agent 系统，通过 LLM Proxy 将 API 请求转发回 Host。

Agent注册名底层系统安装方式关键演进
Claude Codeclaude_codeAnthropic Claude Code CLInpm installv2.1.202 引入 Dynamic Workflow Size；v2.1.206 /doctor 诊断、MCP timeout 修复；v2.1.170 Fable 5 访问；v2.1.197 Sonnet 5 默认模型；v2.1.198 Background Subagents（多 Agent 并行）；v2.1.207 Bedrock/Vertex/Foundry 默认解锁 Auto Mode；v2.1.212 /fork→后台会话 + /subtask 子代理 + MCP 自动后台化（>2min）；v2.1.223 多步任务 Agent + 内置 Grep + 多 Agent 协作 + 修复制表符/Unicode 权限绕过；v2.1.224 self-hosted-runner + zip 插件安装 + 跨会话权限 + subagent 取消数量上限；v2.1.225 gateway spend-limit 可视化 + claude agents 工作区信任提示；v2.1.239–270（2026-08-21~09-12，官方 changelog 记录 23 个版本条目）：promptCacheTtl/subagentPromptCacheTtl（243）、agent frontmatter experimental.cacheTtl（248）、foreground subagent 工具调用实时流式到 Remote Control（251）、CLAUDE_CODE_SUBAGENT_MODEL_FORCE（257）、nested background subagent 结果写入父 transcript（259）、subagent 触及 maxTurns 返回 partial（246）、/tasks 按 subagent 显示 model + effort（243）、CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS（1–256，269）；v2.1.271–287（2026-09-14~10-01，官方 changelog 收录 16 个版本块，其中 2.1.279 未发布）：遥测开关不再能从项目级设置下发（282）、LLM 网关提示头与 x-claude-code-prompt-id（273/283）、原始请求体落盘并与 transcript 消息双向对齐（274）、五条子代理结果静默丢失修复（273/275/280）、未知模型 ID 下 Explore 子代理偷偷换模型（284）、沙箱设置不可被项目级放宽（285）、workflow 默认尺寸下调（271）、后台命令硬超时（285）、子代理结果加来源标记（277）、Claude Mods 插件可改更深行为（287）—— 逐条见下方「多 Agent 拓扑对 Installed Agent 适配的影响」与「Docker Runtime 安全注意事项」两节

📌 本表 Claude Code 侧版本基线（2026-11-10 更新）：latest = v2.1.322（发布 2026-11-10，核于 2026-11-10，源 registry.npmjs.org dist-tags + time 字段）；stable = v2.1.311（发布 2026-10-26）——stable 与 latest 自 2.1.311 起分离，引用任何版本号时应注明取的是哪个 tag。上一版基线为 v2.1.308（2026-10-22）——两者相隔 19 天、12 个 npm 版本（309/310/311/312/314/315/316/317/318/319/321/322；2.1.313 / 2.1.320 未发布；changelog 有独立版本块的为 309/310/311/312/314/316/317/318/319/321/322，315 无独立块）。最近一个有明细的版本块是 2.1.321（2026-11-09）；2.1.322 的 changelog 仅一条 fast mode on Vertex。⚠️ 凡”某日止于某版本”的写法都有一个内置的过期时钟，改本表时请连同本行一并更新。 | Codex | codex | OpenAI Codex CLI | npm install | Cognition 收购后推出 2.0，SWE-1.5 推理模型 | | Gemini CLI | gemini_cli | Google Gemini CLI | npm install | Google Agent 生态入口，支持 A2A 协议 | | OpenClaw | openclaw | 腾讯 OpenClaw Agent | pip install | ⚠️ 2026.05-06 多个 CVE（提权 + 命令注入），见下方安全说明 |

📌 模型线续写（2026-11-10 补，衔接上表「v2.1.170 Fable 5 访问」）：v2.1.321（11-09）新增 Claude Fable 5.2（claude-fable-5-2，1M 上下文，8/8/40 per Mtok、$0.20/Mtok 缓存读）并设为默认 Fable 模型，同时把保存的 Fable 5.1 选择迁到 fable 通道。另有一条带死线的过时锚：Opus 4.8 fast mode 自 2026-10-30 起弃用、2026-11-30 移除且不回退（移除后 fast mode 请求直接报错，官方建议迁移 Opus 5.5）——凡评测配置里标注了 fast mode 的条目，在该日期后必坏，引用时应带死线。

⚠️ 以上 Agent 版本更新频繁，以实际安装版本为准。

这种模式的核心思想：不重新实现这些 Agent 的逻辑，而是在 Nexus 的沙箱里原样运行它们，只代理 LLM 请求。 这意味着你可以用 Nexus 的批量执行、轨迹采集、评分体系来跑这些 Agent，而不需要修改它们的代码。

agent_name: "claude_code"
agent_config:
  user_prompt: "Fix the bug described above"
  working_dir: "/workspace/repo"
  timeout: 3600

Installed Agent 的工作流程（第 18 章会详细拆解）：

  1. 在 Runtime 内安装 Agent CLI
  2. 启动 LLM Proxy Server（监听本地端口）
  3. 设置环境变量让 Agent CLI 的 API 请求指向 Proxy
  4. 运行 Agent CLI
  5. Proxy 将请求转发给 Host 侧的 OpenAI Client，实现 token 计数和轨迹采集

⚠️ MCP 超时注意：Claude Code v2.1.206 修复了 request_timeout_ms 被静默忽略的 bug——此前所有 MCP 工具调用被强制 60 秒超时。但 v2.1.212 新增 MCP 自动后台化特性（>2 分钟的 MCP 调用自动转入后台），可通过 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 调整或禁用。如果你的 Installed Agent 使用长时间运行的 MCP 工具，需注意后台化可能导致 Nexus 的 agent_config.timeout 被绕过。 v2.1.319（11-06）又把后台化的触发面扩了一档：MCP server 把工具调用声明为 task 时，Claude Code 立即转后台（不等 2 分钟），CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND 可关——agent_config.timeout 被绕过的风险从”长调用”扩展到”task 型调用”，凡被测 MCP server 支持 tasks 协议的配置都应重估超时语义。

⚠️ LLM gateway 形态下 auto mode 的降级行为也变了（2026-11-10 补）：v2.1.319 起，telemetry / feature flags 关闭（含 LLM gateway 场景）时，auto mode 对服务端无法核查的调用不再回退到内置分类器，改为询问或拒绝；CLAUDE_CODE_AUTO_MODE_SERVER 控制服务端核查开关。Nexus 的 Installed Agent 恰好运行在”LLM Proxy 后面”的形态——auto mode 的行为在这个形态下需单独验证，不能沿用直连环境的测试结论。

⚠️ 多 Agent 拓扑对 Installed Agent 适配的影响： Claude Code v2.1.223 引入多步任务 Agent、内置 Grep 与多 Agent 协作，v2.1.224 进一步取消 subagent 数量上限。这意味着单个 Installed Claude Code 实例内部的 Agent 拓扑从”单主 Agent + 有限子代理”演变为”任意深度的多 Agent 协作图”。对 Nexus 的 Installed Agent 适配有三点影响：(1) 资源配额假设失效——原先按”单个 Agent 进程”估算的 CPU/内存/时间预算，需改为按”Agent 拓扑规模”动态估算；(2) token 计数粒度变粗——子代理的 LLM 请求也经过 LLM Proxy，但归属关系更复杂，token_counter 需要能区分”主 Agent vs 子代理”的 token 归属；(3) 轨迹采集需要捕获子代理的完整上下文，否则训练数据的因果链断裂。

⭐ 上面三点在 v2.1.239–270 区间已被官方逐条兑现，本段的写法应从”我们需要 X”改为”官方已提供 X，应这样对接”：

(1) 资源配额已有可配置量纲：v2.1.269（2026-09-11）新增 CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS，取值 1–256，用于提升 Workflow 工具每轮的并发 agent 上限（官方用例写作 inference-bound fan-outs）。这给出两个此前只有定性判断的事实：拓扑规模有上限，不是无界增长；官方默认值不足以支撑推理受限的扇出场景。Nexus 侧的资源预算可直接对齐到「并发 agent 数」这一维度估算（例如 N_agents × (单 agent 峰值内存 + 单 agent 超时)），而不是笼统地按”拓扑规模”打折。建模公式为编辑建议，非官方表述。

⚠️ 1–256 是取值域，不是默认值（2026-10-02 补）：v2.1.271 起，dynamic workflow 的默认尺寸在 Pro 计划上为 small，且 medium 的尺寸指南从 15 降到 10 agents。按 256 或 15 做预算会严重高估。 公式中”单 agent 超时”一项此前没有官方默认值；v2.1.285 起后台 Bash/PowerShell 命令有了硬超时——run_in_background 的 timeout，默认 30 分钟、上限 2 小时，超时会停止并通知 Claude。可作为该项的官方锚点。

🔴 v2.1.302 起，默认拓扑又变了一次，而且正好变在 Installed Agent 的宿主形态上（2026-10-22 补）。官方原文：「Changed fork subagents (subagent_type: "fork") to be on by default in claude -p, the Agent SDK, the desktop app and VS Code, as they already are in the terminal；CLAUDE_CODE_FORK_SUBAGENT=0 turns them off」。这四种恰好是 Installed Agent 的全部接入形态——即 Nexus 现在默认跑在 fork subagent 已开启的形态下，本章”(1) 资源配额假设失效”的紧迫度随之上升。

配套两点：① 关闭开关是 CLAUDE_CODE_FORK_SUBAGENT=0；若批量评测要求拓扑可复现，应在默认模板里显式写死（开或关二选一），不要依赖默认值。② v2.1.307 修了一条并发 fork 的缺陷——「Improved fork subagents launched together: each is now told which launch is its own, so forks are much less likely to try to start each other’s work」，说明并发 fork 会互相抢活；批量评测若开启 fork，应把”同一父任务下的 fork 数”作为并发控制的一个维度。

另有一条可用性改进：v2.1.271 起 dynamic workflows 在触及用量上限时暂停并在重置后自动继续，而不是丢弃受影响的 agent——批量评测不必再为”跑一半撞上限”单独设计重试。

(2) token 归属维度官方已做出，可对齐而不必自研：v2.1.243 起 /tasks 与 agent 详情框按 subagent 显示其运行的 model 与 effort level；v2.1.257 起 background subagent 与 teammate 的 token counter 在流式响应时实时更新（此前切换 subagent transcript 后计数器会卡住或变慢）；v2.1.267 起 subagent 与 --system-prompt 启动的会话，其 system prompt 与工具定义只记录一次（不再每轮重新渲染）。建议 Nexus 的 token_counter 直接采用「(agent_id, model, effort)」三元组作为归属键，与官方字段同名。

⭐ v2.1.273 起，这些归属维度从”UI 显示”下沉到了”请求头”（2026-10-02 补）：开启 CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 后，每一个发给 LLM 网关的请求都带 x-claude-code-request-class、x-claude-code-agent-type、x-claude-code-compaction、x-claude-code-context-compacted；v2.1.283 再加 x-claude-code-prompt-id，用于把”服务同一个用户 prompt 的多次请求”归为一组。由于 Nexus 的 Installed Agent 本就经过自己的 LLM Proxy，这些头可以直接在代理侧采集，无需改动 Claude Code。

对归属键的直接影响：prompt-id 提供了三元组表达不了的粒度——「一道题的一次尝试」。批量评测中计费与归因的自然单位往往是这个，而不是”一次 API 调用”。建议归属键改为 (prompt_id, agent_id, model, effort)，其中 prompt_id 取自 x-claude-code-prompt-id，其余三项沿用官方字段。

另：v2.1.273 起 OTEL_LOG_TOOL_DETAILS=1 的 cost/token 指标会带上真实的 agent / skill / plugin / MCP server 名称（此前只有泛化名），工具级归因首次可行。

⚠️ 归属键里 token 这一维有一个版本前提（2026-10-22 补）：官方 changelog v2.1.307 原文「Fixed subagent transcripts recording placeholder token usage and an empty stop reason for streamed responses」。含义是——在 2.1.307 之前，流式响应下落盘 transcript 里的 subagent token 用量是占位符、stop_reason 为空，即transcript 侧与 counter 侧的 token 数字不同源。凡以 transcript 为唯一数据源的计费与归因，必须确认 Claude Code 版本 ≥ 2.1.307；否则应改从 OTel 侧取数，或对跨版本间的 token 总量做跳变检测。

⚠️ 归属键里 effort 这一维同样有两个版本前提：① v2.1.288 之前，按名字派生的插件定义 agent 跑的是默认值而非自身声明的 prompt / tools / disallowedTools / effort（官方原文：「a plugin-defined agent spawned by name now runs with its own prompt, tools, disallowedTools and effort instead of the defaults」）——即记录到的 effort 可能不是实际 effort；② v2.1.292 起 Agent 工具新增 effort 参数（官方原文：「so Claude runs a sub-agent at the effort level you ask for」），effort 从”可观测”变为”可指定”。对批量评测的含义：同一模型在同一任务上的分数可能因调用方指定的 effort 而变，引用分数时须与 model 一并记录；Installed Agent 的默认配置模板里应显式指定 effort，不要依赖默认值。

📌 第三、四条版本前提（2026-11-10 补）：③ v2.1.316 起新增 CLAUDE_CODE_SUBAGENT_EFFORT 环境变量——无其他指定时 subagent 的默认 effort 有了全局旋钮，不再继承会话级 effort（官方原文：「Added CLAUDE_CODE_SUBAGENT_EFFORT to set the effort level subagents run at when nothing else names one, instead of inheriting the session’s」）；④ v2.1.317 起，与主会话不同模型的 subagent / teammate 改用该模型自己保存的 effort 值或其默认值，而非会话的 effort。合起来看，effort 的实际取值现在有三个来源（显式指定 / 模型保存值 / 全局默认环境变量），归属记录应把来源一并记下，否则同一分数背后可能换了生效路径。另：v2.1.317 起 OTel 指标 / 事件 / span 新增 anthropic.plan / anthropic.seat_type / anthropic.provider / anthropic.custom_base_url 四个维度——网关侧归因（含”走了哪个 provider / 哪个自定义 base_url”）从此可对齐。

📌 v2.1.307 起，五层拦截有了统一事件（2026-10-22 新增）。官方原文：「Added the claude_code.safety_event OpenTelemetry event for each tool call a permission rule, auto mode, a safety check, a hook or the sandbox stopped, prompted or sent back」。这是第一个把拦截来源（权限规则 / auto mode / 安全检查 / hook / 沙箱）与处置结果（stopped / prompted / sent back）放进同一条记录的结构——此前只有 v2.1.301 挂在 tool_decision 上的 classifier_verdict / permission_mode 两个属性，只能区分分类器与权限规则两层。

🔴 2026-11-05 订正：该事件已于 v2.1.312（10-27）被官方移除（“Changed Claude Code to stop sending the claude_code.safety_event OpenTelemetry event”），从加入到撤回仅 6 天。下段”对 Nexus 的意义”按历史/设计参照读——该事件结构（来源层 × 处置）的设计价值仍在，但作为现行采集通道已不存在；代理侧遥测的稳定锚点回到 v2.1.301 的 classifier_verdict / classifier_category。

对 Nexus 的意义：Installed Agent 的代理侧可以一次采集完整因果链（哪个工具调用、被哪一层、以什么方式处置），不必事后从多个事件与属性里拼装。建议 Filter / Processor 直接以该事件的 （来源层 × 处置） 作为执行受阻样本的分类维度——它比”score 低”更能解释一条轨迹为什么没跑完。

⭐ 另有一条对评测框架特别有用的开关：v2.1.257 新增 CLAUDE_CODE_SUBAGENT_MODEL_FORCE——强制所有 subagent 使用同一模型（忽略 per-spawn 与 agent-definition 的模型覆盖）。批量评测时开启它，可消除”子代理悄悄换成别家模型”这一混淆变量，让分数差异只来自被测对象。对以可复现为生命的评测框架，这一项应写进 Installed Agent 的默认配置模板。

⚠️ 该开关不是这一类问题的完整解——还有一个前置条件是”模型 ID 被 Claude Code 识别”（2026-10-02 补）。v2.1.284 修的正是一个反例，官方原文：

Fixed the Explore subagent switching to Opus on the Claude API when the session runs a model ID Claude Code doesn’t recognize, such as a custom model behind a proxy; Explore now inherits that model

v2.1.274 另修了 Bedrock / Vertex / Foundry 上 model: "opus" 子代理在模型 ID 无可识别 family 时离开会话模型的问题。

这两条都点名了 Nexus 的运行形态（自定义模型 + 代理）。落到默认配置模板上，除了 CLAUDE_CODE_SUBAGENT_MODEL_FORCE，还应校验会话模型 ID 落在 Claude Code 可识别的 family 内；若使用自定义 ID，须确认 Claude Code 版本 ≥ 2.1.284，否则 Explore 子代理仍会换模型，且换模型这件事不会体现在分数报告里。

(3) 轨迹采集已有官方落盘机制：v2.1.259（2026-09-02）起，nested background subagent 的结果会保存到父 subagent 的 transcript，恢复的 subagent 能保留这些结果、共享 transcript 也能看到投递记录（v2.1.260 另修了 in-process teammate 的 transcript 在长时间 API 重试期间丢消息/变空白的问题）。Nexus 的轨迹采集应优先对接这一层，而不是自行重放。

⭐ v2.1.274 起，原始请求体可落盘并与轨迹消息双向对齐（2026-10-02 补）：OTEL_LOG_RAW_API_BODIES=file:<dir> 会生成 index.jsonl，并用 request_body_id 与 message.id 两个事件属性把每个响应关联到它的请求文件与 transcript 消息。这补上了此前”有 transcript 无请求体 / 有 OTel 指标无原始 body”的缺口。v2.1.283 起 OTEL_LOG_TOOL_CONTENT=1 还会把 MCP 工具、WebFetch、WebSearch 的输出写进 tool.output span 事件。

🔴 v2.1.282 起，项目级与 local 设置里的遥测开关被忽略（2026-10-02 新增，本轮最容易被漏掉的一条）。官方原文：

Changed project and local settings to ignore OpenTelemetry variables that turn on export, set its endpoint, or capture content, like CLAUDE_CODE_ENABLE_TELEMETRY and OTEL_LOG_*

对 Nexus 的直接后果：把遥测开关写进评测仓库的 .claude/settings.json 或项目配置，在新版本上会静默失效且不报错。遥测开关必须由管理态设置（managed settings）或进程环境变量下发。

配套的反向能力是 v2.1.274 新增的 claude_code.managed_settings_resolved OTel 事件——它记录管理态设置的来源与策略助手状态（OTEL_LOG_MANAGED_SETTINGS=1 时输出脱敏后的设置与摘要），可用于核对”实际生效的是哪一份策略”。

这条属于操作化退化型风险：配置项写对了位置，但位置本身在新版本被剥夺了效力，且失败是静默的。若仍按旧方案在项目配置里开遥测，现象会是”什么都没发生”，而不是报错。

⚠️ 一条关键限定：v2.1.251 的实时流式只覆盖 foreground subagent——官方原文写明 background subagent（默认）「still show status only」。第 5 章的训练数据生产通常跑 batch/background，实时流式对该场景不适用，只能依赖 transcript 落盘。引用此条时须带上该限定，否则会误导。

⭐ 一个值得接入 Filter 的数据质量信号：v2.1.246 起，subagent 触及 maxTurns 上限时返回结果被标记为 partial（并提示可用 SendMessage 续跑），而非静默结束。被截断的轨迹应在 Filter 阶段识别并剔除或标记，否则会作为”失败轨迹”污染 RL 数据——这与第 5 章的 Filter 模块直接相关。

⚠️ 比”被截断”更危险的是”被丢掉且不报错”（2026-10-02 新增）。v2.1.271–280 区间官方修了至少五条静默丢失路径，全部落在 headless / SDK / --output-format stream-json 这三种集成方式上——正是 Installed Agent 的接入方式：

  1. v2.1.273：子代理在回合中途被转入后台后，其剩余消息与最终报告被 stream-json / SDK 输出丢弃
  2. v2.1.273：最终流式回复缺 token usage 或没有 model id 时，子代理与后台 agent 被报为 failed，且结果永不投递
  3. v2.1.275：--forward-subagent-text 下，context: fork 技能派生的子代理消息被丢弃
  4. v2.1.280：headless 与 SDK 会话中，发给正在收尾的后台子代理的消息被静默丢弃
  5. v2.1.280：启动子代理的会话在报告被读取前发生 compaction，则该报告丢失

对评测框架的后果：第 2 条会让成功的子代理被记成失败——分数被系统性低估，而输出里看到的只是一条正常的 “failed”，没有任何异常信号。这与 v2.1.246 的 partial 标记性质相反：partial 是看得见的失败，上面五条是看不见的失败。Filter 阶段无法用”剔除”来处理，只能靠版本基线 + 结果对账（例如统计 failed 比例在跨版本间的跳变）。

第 5 条与本章已写的 v2.1.259/260/267 正面相接：批量评测是最容易触发 compaction 的场景，故”在 compaction 前读取子代理报告”应作为 Runner 的一条时序约束。

🔴 第六条，性质是”失控”而不是”丢失”（v2.1.304，2026-10-22 补）：官方原文「Fixed a plugin keeping a headless run going past --max-turns, Stop, or ended input by spawning subagents or re-running a finished one」。即插件可以通过派生或重跑子代理，让 headless run 越过 --max-turns、Stop 或输入结束信号。

与上面五条对比：前五条让分数被低估，这一条让成本被超支——方向相反，且在输出上表现为”正常跑完”，比 failed 更难察觉。建议：Installed Agent 的批量配置里，--max-turns / max_iterations 之外应再加一层墙钟时间预算作为兜底，并统计单 run 实际轮次的右尾（跨版本比对时，右尾比均值更敏感）。

📌 “未知”与”失败”必须分开：这不是 Claude Code 独有的问题（2026-10-22 补）。同期 qwen-code v0.26.0（2026-10-21）的两条 release note 修的是同一类：#14669「Hosted Turn recovery now asks the Runtime Broker for execution evidence and treats unprovable outcomes as unknown instead of transient faults」；#14681「Parks managed-agent turns with unknown Runtime outcomes for later rechecks instead of repeatedly retrying cancellation, keeping them active and avoiding false FAILED results」。

两个独立产品在同一周给出了同一答案：为”结果不可证明”设一个独立状态（unknown），与”失败”区分，并保留待复核而不是反复重试或直接判失败。对 Nexus 的具体建议：Filter 阶段的状态集不应是二值的 {success, failed}，而应是三值的 {success, failed, unknown}，且 unknown 不计入成功率分母、也不进入训练集。这与上面”版本基线 + 结果对账”是互补的两半：对账负责发现，三值状态负责不污染。

📌 被测对象自己也交卷了（2026-11-10 补）：v2.1.319（11-06）修复「claude -p exiting 0 in auto mode when its actions were refused because no safety check was available: text and JSON output now exit 1」；v2.1.314（10-30）修复「claude -p exiting with code 0 and no output when startup failed」——两类”假成功 exit 0”（动作被拒时 / 启动失败时）都是 Claude Code 自己修的，与 qwen-code 的两条互为镜像。同版本还新增 permissions.denyInsteadOfPrompting：在终端会话、子代理与队友中，本会等待权限提示的调用改为直接拒绝并继续。对 Runner 的落地建议：exit code 与 permission-refused 事件必须分开采集——319 修复前，被拒动作冒充成功退出码；修复后，denyInsteadOfPrompting 又让”被拒”成为合法的正常路径，只有分开采集才能既不漏失败也不误判被拒。

第四类：专用 Agent

针对特定任务类型优化的 Agent。

Agent注册名定位
BrowserGym Agentbrowser_gym_agent浏览器操作（WebArena/BrowseComp）
Search Agentsearch_agent信息搜索和检索
MM Search Agentmm_search_agent多模态搜索（图片+文本）
Science Agentscience_agent科学研究任务
Terminus2terminus2终端操作（XML 解析范式）
Rondo Agentrondo_agentRondo 范式
Single Turnsingle_turn单轮 LLM 调用（无工具）

browser_gym_agent 是处理网页任务的主力。它实现了复杂的 DOM 压缩、增量观察、站点感知过滤等优化，详细配置：

agent_name: "browser_gym_agent"
agent_config:
  max_iterations: 30
  observation_type: "axtree"           # axtree / html / screenshot
  viewport_width: 1280
  viewport_height: 720
  action_type: "bid"                   # bid / coordinate / code
  use_delta_observation: true          # 增量 DOM 更新（节省 token）
  use_task_aware_filter: true          # 任务感知的 DOM 过滤

Docker Runtime 安全注意事项

Nexus 的 Docker Runtime 是默认沙箱运行环境，但 2026 年 5-6 月披露了多个与 Docker 沙箱和 Agent 运行时相关的严重 CVE：

CVE影响严重性
CVE-2026-2287（CrewAI RCE）远程代码执行漏洞，影响所有使用 CrewAI 框架的 Agent🔴 严重
CVE-2026-27002（OpenClaw 提权）OpenClaw 沙箱内特权提升，逃逸到宿主机🔴 严重
CVE-2026-34040（Docker AuthZ 绕过）CVSS 8.8（HIGH，NVD）。用特制的 API 请求可让 daemon 把请求转发给 AuthZ 插件时不带 body，插件看到空 body 于是放行，而 daemon 照常处理完整请求。对 OPA、Prisma Cloud、Casbin 及所有自研 AuthZ 插件一视同仁；是 CVE-2024-41110 的不完整修复（同根因第三次迭代）。修复于 Docker Engine 29.3.1（2026-03-25，改为 fail-closed）。⚠️ 官方公告原话：不使用 AuthZ 插件的部署不受影响；官方并自评「被利用的基础可能性为低」🟠 高
CVE-2026-24763（OpenClaw 命令注入）通过环境变量注入执行任意命令🔴 严重

对 Nexus 用户的直接影响：如果在 Docker Runtime 中运行第三方 Installed Agent（特别是 OpenClaw），将面临提权和命令注入风险。

⭐ CVE-2026-34040 对 Installed Agent 场景的特殊性： 安全研究方 Cyera Research 明确警示过一个场景：AI coding agent 可能自主发现并利用该漏洞。典型路径是——一个被派去调试 K8s 问题的 agent 想挂载宿主目录，被 AuthZ 拒绝；它拿着 Docker API 访问权限，也理解 HTTP，于是自己构造一个 padding 超过 1 MB 的请求绕过限制。Cyera 的表述是：这个 CVE 不需要任何利用代码、特权或特殊工具，只是一个带额外 padding 的 HTTP 请求，任何能读懂 Docker API 文档的智能体都能构造出来。另一条路径是提示词注入：agent 克隆含恶意指令的仓库后被诱导构造该请求，从而逃出沙箱。

这让上面那句偏抽象的风险论断有了具体的、已披露的实现路径：不是”Docker 有个洞，agent 可能会踩到”，而是”agent 会在完成合法任务受阻的过程中自己找到这个洞”。对 Nexus 的推论是——给 Installed Agent 的 Docker API 权限，等价于给它绕过 AuthZ 的能力；权限边界必须在 Agent 拿不到 Docker socket 的层面划定。

⚠️ 需与官方口径一并阅读：Moby 官方公告只确认了”特制请求可绕过 AuthZ 插件”（未给出 1 MB 阈值，也未提及 AI agent 场景），并把利用的基础可能性评为低。1 MB 阈值、AI agent 自主利用路径、以及下面的 rootless 缓解建议均来自 Cyera Research，属研究方结论，引用时应区分。

⚠️ 权限绕过案例延伸： Claude Code v2.1.223 修复了制表符/Unicode 权限绕过漏洞——此前攻击者可通过在文件路径/命令中嵌入制表符或特殊 Unicode 字符，绕过 Claude Code 的文件操作权限检查。这与上表 CVE 属同一主题：Agent 在受控环境中的越权风险。对 Nexus 的启示是：Installed Agent 的权限边界不能只依赖 Agent 自身的权限检查（它可能被字符编码绕过），而应在沙箱层（Docker/Nix）做独立的能力裁剪作为第二道防线——这正是下面第 3 条”能力裁剪”措施的意义所在。

第三个案例（v2.1.268，2026-09-10）：官方修了一个被 respawn 的进程内 teammate 从你未标记为信任的目录中同名 agent 文件里加载 tools 与 system prompt 的问题。前两个案例的问题是”Agent 自身的检查可被绕过”，这个案例更进一步——风险来自 Agent 从哪里加载配置。对 Nexus 的额外推论：Installed Agent 的 agent 文件发现路径必须显式白名单化（与第 6、7 章的模块发现机制同一套信任模型），否则”目录里多放一个同名文件”就能改变 Agent 的工具集与系统提示。

⚠️ 第四种形态（v2.1.294，2026-10-08）——不是”检查被绕过”，而是”检查没生效”（2026-10-22 补）。官方原文：「Fixed prompt and agent hooks written as instructions (such as “Block commands that…”) allowing what they should block」。即用自然语言指令形式写的 prompt / agent hook，此前会放掉它本该拦截的内容。

前几个案例的共同点是”检查是对的，被绕过去了”；这个案例是”检查写对了，表达方式让它失效”。对 Nexus 的推论是新的：Installed Agent 的安全配置若以自然语言指令下发，其生效性不可假设——批量评测中凡以自然语言形式表达的策略，都应有一条结构化规则作为对照，否则”配了”不等于”生效了”。

同一版本还有一条反向优化可一并参照：「Improved how prompt hooks on Stop and SubagentStop written as instructions (such as “Carry on if the build is broken”) are judged, so Claude is less likely to stop early」——同一种写法（指令式 hook）在拦截场景下会放行、在停止场景下会提前停，方向相反，是同一根因的两个表现。

🔴 第五种形态（v2.1.314/319/321，2026-10-30~11-09）——不是”单次检查失效”，而是”入口级保护缺口”（2026-11-10 补）。前四种形态的共同点是某一次检查被绕过/没生效/被伪造；v2.1.309–321 区间集中修复的一批缺陷升级了问题层级——沙箱保护对特定入口路径整体不适用：

  • v2.1.319：创建 worktree 时存在沙箱逃逸；一条精心构造的环境变量前缀可以把命令片段藏起来躲过 Bash 权限检查；sed 在 accept-edits / auto 模式下可跳过权限检查
  • v2.1.314：claude -p --resume / --continue 进入的 worktree，沙箱保护整体不适用——headless resume 形态直接命中 Installed Agent 的接入方式
  • v2.1.321：一条只读 Bash 命令可在沙箱外运行且不弹权限提示；MCP OAuth 在 server 重定向时会把 refresh token 等密钥发给另一台主机

对 Nexus 的推论：Installed Agent 的沙箱假设必须按入口路径枚举验证——全新会话 / --resume / --continue / worktree 创建与进入，每个入口各验一遍，不能只验单一入口；MCP OAuth 那条另加一条网络侧出口校验（redirect 目标白名单）。

第四个案例（v2.1.277，2026-09-18）——这一类不是”检查被绕过”，而是”来源被伪造”（2026-10-02 新增）。官方改为让子代理结果以标记为 subagent output 的 header 送达主 agent 并将内容缩进，使子代理结果里的文本不能冒充会话自身的指令；同一版本还把 workflow 脚本计算出的 agent() prompt 以”脚本撰写文本”的框架送达，使安全分类器不把它读成用户指令。

对 Nexus 的数据侧意义：训练数据生产时，“指令”与”子代理产出”现在有了官方的结构性区分（header + 缩进），可用于 Filter 阶段识别注入样本——这比事后用启发式猜要可靠。

⚠️ 一条反向的供应链信号（v2.1.287，2026-10-01）：官方新增 Claude Mods——插件现在可以修改更深的行为。这把上面”agent 文件发现路径必须显式白名单化”的推论推进一步：信任边界从”加载哪些文件”扩大到”插件能改到多深”。对 Installed Agent 适配的推论是：插件来源与插件能力应纳入同一套白名单模型，而不只是文件路径。

🔴 v2.1.321 把这个矛盾推到了顶点（2026-11-10 补）。官方 changelog 两条原文：「Changed mods Claude writes to turn on without asking in auto and bypass modes, even with managed allowUnsandboxedCommands: false or allowManagedDomainsOnly, and not to load in dontAsk mode」「Changed mods’ own tool calls ($.tool.call, $.mcp.call) to raise no permission prompt, even under your own ask rules or in dontAsk and -p runs; deny rules and organization policy still apply」。两个要点：① 管理态沙箱开关（allowUnsandboxedCommands: false）挡不住 mods 自动开启——上段”沙箱策略必须由管理态统一下发”在 mods 这一维失效；② headless（-p）运行中 mods 的工具调用完全静默——而 -p 正是 Installed Agent 的主形态；dontAsk 模式则相反，mods 整体不加载——auto/bypass 与 dontAsk 两种形态下 mods 的存在面完全不同，批量评测若混用这两种模式，行为面不可比。

对批量评测的推论：Installed Agent 若在 auto/bypass 模式下运行、且会话中产生了 mod，行为面会无提示地扩大——上节”显式写死配置”的建议从拓扑维度（fork）扩展到 mods 维度：默认配置模板应显式控制 mods 的产生与加载（或在基线镜像中禁用）；deny 规则与组织策略是 mods 场景下唯一仍生效的防线，应作为该场景的可信层单独写入验收清单。

相关的一条降噪能力：v2.1.271 起 agent frontmatter 支持 omitClaudeMd，可让自定义/插件子代理不加载 user/project/local CLAUDE.md（管理策略文件仍加载）——批量评测中可一并减少噪声与注入面。

⚠️ 在列缓解措施之前，先记一个前提（v2.1.305，2026-10-22 补）：官方原文「Added sandbox.allowNestedUserNamespaces so sandboxed commands on Linux can create user namespaces (Chromium, rootless podman)；this lets them get around the sandbox’s file protections」。沙箱自带一个官方承认的、会绕过其文件保护的豁免开关。与 v2.1.285（项目级不能放宽管理态沙箱）并列读，结论是：沙箱强度有一个由管理态控制的上限旋钮，默认语义为”关”。共享评测集群上若开启了它，下面第 3 条（能力裁剪）与第 5 条（rootless）的防护语义都要重估——排查时除已有的三条命令外，还应查该项设置是否被打开。

建议的安全缓解措施：

  1. microVM 隔离：对高风险 Agent，使用 Firecracker/gVisor 等 microVM 替代纯 Docker 隔离
  2. 网络策略：限制 Docker 容器的网络访问，禁止容器间通信
  3. 能力裁剪：使用 --cap-drop=ALL + 按需 --cap-add 最小化容器能力
  4. 版本锁定：确保 OpenClaw 升级到修补 CVE-2026-27002 和 CVE-2026-24763 的版本
  5. rootless 模式：针对 CVE-2026-34040，Cyera 给出的效果最直接——rootless 模式下即便特权容器的 root 也映射到宿主的非特权 UID，爆炸半径从”整台宿主失陷”降为”一个非特权用户失陷”
  6. --userns-remap：无法全量 rootless 时的同类 UID 映射替代
  7. 限制 Docker socket 暴露，并在反向代理层限制请求体大小（如 512 KB）：后者是本 CVE 的定向缓解，无需改动 daemon

⚠️ 上表中需要”改沙箱配置”的措施（1 / 3 / 5 / 6），在存在管理态策略的机器上只能往更严的方向改（2026-10-02 新增，是对前 7 条适用条件的说明，不是第 8 条措施）：v2.1.285 起，项目设置不能放宽或关闭 admin-required sandbox、不能替换 managed deny list 之后的 proxy、不能扩展 strict allowlist、不能重开 managed read-denies；v2.1.282 起，项目/local 的 sandbox.excludedCommands 在管理态设置 allowUnsandboxedCommands: false 或 allowManagedDomainsOnly: true 时被忽略。

对 Nexus 的推论：共享评测集群上，沙箱策略必须由管理态统一下发，不能依赖每份 YAML 的项目级配置——这与上面”agent 文件发现路径必须显式白名单化”是同一个方向（信任边界上移）。另有一条可用的新管理态能力：v2.1.285 的 allowedProviders，可直接限定机器可用的 API provider 列表。

📌 v2.1.304 起，“不可放宽”不再是一张清单，而是一种可编程机制（2026-10-22 补）。官方原文：「Changed mods’ settings.read hooks to receive each settings layer and rewrite the merged settings, so a managed mod can make an organization’s setting a ceiling, including the cleanupPeriodDays the retention sweep uses」。即托管 mod 可以逐层读取设置、重写合并结果，从而把任意一项设置钉成上限。

推论随之升级：共享集群上不只要”由管理态下发”，还要意识到管理态能把包括日志保留期在内的任意项钉死；评测框架若依赖某个本地设置（如日志保留期、缓存目录），需确认它不在被钉死的项里。同一版本（v2.1.305）还有一条相反方向的收紧：插件的预授权工具集也可能被整体剥夺——官方原文「Changed plugins that Claude Desktop mounts by path to no longer keep their allowed-tools when your organization’s managed settings set allowManagedPermissionRulesOnly」，以及「Fixed plugins from marketplaces, claude.ai and npm pre-approving their own tools via allowed-tools under managed allowManagedPermissionRulesOnly; only plugins from an official Anthropic source or a source that managed settings vouch for keep that pre-approval」。

配置书写面上还需注意两个已被修掉的匹配坑：v2.1.277 之前，excludedCommands 的一个 glob 只要匹配复合命令的一部分就会整体豁免；v2.1.281 之前，它匹配不到 git rev-parse --git-dir、与 shell 内建同名的程序，以及含 [WIP] 或 # 行的 commit message。

排查命令（针对 CVE-2026-34040）：docker version --format '{{.Server.Version}}'（低于 29.3.1 即受影响）、docker info --format '{{.Plugins.Authorization}}'（返回插件名才有风险，空则不受影响）、journalctl -u docker | grep "Request body is larger than"。

🔗 详见 Ch10-Runtime 的沙箱架构讨论和 Ch11-Nix 注入的安全防护机制。

Installed Agent 生态动态

2026 年 Q2，Installed Agent 领域有几个值得关注的动态：

Agent SDK 三强竞争：OpenAI Agents SDK、Claude Agent SDK、Google ADK 形成三强格局，各自定义 Agent 的安装、运行和通信规范。对 Nexus 的影响：

  • 不同 SDK 的 Agent 安装方式可能不兼容，Nexus 的 Installed Agent 适配器可能需要为每个 SDK 维护独立的安装脚本
  • A2A 协议（Google）vs MCP 协议（Anthropic）vs 函数调用协议（OpenAI）的竞争，可能影响 Agent 间通信的标准化

mini-swe-agent 取代 SWE-agent：Princeton 官方推荐 mini-swe-agent（约 100 行 Python），SWE-agent 进入维护模式。DeepSWE 和 ProgramBench 均使用 mini-swe-agent 作为统一评测脚手架。对 Nexus 的影响：

  • swe_agent 的底层脚手架可能需要迁移到 mini-swe-agent 的接口规范
  • 统一脚手架使得不同基准间的结果更具可比性

同一 Task 切换 Agent

切换 Agent 只需要改 YAML 的两个字段：

# 方案 A：用 main_agent + 自选工具
agent_name: "main_agent"
agent_config:
  tools: ["str_replace_editor", "python_code_interpreter"]
  max_iterations: 20

# 方案 B：用 swe_agent
agent_name: "swe_agent"
agent_config:
  max_iterations: 30

# 方案 C：用 claude_code
agent_name: "claude_code"
agent_config:
  timeout: 3600

Task 本身不关心用的是哪个 Agent——它通过 WithAgentRunner Mixin 拿到的 run_agent() 函数是由 Runner 注入的工厂函数，内部会根据 agent_name 找到并调用对应的 Agent。

这种解耦的好处：你可以在同一个 benchmark 上对比不同 Agent 的表现，只需要改配置文件。 批量执行时甚至可以在 Generator 里为不同实例分配不同 Agent。

Agent 配置的层级

Agent 配置有两个来源，后者覆盖前者：

  1. YAML 的 agent_config：静态配置，对所有实例生效
  2. Task 通过 run_agent() 传入的参数：动态配置，每个实例可以不同

例如 swe_task 会这样调用 Agent：

agent_output = await task_input.run_agent(
    user_prompt=instance.problem_statement,
    working_dir="/workspace/repo",
)

user_prompt 和 working_dir 来自 Task，max_iterations 和 tools 来自 YAML 的 agent_config。两者合并后传给 Agent。

工具可用清单

Agent 可以使用的工具取决于两个因素：

  1. 已安装的 Tool 模块（通过 nexus modules 查看）
  2. Agent 配置中的 tools 列表（仅 main_agent 需要显式指定）

内置的 34 个 Tool 按类型分：

类别Tool 名执行位置说明
浏览器browser/goto, browser/click, browser/fill 等 20 个RUNTIMEPlaywright 浏览器操作
代码执行python_code_interpreter, safe_python_code_interpreterRUNTIMEPython 代码执行
代码执行jupyter_code_interpreter, jupyter_with_imageRUNTIMEJupyter notebook
文件编辑str_replace_editorRUNTIME精确文件编辑
搜索google_search, google_serper_search, hunyuan_searchLOCAL网页搜索
搜索visit, image_visitLOCAL访问网页/图片
搜索text_to_image_search, image_to_image_searchLOCAL图片搜索
代码搜索search_stateful/find, search_stateful/search, search_stateful/openRUNTIME带状态的代码搜索

注意 LOCAL 和 RUNTIME 的区别：LOCAL Tool 在 Host 进程执行（因为需要 API Key 等），RUNTIME Tool 在沙箱里执行（因为操作文件系统/浏览器）。