章节导航 第 18 章 / 共 21 章
第 18 章 第二部分：架构原理

Installed Agent 模式

在沙箱内运行第三方 Agent、LLM Proxy 转发机制、四种 Installed Agent 的实现对比

Nexus Installed Agent Claude Code OpenClaw LLM Proxy

Installed Agent 的核心思想

不重新实现别人的 Agent 逻辑，而是在 Nexus 的沙箱里原样运行它们，只代理 LLM 请求。

这意味着：

  • Claude Code 的 100+ 内置工具、multi-agent 协作、权限模型——全部原封不动
  • Nexus 只做基础设施：沙箱隔离、LLM 路由、轨迹采集、评分
  • 用 Nexus 的 batch runner 可以大规模跑这些 Agent 的评测

架构

Host 侧                           Runtime 沙箱内
┌──────────┐                      ┌──────────────────────┐
│ Runner   │                      │                      │
│   │      │   HTTP/SIO           │  1. Installer        │
│   ├──────┼──────────────────►   │     npm install @anthropic-ai/claude-code
│   │      │                      │                      │
│ OpenAI   │   LLM Proxy relay    │  2. Runtime Setup    │
│ Client ◄─┼──────────────────────┤     启动 LLM Proxy   │
│   │      │                      │     设置环境变量      │
│   │      │                      │                      │
│   │      │                      │  3. Agent CLI        │
│   │      │                      │     claude-code --prompt "..." │
│   │      │                      │     ↓ API 请求       │
│   │      │                      │     → LLM Proxy      │
│   │      │   ◄─ relay ──────────┤     → SIO → Host    │
│   ├──────┼──────────────────►   │     ← response       │
│   │      │                      │                      │
└──────────┘                      └──────────────────────┘

四个 Installed Agent 的实现对比

每个 Installed Agent 都有三个模块：

installer.py：安装逻辑

Agent安装方式大小特殊处理实测最新版（2026-10-06）
claude_codenpm install @anthropic-ai/claude-code8.4KB版本检测、npm registry 配置、二进制路径查找2.1.310（2026-10-23 发布；stable tag 停在 2.1.308）
codexnpm install @openai/codex2.8KB相对简单0.164.0（2026-10-23 发布；另有 alpha 0.165.0-alpha.1）
gemini_clinpm install @google/gemini-cli4.5KB需要 Node.js 20+，自动检测版本npm 0.65.0（2026-10-20 发布；preview 0.66.0-preview.0、nightly 0.67.0-nightly，勿混用）
openclawpip install + git clone10KB最复杂——需要 clone 仓库、安装依赖、配置环境无公开版本号可核

⚠️ 原书此处写的是 npm install @anthropic-ai/gemini-cli，该包在 npm registry 上返回 404（不存在）。 Gemini CLI 的官方发布 scope 是 @google。同书 Ch19 的 Installed Agent 差异表写的正是 @google/gemini-cli——同一张表在两章曾给出两个不同的包名，现统一为 @google/gemini-cli。

⚠️ 版本锚点口径提示：本节三个包各有多个 tag，引用时必须说清是哪个：claude_code 的 npm latest 是 2.1.289，而 stable tag 停在 2.1.285（另有 next 2.1.290）；codex 除 latest 0.160.1 外还有 0.162.0-alpha.15 预发布；gemini-cli 除 npm stable 外还有 preview 0.63.0 与 nightly 0.64.0。gemini-cli 的 npm latest 与 GitHub releases 的 nightly 标签不是同一口径，不要混用；本节一律以 npm stable 为准。

🔴 请把本节的版本号当作抓取时刻的快照，不要当作稳定事实。 claude_code 在两次抓取之间（2026-09-17 → 2026-10-06，19 天）从 2.1.274 漂到 2.1.289，中间是 15 个版本。下一次复测（2026-10-06 → 2026-10-23，17 天）从 2.1.289 漂到 2.1.310，中间是 21 个版本——比上次更快（0.79 版/天 → 1.24 版/天）。「当作快照、不当作稳定事实」这条因此不是修辞，是可测量的：两次独立测量的漂移率都在上升。这个漂移率意味着任何写死版本号的句子都会很快过期。本节的全部结论都不依赖具体版本号，依赖的是机制（装什么、怎么起代理、数据怎么采）；版本列只是给读者一个”我当时看到的是这个”的参照。

runtime_setup.py：环境配置

这是差异最大的部分。

claude_code（12KB）：

  • 启动 Anthropic Proxy（接收 Anthropic 格式请求，转为 OpenAI 格式转发给 Host）
  • 设置 ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL 指向本地 Proxy
  • 配置 Claude Code 的 settings（禁用遥测、设置模型名等）

