章节导航 第 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.289（2026-10-03 发布）
codexnpm install @openai/codex2.8KB相对简单0.160.1（2026-10-05 发布）
gemini_clinpm install @google/gemini-cli4.5KB需要 Node.js 20+，自动检测版本npm 0.62.0（2026-09-29 发布）
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 个版本。这个漂移率意味着任何写死版本号的句子都会很快过期。本节的全部结论都不依赖具体版本号，依赖的是机制（装什么、怎么起代理、数据怎么采）；版本列只是给读者一个”我当时看到的是这个”的参照。

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 自己猜。

跨章看，这是同一条链路的三段：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

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 上下文窗口（见上一节的紧急提示）行为变更

三个多月里六条，其中两条被官方自己标注为前一版本的 regression，两条是凭据外泄路径。这意味着”配好一次就能一直跑”的假设不成立。三条缓解：

  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 发去了错误的地方——这是最坏的一类失败：不报错，只是悄悄错。

训练数据采集

关键收益：所有 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/sandbox-agent，约 1.6k stars，Apache-2.0）：

  • 凭据抽取：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 })163本章描述的这一版。npm agentbox-sdk 最新 0.1.512（2026-09-16），仍在活跃迭代
madarco/agentboxCLI + macOS 菜单栏应用，隔离 VM + checkpointing（从检查点恢复 <1 秒）+ parallel boxes + project teleportation406活跃演化中的另一版，支持 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/仓库核。

交叉引用：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 是否也有逐轮变化的注入内容，需实测。

生产级安全部署

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 过滤），向基础设施层和凭证层扩展是生产级部署的必要条件。