🔴 ANTHROPIC_BASE_URL 不是一次性适配，它是一个逐版本的兼容性面。 自 2.1.285（2026-09-29） 起，会话一旦检测到自定义 ANTHROPIC_BASE_URL，就会默认使用模型的 1M 上下文窗口（Opus 4.7+、Sonnet 5+、Fable）——官方原文是 “Changed sessions behind a custom ANTHROPIC_BASE_URL to use the 1M context window of models that have one”；官方给的处置方式是客户端显式声明更小窗口（/autocompact 200k）。

Nexus 的 anthropic_proxy 正是这种形态，而 Host 侧 openai_client 背后的模型未必支持 1M。后果是超窗硬失败，不是优雅降级：CLI 按 1M 去组织上下文，Proxy 转发出去后 Host 侧直接拒。因此 Proxy 或 setup 阶段必须向 CLI 声明 Host 侧真实的窗口上限，不能让 CLI 自己猜。

⚠️ 2026-10-25 降级修正：上一段的处置建议不完整，须补两点。

第一，处置手段有两个，不只一个。 除客户端显式声明更小窗口（/autocompact 200k）外，还有环境变量 CLAUDE_CODE_DISABLE_1M_CONTEXT（2.1.50 引入；2.1.287 注明 =1 保留 200K，并把 Opus 4.7+ 与 Fable 的 1M 默认窗口推广到 Bedrock / Vertex / Foundry / Claude apps gateway，不带 [1m] 后缀）。

第二，也是更要紧的：这个开关不是硬上限。 自 2.1.223 起，它的实现方式是「把每一个具备原生 1M 窗口的 Claude 模型经 auto-compaction 压到 200K，而不是只管一个固定清单」；当 auto-compaction 没能把会话压到 200K 时，官方只给一条启动告警。因此原句「必须声明 Host 侧真实的窗口上限」应改写为「声明 + 回读生效窗口」——光把值写进去不够，压缩可能兜不住，而兜不住时唯一的信号是一条启动日志，Proxy 侧看不到。

后半句结论不变且应强化：后果仍是超窗硬失败而非优雅降级。

跨章看，这是同一条链路的三段：Ch15 的压缩触发阈值、Ch16 的 ContextLengthExceededError 包装、以及这里——窗口声明 → 触发阈值 → 超限包装。三段缺任何一段，长上下文请求都会以一种看不懂的方式失败。

codex（5.5KB）：

  • 启动 OpenAI Proxy
  • 设置 OPENAI_API_KEY、OPENAI_BASE_URL
  • 相对简单——Codex 原生用 OpenAI 格式

codex 审批/治理演进：Codex CLI v0.147.0（2026-08-07）新增 --approve-for-me 标志，把逐条审批决策委托给独立的 auto-review subagent（LLM reviewer）——低风险动作自动批准、高风险（网络外泄/凭据访问/破坏性文件操作）仍拒绝或升级人工。OpenAI 声称 96.1% 恶意行为捕获率，同时把人工中断降低约 200×。同版本移除已弃用的 --full-auto 标志，安全策略从「一次性跳过审批」转向「分层自动审查」。这对 codex 作为 Installed Agent 被 Nexus 转发时的默认安全假设有直接影响。

gemini_cli（8.6KB）：

  • 启动 Gemini Proxy（接收 Gemini 格式请求，转为 OpenAI 格式）
  • 设置 GEMINI_API_KEY、自定义 API 端点
  • 处理 Gemini 特有的 streaming 格式

gemini_cli 内建子代理：自 Gemini CLI v0.54.0（2026-08-06）起内建 Antigravity agent runner（Firestore 并发双锁 + 完整 prompt templates）与 PR Generator——标志其从「单一 CLI Agent」向「内置 PR 自动化子代理 + 服务端编排（Cloud Run job）」扩展——Installed Agent 本身也在变成多 Agent 平台，佐证本章「生态扩展趋势：从 4 种到 6+ 种」的判断。

⚠️ “Antigravity” 在本节里指两件不同的东西，别混。 这里的 Antigravity 是 Gemini CLI 内部的子代理 runner（官方 release notes 记为 v0.54.0 的 “PR Automation & Antigravity Agent”，用 Firestore 并发双锁保护 PR generator）。另有传闻称免费档已被一个闭源的 Antigravity CLI 取代——那是另一个东西，本节不涉及。

📌 模型面补充：官方文档的模型配置表里已出现 gemini-3.8-flash 与 gemini-3.5-flash-lite，可通过 model.name 选择（选择方式见 Ch15 引过的 Gemini CLI 配置表）。⚠️ 这两个 ID 是否随 v0.62.0 引入、是否受实验标志门控，本轮未回源确认。

openclaw（48KB——最复杂）：

  • 在 Nexus 沙箱内再搭建一套 OpenClaw 的运行环境
  • 生成 OpenClaw 配置文件（YAML）
  • 启动 OpenClaw 的 tool server（提供文件操作、终端操作等）
  • 配置 MCP Server
  • 处理 OpenClaw 的多种运行模式

agent.py：运行逻辑

四个 Agent 的运行逻辑相似：

@agent_registry.register('claude_code')
async def run_claude_code(input_data: ClaudeCodeInput) -> ClaudeCodeOutput:
    ctx = require_context()
    runtime = await ctx.get_runtime()

    # 1. 安装（如果还没装）
    await runtime.invoke(installer.install, ...)

    # 2. 启动 LLM Proxy
    proxy_info = await runtime.invoke(runtime_setup.setup, ...)

    # 3. 运行 CLI
    result = await runtime.invoke(agent.run_cli,
        prompt=input_data.user_prompt,
        working_dir=input_data.working_dir,
        timeout=input_data.timeout,
    )

    # 4. 解析输出
    return ClaudeCodeOutput(
        success=result.exit_code == 0,
        output=result.stdout,
        main_tmux_session_id=result.session_id,
    )

LLM Proxy 转发机制详解

Proxy 是 Installed Agent 的核心——它让沙箱内的 Agent CLI “以为”自己在直接调用 LLM API，实际上请求被转发到了 Host。

数据流

Agent CLI (沙箱内)
  │ POST http://localhost:8080/v1/messages  (Anthropic 格式)
  ▼
Anthropic Proxy (沙箱内 FastAPI)
  │ 转换为 OpenAI 格式
  │ SIO emit('llm_request', {messages, model, ...})
  ▼
SIOBridge → Socket.IO → Host
  │
  ▼
RemoteRuntime (Host 侧)
  │ 接收 llm_request 事件
  │ ctx.openai_client.create_completion(messages)
  ▼
OpenAI API (或其他 LLM)
  │ 返回 completion
  ▼
Host → SIO → Proxy
  │ 转换回 Anthropic 格式
  ▼
Agent CLI

格式转换

四种 Proxy 的核心工作是格式转换：

  • Anthropic Proxy（server/services/anthropic_proxy/converter.py，23KB）：Anthropic Messages API ↔ OpenAI Chat Completions
  • Gemini Proxy（server/services/gemini_proxy/converter.py，25KB）：Gemini generateContent ↔ OpenAI
  • OpenAI Proxy（server/services/openai_proxy.py，8.5KB）：OpenAI ↔ OpenAI（处理 streaming 等细节差异）
  • Responses Proxy（server/services/responses_proxy/converter.py，10.5KB）：OpenAI Responses API ↔ Chat Completions

⚠️ 在讨论分页拉取之前，先有一条已经发生的、更先出问题的失效：2.1.302（2026-10-16）修的是「当 server 协商的协议版本是 2026-07-28 但省略了 resultType、ttlMs 或 cacheScope 时，MCP server 显示不出任何工具，或每次工具调用都失败」。前置条件是 2.1.292 起本地（stdio）MCP server 默认按 2026-07-28 协商（含 Bedrock / Vertex / Foundry），2.1.295 起 claude.ai connectors 同样默认。

这说明协议版本协商本身就是一个会静默归零的接缝——声明了新版本却缺字段，得到的是零工具，而不是一条「你的 server 不合规」的报错。这比分页拉取更先出问题，也更难定位。与 Ch20 的 MCP 段互引（Ch20 主写）。

MCP 2026-07-28 最终规范（SDK 3.0.0 已落地）引入了分页工具发现、多轮请求、非阻塞 server 启动三项能力。若 Nexus 的 LLM Proxy 需要转发 MCP 工具，需关注大工具目录下的分页拉取与多轮请求适配——这会改变 Proxy 侧的工具列表拉取方式。

以上规范条款本身已核实为最终版（非 RC，SDK 3.0.0 已落地）；但对 Nexus 具体转发实现的影响为推断，是否真的需要改造 Proxy 侧的工具列表拉取，待工程验证。

LLM Proxy 是逐版本兼容性面，不是一次性适配

前面把 Proxy 描述成”Installed Agent 的核心”，机制确实是稳定的——但稳定的是机制，不是兼容性。Nexus 的 anthropic_proxy 通过设置 ANTHROPIC_BASE_URL 工作，而在官方 changelog 里，ANTHROPIC_BASE_URL / proxy / gateway 是一个高频回归区：

版本（日期）官方要点性质
2.1.181（2026-06-17）自定义 ANTHROPIC_BASE_URL 上 prompt caching 读不到，因为每轮的 per-request attestation token 都在变功能失效
2.1.203（2026-07-07）后台与 agent-view 会话丢掉 shell 导出的 ANTHROPIC_BASE_URL，把 API key 发到默认端点并 401凭据外泄路径
2.1.246（2026-08-25）遥测与 metrics 请求携带为第三方网关配置的 API key 发往 Anthropic凭据外泄路径
2.1.266（2026-09-08）2.1.265 的 regression：未文档化的 CLAUDE_CODE_USE_GATEWAY 开始自行强制 Cloud gateway 登录官方自标 regression
2.1.276（2026-09-18）2.1.275 的 regression：ANTHROPIC_BASE_URL 指向 proxy/gateway 时每个请求都 400（Input tag 'advisor_20260301'）官方自标 regression
2.1.285（2026-09-29）检测到自定义 ANTHROPIC_BASE_URL 即默认使用 1M 上下文窗口（见上一节的紧急提示）行为变更
2.1.290（2026-10-05）mods 对「经网关（ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN）访问且无 Anthropic 账号」的用户保持关闭功能失效
2.1.299（2026-10-14）①server-managed settings 请求携带了第三方网关的 API key（当 managed settings 文件设置了 ANTHROPIC_BASE_URL 时）凭据外泄路径
2.1.299（2026-10-14）②feature flag、startup、fast mode、profile 与 feedback 请求携带了为第三方网关配置的 API key（原文注明 Anthropic API keys 仍照常发送）凭据外泄路径
2.1.299（2026-10-14）③经自定义 ANTHROPIC_BASE_URL 的流在 180 秒无数据后被中断，现改为等 300 秒，无论 feature flags 是否加载行为变更
2.1.299（2026-10-14）④在网关专属模型名下，会话在约 200K token 处就以 Prompt is too long · automatic compaction failed 结束，而不是把请求发出去功能失效
2.1.304（2026-10-19）自定义 ANTHROPIC_BASE_URL 下 tool search 默认开启；网关返回 400 或 422 时会不带它重试行为变更
2.1.307（2026-10-21）prompt-caching-scope beta header 在自定义 ANTHROPIC_BASE_URL 网关后以及 Foundry 上仍被发送，而那里它不起作用功能失效
2.1.310（2026-10-23）部分网关与兼容 server 会拒绝 effort-2025-11-24 beta 值或中途插入的 system message，导致请求失败；现在会不带它们重试兼容性修复

四个多月里十一条，其中两条被官方自己标注为前一版本的 regression，四条是凭据外泄路径（2.1.203 / 2.1.246 / 2.1.299①②）。⚠️ 上一版正文写的「两条是凭据外泄路径」已被 2.1.299 一次加的两条推翻——同一份修复列表里一次新增两条同类路径，说明这不是偶发疏漏，而是「凡发往 Anthropic 的非模型请求都默认带上当前配置的 key」这一默认行为的持续外显。这意味着”配好一次就能一直跑”的假设不成立。五条缓解：

  1. CLI 版本必须锁定（与 Ch19「锁定依赖版本」同一原则），升级前在 Proxy 上跑一次冒烟——上表里两条 regression 都是在 minor 升级中引入的。
  2. Proxy 侧对未知字段应透传而非校验拒绝。2.1.276 那条就是官方往请求里注入了一个 Proxy 不认识的 Input tag，Proxy 若严格校验会把它变成全量 400。
  3. setup 阶段断言 ANTHROPIC_BASE_URL 已生效。2.1.203 那条里，环境变量只是被丢掉了，之后一切照常运行、只是 key 发去了错误的地方——这是最坏的一类失败：不报错，只是悄悄错。
  4. Proxy 不得改写 model 名，必须原样回显请求里那个字符串。依据是一组三条同族修复：2.1.301 修的是「在返回的模型名与所请求不同的 LLM 网关后面，会话被反复压缩，而且压在一个你没选的模型上」；2.1.302 修的是 /autocompact 与 /effort 在网关用前缀命名 Opus 4 / 4.1（如 anthropic/claude-opus-4-1）时保存到错的模型；2.1.299④ 是同一格的第三种表现（网关专属模型名 → 约 200K 处直接报压缩失败而非发出请求）。Nexus 的 anthropic_proxy 做格式转换时若顺手改写 model 名（加前缀、映射内部别名），会精确命中这一条：请求发的是 A、响应里是 B，CLI 按 B 记账并按 B 的窗口压缩。判据升级：与 Ch15 已立的「写了值要回读生效值」是同一条——这里是「发出去的名要回读成同一个名」。这条失效的表现是压缩失败而不是模型错误，读者极难反向定位到 Proxy 改名。
  5. Host 侧必须在 300 秒内吐出第一个字节。经自定义 base URL 的流，原本 180 秒无数据就被中断，2.1.299 起放宽到 300 秒（且无论 feature flags 是否加载）；2.1.222 有一条更早的同族修复（server 的 keep-alive ping 已到达时 idle timeout 仍误触发）。这是一道不在 Nexus 手里的时钟：Nexus 侧 agent_config.timeout 默认 3600s（Ch19），Installed Agent 的 timeout 默认 3600.0——两道闸门都比 CLI 的 300 秒宽松一个数量级，真正的先到者是 CLI。慢模型 / 长 prefill 会表现为「CLI 提前退出」而不是超时错误，对评测场景尤其危险：建议显式发 keep-alive，或把这条写进对标评测的可比性说明。

训练数据采集

关键收益：所有 LLM 请求都经过 Host 侧的 OpenAI Client，这意味着：

  • @observe 装饰器自动采集每次调用的 Span
  • @cacheable 装饰器支持缓存和重放
  • TokenCounter Processor 统计 token 用量
  • ChatTracker 记录完整对话轨迹

即使是 Claude Code 这样的黑盒 Agent，Nexus 也能采集到完整的 token-level 训练数据。

还有一类信号是 CLI 主动送出来的，成本只是读几个 header。 设 CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 后，Claude Code 会在每个请求上带一组 hint headers，其中两项对 Nexus 直接有用：

  • x-claude-code-prompt-id（2.1.283，2026-09-25）——把服务同一个 user prompt 的请求归组。这比按时间戳切段可靠得多：一次 user prompt 可能引发多轮请求（含工具调用、子代理、后台任务），时间戳切段会把它们切开或把不相关的合进来。
  • x-claude-code-compaction 与 x-claude-code-context-compacted（2.1.273，2026-09-15）——让 Proxy 层直接看到压缩事件。这正好可以当轨迹切段边界：与 Ch15「平台侧 compaction 是一等可观测事件」、Ch14 的 segment 构建是同一个接缝。

⚠️ 需工程验证：这几个 header 在经 Nexus Proxy 做格式转换与过滤之后是否还保留。

InstalledAgentInput/Output 公共模型

class InstalledAgentInput(AgentRunInput, WithUserPrompt, WithWorkingDir):
    timeout: float = 3600.0

class InstalledNodeCliInput(InstalledAgentInput):
    npm_registry: str | None = 'http://mirrors.tencent.com/npm/'

class InstalledAgentOutput(AgentRunOutput):
    success: bool
    output: str          # stdout
    stderr: str = ''
    exit_code: int = -1

所有 Installed Agent 共享这些基类，保证了一致的接口。

适用场景

场景推荐理由
对标 Claude Code 的 SWE-bench 成绩claude_code Installed原汁原味，结果可比（⚠️ 自 2.1.287 起需显式固定 mods 配置，见下方限定）
自研 Agent 的评测main_agent + 自定义 tools完全控制，灵活性最高
快速试用新 Agent 系统Installed Agent不需要理解内部实现
RL 训练main_agent + HyTuner需要 token-level 控制
训练数据采集（黑盒 Agent）Installed Agent + ChatTrackerLLM Proxy 自动采集

⚠️ “原汁原味”这个理由要带一个时间限定。 自 2.1.287（2026-10-01） 起，插件可以通过 Claude Mods 修改更深层行为（官方原文：plugins may now modify deeper behavior）；同版本还内置了首发 mod “You should know”——一个旁挂的子代理在会话中主动介入、提示你可能漏掉的东西，可用 /plugin enable cc-plugin-you-should-know@builtin 打开（限 first-party 且开启遥测的会话）。两件事叠起来的后果是：做对标评测时必须显式禁用或固定 mods 配置，否则轨迹里会混入 Nexus 侧完全看不到的 mod 行为，“原汁原味、结果可比”就不再成立。这与本章 §生产级安全部署 的纵深防御取向是同一条逻辑——第三方可扩展的层级越深，评测对”可控性”的假设就越弱。

至此，原理篇全部完成。18 章 + 阅读指南覆盖了 Nexus 框架从使用到设计的完整知识体系。

生态扩展趋势：从 4 种到 6+ 种

sandbox-agent 生态的扩展揭示了两类新的 Installed Agent 用例，不在 Nexus 原有四种分类（代码生成/代码审查/安全扫描/文档生成）中：

  • IDE 嵌入式 Agent（如 Cursor）：直接在编辑器上下文中执行，需要 IDE API 工具集，强调与开发工作流的无缝集成
  • 持久会话式 Agent（如 Pi）：需要持久会话管理和上下文维护能力，强调跨轮次的对话连续性
  • 自进化 Agent（Hermes）：Nous Research 在 Hermes 中实现了第三种模式——Agent 通过 Skills 学习新能力、持久记忆积累经验，而非固定工具集。阿里云已提供官方托管方案（FC Agent Sandbox + 云沙箱）。对于 Nexus，Hermes 作为 Installed Agent 的独特价值在于”可采集 Agent 自进化轨迹”——当前 ChatTracker 记录的是固定能力 Agent 的推理轨迹，而 Hermes 的 Skills 学习路径提供了新的训练数据类型。挑战在于：自进化 Agent 的 LLM Proxy 适配需要处理动态工具注册（Skills 可能运行时生成新 tool schema）。

这两类代表了 Installed Agent 向”嵌入式”和”持久化”方向的演进。对架构的新要求包括：

  • IDE API 集成：Cursor Agent 需要通过 LSP/DAP 等 IDE 协议访问代码上下文，Nexus 的沙箱需要暴露这些接口
  • 会话状态持久化：Pi Agent 需要跨重启维护对话历史，Nexus 的 BatchRunner 目前是任务级状态管理，需要扩展为会话级

Installed Agent 生态扩展

Nexus 的四个 Installed Agent（claude_code/codex/gemini_cli/openclaw）并非唯一的「沙箱 + Agent CLI + 代理通信」方案。社区已有多个类似架构的开源实现：

sandbox-agent

开源 Rust 二进制，在沙箱内启动 Claude Code/Codex/OpenCode/Amp 作为服务端进程，通过 HTTP/WebSocket 控制运行。统一 session transcript schema 标准化不同 Agent 的事件格式。支持 E2B/Daytona/Vercel Sandboxes 等多种沙箱提供商。

2026 年重大升级：

  • 新增 Agent 支持：Cursor、Pi（共 5 种 Agent：OpenCode/Amp/Cursor/Pi/原有通用类型）+ Hermes 自进化 Agent（阿里云托管）
  • 新增沙箱后端：Docker + gVisor 两种隔离方案（gVisor 提供用户态内核隔离，比纯 Docker 容器更强）
  • LLM Proxy 增强：新增 Claude/Gemini/OpenAI 多模型路由，支持按任务类型自动选择模型
  • 会话持久化：支持跨重启保持 Agent 状态（截至 2026-09-17 官方提供五种后端可选：in-memory / Rivet Actor state / IndexedDB / SQLite / Postgres）

2026 年新增、本章原先未覆盖的能力（截至 2026-09-17，仓库 rivet-dev/agents（原名 rivet-dev/sandbox-agent，1,608★，Apache-2.0，最后 push 2026-10-24）：

⚠️ 仓库已改名（2026-10-25 核实）：rivet-dev/sandbox-agent 现在 301 跳转到 rivet-dev/agents（1,608★，Apache-2.0，最后 push 2026-10-24）。引用链接需更新。更要紧的是——改名往往伴随定位调整，下列四项能力（凭据抽取、LLM credential gateway、desktop runtime、会话持久化五后端）是在原名时期读的文档，本轮未回新仓库文档复核，在复核之前不得视为仍然成立。保留原描述但标 ⚠️ 待核。

  • 凭据抽取：sandbox-agent credentials extract / extract-env 可直接从本地 claude / codex / opencode / amp 的配置里抽出 API key 并注入沙箱。这条能力同时意味着本地凭据会被显式抽出并送入沙箱，与本章「凭证层：任务完成即销毁」的取向相反，是值得对照的反面参照。
  • LLM credential gateway：官方支持接入 OpenRouter / LiteLLM / Portkey 等网关，并提供 per-tenant token 计量与预算强制——恰好是本章「LLM Proxy 成本优化」一节想做而没做成的东西。
  • desktop runtime：/v1/desktop/* 一组截图、剪贴板、键盘/鼠标输入 API，即 computer use 能力。这是 Nexus 当前完全没有的一层。

AgentBox SDK

npm install agentbox-sdk（仓库全名 TwillAI/agentbox-sdk），提供 Agent("claude-code", { sandbox }) 统一接口。关键创新：不使用 claude --print（非交互模式），而是在沙箱内启动 Agent 为 server process，通过 WebSocket/HTTP 通信，保留完整的 approval flow、tool-use control 和 streaming。支持 local-docker / e2b / modal / daytona / vercel 沙箱互换。

同名项目警告：当前至少有三个互不相干的 agentbox。不绑定仓库全名，读者会装到完全不是本章描述的那个：

仓库形态星数（2026-09-17）与本章的关系
TwillAI/agentbox-sdkTypeScript SDK，Agent("claude-code", { sandbox })166本章描述的这一版。npm agentbox-sdk 最新 0.1.603（2026-10-02），最后 push 2026-10-14，仍在活跃迭代
madarco/agentboxCLI + macOS 菜单栏应用，隔离 VM + checkpointing（从检查点恢复 <1 秒）+ parallel boxes + project teleportation559活跃演化中的另一版（push 2026-10-07，约五周涨 153 星），支持 Claude Code / Codex / OpenCode / Pi
rlaope/agentbox服务端 Node.js 框架，把沙箱 Agent 当 SaaS 后端执行引擎2与本章无关，仅作消歧

⚠️ 早期扫描资料称 TwillAI 版「2026-05-25 后无提交、无 release，已停更」。经 npm registry 与 GitHub 一手核实，此为误判：该仓库 2026-09-16 仍有推送，npm 版本已迭代到 0.1.512（09-09、09-14、09-16 连续发布）。引用二手档案站的活跃度结论前须回 npm/仓库核。

本轮是这条结论的第二次独立确认（距上次 39 天）：npm 版本又从 0.1.512 迭代到 0.1.603（又发了 91 个补丁版本），仓库最后 push 2026-10-14。同名项目警告表里 madarco 版同期从 406★ 涨到 559★。这说明本项目名下的两个实现都在活跃演化，星数列需定期刷新。

交叉引用：madarco 版的 checkpointing（从检查点恢复 <1 秒） 与本书 Ch13 讨论的 durable execution、Ch17 提案涉及的快照/分叉能力属同一技术方向，可作为 Installed Agent 侧的实例。

社区方案对比

维度Nexussandbox-agentAgentBoxOpenAI Agents SDK
目标场景评测 + 训练数据采集通用 Agent 执行CI/CD 生产部署Agent 开发 + 部署（通用 Agent 运行时）
Agent 支持4 种（claude_code/codex/gemini_cli/openclaw）5+ 种（含 OpenCode、Amp、Cursor、Pi）3+ 种自定义（Agent 基类 + SandboxAgent）
沙箱后端DockerE2B/Daytona/Vercel/Cloudflare/Modal/Local + gVisor（官方当前清单未列，待核实）Docker/E2B/Modal/Daytona/VercelDocker/E2B/Daytona/Modal/Vercel/Cloudflare/Redis/S3（20+）
交互式会话--print 模式服务端进程服务端进程（保留 approval flow）Sessions API（长程任务）
LLM 路由单模型转发多模型路由（Claude/Gemini/OpenAI）单模型100+ provider（provider-agnostic）
LLM 网关与预算❌（当前仅转发）✅ OpenRouter / LiteLLM / Portkey 网关，per-tenant token 计量与预算强制❌部分（provider 层）
凭据处理环境变量 / 建议 vsock 注入✅ credentials extract 从本地配置抽取 key 注入沙箱（同时扩大凭据暴露面）环境变量provider 层各自处理
会话持久化BatchRunner 状态管理跨重启持久化（五选一：in-memory / Rivet Actor state / IndexedDB / SQLite / Postgres）❌Redis/S3 持久化
训练数据采集✅ ChatTracker + Span❌❌✅ Tracing（内建 OpenTelemetry）
评分✅ 内置❌❌❌（依赖外部）
Batch Runner✅❌❌❌（依赖 Temporal/外部）

Nexus 的独特优势在于训练数据采集和评测评分——这是其他社区方案不具备的。社区方案的优势在于更多 Agent 支持、更多沙箱后端、以及 CI/CD 集成。OpenAI Agents SDK 则代表了”SDK 原生嵌入沙箱”的新范式——SandboxAgent 作为 SDK 内置基类而非独立框架，与 Nexus 的 Installed Agent 理念高度相似但采用更轻量设计。

架构对照：

  • sandbox-agent LLM Proxy ≈ Nexus LLM Proxy（多模型路由 vs 单模型转发）
  • gVisor 后端 ≈ Nexus 的进程级隔离（⚠️ gVisor 说法待核实，见上文限定语）
  • 会话持久化 ≈ Nexus 的 BatchRunner 状态管理
  • OpenAI Agents SDK SandboxAgent ≈ Nexus Installed Agent（SDK 原生 vs 独立框架）
  • desktop runtime（/v1/desktop/* 截图与输入 API）= computer use 能力——Nexus 当前缺失的一层

LLM Proxy 成本优化

Nexus 的 LLM Proxy 目前专注于格式转换和训练数据采集，但社区实践表明还有显著的成本优化空间：

本地拦截策略

free-claude-code（GitHub Alishahryar1/free-claude-code）通过本地代理拦截 5 种无需调用 LLM 的请求类型（配额探测、标题生成、前缀检测等），本地直接响应，节省 API 配额。同时支持 Opus/Sonnet/Haiku 三级模型路由——简单任务用 Haiku，复杂任务用 Opus。

2026-09-17 现状：仓库星级已从本章写作时的 8900+ 涨到 55,240（GitHub 一手快照，2026-09-17），且当日仍有提交。它的形态也不再只是「本地拦截脚本」，而是长成了一层多 Provider 路由代理：官方仓库描述写明支持 Claude Code / Codex / Pi / OpenCode 等 10 个 harness（“and 6 other harnesses”），并宣称提供 1.3B+ 免费 token。二手中文资料进一步称其支持 29 个 Provider（含 NVIDIA NIM / OpenRouter / DeepSeek / Bedrock / Groq 及本地 LM Studio / llama.cpp / Ollama）、MODEL_OPUS/MODEL_SONNET/MODEL_HAIKU 可分别指向不同 provider、思考强度五档控制、Admin UI、VS Code / JetBrains ACP / Discord / Telegram 接入——按这个形态，它与 Nexus 的 LLM Proxy 是同一层东西，值得作为对照对象而非脚注。

⚠️ 合规限定：该方案是第三方非官方实现，多个二手来源提示其可能违反 Anthropic 服务条款。本章将其作为技术机制参照，不建议在生产部署中直接采用。这一点对本章「生产级安全部署」一节尤其重要——该节第 2 层把它列为应用层措施，须连同本限定语一起读。

对 Nexus 的启示

  1. 识别非关键请求：遥测、heartbeat 等请求可以本地响应，不消耗 LLM 配额
  2. 按任务复杂度路由模型：HyTuner 的 RL 训练用强模型，评测用弱模型；简单 Task 用 Haiku，复杂 Task 用 Opus
  3. DAG hook pipeline：ccproxy v2.0 采用 DAG 驱动的 hook pipeline 处理请求（而非 Nexus 的线性格式转换），更灵活——但 Nexus 的评测场景需要精确 token 计数和轨迹采集，API 层代理更适合
  4. 检查 Proxy 有没有把 prompt cache 打掉。官方 2.1.181（2026-06-17）修的正是这件事：自定义 ANTHROPIC_BASE_URL 上 prompt caching 读不到，原因是每轮的 per-request attestation token 都在变——前缀对不上，缓存全线 miss。判据因此非常简单：Proxy 往请求里注入的任何内容都必须是跨轮稳定的。注入一个每轮变化的 nonce、时间戳或 attestation，省下的那点 token 会被整段前缀重新 prefill 加倍吐出去。这一条与 Ch16 的 prompt cache 键迁移、CCI Ch19 属同一主题族，三处口径应一致。⚠️ 官方修的是 Claude Code 自己注入的 token；Nexus Proxy 是否也有逐轮变化的注入内容，需实测。

现在这条判据要从一条扩成两条，因为已有第二个实例，且它属于另一类失效：2.1.307（2026-10-21）修的是「prompt-caching-scope beta header 在自定义 ANTHROPIC_BASE_URL 网关后以及 Foundry 上仍被发送，而那里它不起作用」。注意与 2.1.181 的区别——2.1.181 是「注入内容每轮变化」，2.1.307 是「注入内容在该端点上根本无效」。判据因此应扩为两条：(a) 跨轮稳定；(b) 在该端点上真的有效。同族第三例是 2.1.310（网关拒绝 effort-2025-11-24 beta 值或中途插入的 system message），官方的修法是不带它重试——这本身就是一条可复用的网关适配模式：遇到不认识的字段，先重试一次不带它的版本，而不是直接失败。

生产级安全部署

Anthropic 官方发布的 Claude Code 安全部署文档提供了三层纵深防御架构，可直接指导 Nexus Installed Agent 的安全增强：

  1. 基础设施层：vsock 隔离通信 + Firecracker microVM 沙箱
    • vsock（虚拟套接字）替代 TCP/Unix socket，沙箱与宿主通信完全绕过网络栈，消除网络层攻击面
    • Firecracker microVM 为每个 Agent 任务提供独立内核和设备模型，比 Docker 容器隔离更强
  2. 应用层：free-claude-code 本地拦截策略（前述）
  3. 凭证层：credential injection 安全模式
    • 凭证不写入环境变量或文件，而是通过 vsock 通道临时注入进程内存，任务完成即销毁
    • 容器安全基线：只读根文件系统 + non-root 执行 + 最小 capability 集

三层纵深防御形成完整的安全边界——即使某一层被突破，后续层仍可阻止横向移动。对于 Nexus，当前安全措施集中在应用层（--print 模式限制、LLM Proxy 过滤），向基础设施层和凭证层扩展是生产级部署的必要条件。