Caveman Agent Wrapping 完全指南：将七大编码 Agent 接入本地 Token 压缩网关

Caveman 的 Agent wrapping 是一种"非侵入式"接入方案：它不替换你的编码 Agent，而是以本地代理端点、钩子（hook）、技能（skill）和恢复工具的方式，把 Aider、Claude Code、Codex、Gemini CLI、Hermes、OpenClaw、OpenCode 等 Agent 的模型流量透明地导向本地 Caveman 网关。读完本文，你能掌握 caveman wrap 的完整命令形态、profile 数据文件的字段与编译校验规则、三种运行模式（Compress / Record / Pixel）的适用边界，以及上下文压缩后的 ccr:// 恢复机制与排障流程。

核心定位：包装，而非替换

Agent wrapping 的定义非常克制：Caveman 不接管 Agent 的模型调用、用户界面、权限模型和项目工作流，这些仍然归 Agent 本身所有。它做的事情是"包装"——在 Agent 启动时注入本地端点与增强能力：

• 通过环境变量或配置文件，把 Agent 的模型流量指到本地网关；
• 通过 command hook / memory hook 压缩或增强 Agent 的本地行为；
• 通过 skills 改变 Agent 的写作方式；
• 通过 recovery 工具（caveman tools retrieve 与 MCP 集成）找回被有损压缩过的原始内容。

这一设计与 README 中"why use many token when few token do trick"的主线一致：省 token 的代价必须可控、可恢复，因此 Caveman 把"有损变换必须有恢复路径"作为硬性约束（详见后文模式一节）。

支持的 Agent：协议、注入方式与原生扩展

官方支持矩阵如下（源自 agent-wrapping.md）：

Agent	线协议（Wire protocol）	配置注入方式	原生扩展
Aider	OpenAI Chat Completions	环境变量	无
Claude Code	Anthropic Messages	环境变量	命令与记忆钩子、skills
Codex	OpenAI Responses	环境变量	命令钩子、skills
Gemini CLI	Gemini GenerateContent	环境变量	Before-tool 钩子
Hermes Agent	OpenAI Chat Completions	环境变量	插件
OpenClaw	OpenAI Chat Completions	配置文件	插件
OpenCode	OpenAI Chat Completions	配置 + 环境变量	插件

一个需要明确的前提：profile 中记录的 tested_agent_version 只是"曾经验证过的上游版本"，上游 CLI 是独立演进的。在依赖某个 profile 之前，应运行 caveman setup 检查当前安装环境的支持状态，而不是盲信文档里的版本矩阵。

各 Agent 的注入细节（来自 profile 数据文件）

每个 Agent 的行为由 agents/profiles/ 下的声明式 JSON 描述，注入细节可以从源码数据直接确认：

• Claude Code（claude.json）：协议为 anthropic-messages，通过环境变量注入 ANTHROPIC_BASE_URL={{cave_base_url}} 与 ANTHROPIC_AUTH_TOKEN={{cave_api_key}}；拥有 claude-pretooluse 命令钩子和 claude-userpromptsubmit 记忆钩子，是当前唯一验证过"实时用户提示词注入"面的 Agent；skills 目录为 ~/.claude/skills 与项目级 .claude/skills。
• Codex（codex.json）：协议为 openai-responses，injection.env 为空对象——其 injection_completeness 标注为 code-only，即声明的注入块是"惰性"的，实际路由逻辑全部在 CLI 代码里实现；命令钩子为 codex-pretooluse。
• Aider（aider.json）：协议为 openai-chat，仅注入 OPENAI_API_BASE={{cave_base_url}}/openai/v1，是最典型的"纯数据即可完成路由"（declarative）的接入。
• Gemini CLI（gemini.json）：协议为 gemini-generatecontent，同时注入 GOOGLE_GEMINI_BASE_URL 与 GOOGLE_VERTEX_BASE_URL，并带 gemini-beforetool 钩子。
• Hermes Agent（hermes.json）：协议为 openai-chat，固定附加启动参数 --provider custom，注入 CUSTOM_BASE_URL 与 CUSTOM_API_KEY，命令钩子为 hermes-plugin。
• OpenClaw（openclaw.json）：唯一一个以 config-file 方式注入的 Agent——CLI 把用户基础配置 ~/.openclaw/openclaw.json 与叠加层（overlay，注册 caveman-mcp 服务器）合并成临时配置文件，再通过 OPENCLAW_CONFIG_PATH 指给 Agent；启动参数固定为 chat。
• OpenCode（opencode.json）：采用 config-env-content 方式，将渲染好的 JSON 配置写入 OPENCODE_CONFIG_CONTENT；其 local 配置（本地 BYOK 模式）直接改写 openai/anthropic provider 的 baseURL 指向网关，managed 配置则注册独立的 caveman provider（@ai-sdk/openai-compatible，默认模型 caveman/gpt-5.5）并通过 header 透传上游密钥。

从源码结构看，"本地 vs 托管"双份配置（local / managed）是网关的通用设计：CAVE_GATEWAY_URL 指向回环地址时为本地 BYOK 模式，指向外部时为托管模式，profile 分别为两种模式准备渲染内容。

启动 Agent：命令形态与参数透传

最简形式是一组快捷命令：

caveman claude
caveman codex
caveman gemini
caveman aider
caveman hermes
caveman openclaw
caveman opencode

快捷命令之后的参数会被原样透传给被包装的 Agent：

caveman codex --full-auto

其等价的显式写法是：

caveman wrap codex --full-auto

对于 profile 目录中没有登记的任意命令，可以使用泛化入口：

caveman run -- my-agent --flag value

但要清楚泛化包装的边界：caveman run 只提供代理环境变量注入，它无法推断每个 Agent 各自的钩子或插件格式，因此原生扩展能力（命令钩子、记忆钩子、插件）只在有 profile 的 Agent 上生效。

Profile：可被 CLI 编译的数据文件

Profile 是"数据而非代码"：新增一个 Agent 意味着在 agents/profiles/ 新增一个 JSON 文件，而不是修改代码。按文档说明，一个 profile 可以声明：

• 可执行文件名与线协议；
• 环境变量或配置文件注入；
• 本地代理端点模板；
• 支持的命令钩子与记忆钩子；
• 要安装的 skills；
• 原生插件；
• 版本与能力说明。

编译器的安全边界

profile 由 compile.mjs 编译，并对照 JSON Schema（schema.json) 严格校验。编译器会拒绝未知键、不安全路径、不受支持的注入类型、保留命令冲突，以及未批准的端点模板。具体约束从 schema 中可以逐条确认：

1. 线协议是封闭枚举（schema.json#L32-L35）：只允许 anthropic-messages、openai-chat、openai-responses、gemini-generatecontent 四种，未知值会直接导致编译失败——schema 注释中将其称为"honesty: no guessed protocol"，即宁可编译报错也不猜协议。
2. 环境变量名白名单（schema.json#L9-L12）：env 键必须匹配 ^[A-Z][A-Z0-9_]*_(BASE_URL|API_BASE|API_KEY|AUTH_TOKEN|HOST)$；值的模板只允许 {{cave_base_url}}（可再拼接受控路径段）、{{cave_api_key}}、{{cave_proxy_url}}、{{cave_org_id}}。渲染后为空的变量会被直接省略，而不会被设为空字符串。
3. 注入方式四选一（schema.json#L36-L114）：env（纯环境变量）、config-env-content（内联 JSON 配置经 env 传递）、config-file（渲染临时配置文件再指路，如 OpenClaw）、native-extension（如 Pi 的 --extension 加载，host/asset/flag 全部是封闭允许清单，profile 永远不能指定任意的文件或可执行程序）。
4. 命令钩子方法与目标绑定：claude-pretooluse、codex-pretooluse、gemini-beforetool、opencode-plugin、hermes-plugin、openclaw-plugin 等均为"硬改写"面（返回改写后的命令），而 instruction-note 只是向 Agent 自动读取的指令文件（如 ~/.codex/AGENTS.md）追加一段带 HTML 注释分隔符的软性提示，属于模型相关、非确定性机制。未知方法同样导致编译失败。
5. 诚实性标签：injection_completeness 分 declarative / builder-assisted / code-only 三级，标注路由到底有多少是数据驱动的；tested_agent_version 与 last_verified_at 则受 staleness 预算约束——验证日期过期会 fail-closed，逼迫维护者重新对真实安装的二进制做核验。

这套机制的核心收益是：profile 的每一次"能力声明"都有编译器背书，profile 不能声称自己无法兑现的钩子或协议。

三种运行模式

Compress（默认）

默认的包装模式会在本地压缩符合条件的上下文，对小型结构化数据还可以使用 TOON 编码进一步缩小体积。命令输出也可能被收缩；有损变换必须有恢复存储或等价的恢复路径——这是 Compress 模式的硬约束，与后文的 ccr:// 恢复机制一一对应。

Record

caveman wrap --off claude

Record 模式只观察本地流量，不改动模型可见的请求字节。用途是建立基线、或排查集成问题：当 --off 模式下 Agent 仍失败时，可以判定问题出在请求变换之外（见排障一节）。

Pixel

caveman wrap --pixel gemini

Pixel 模式可以把文本编码为图片，供配置了视觉能力的模型消费。它是有损且依赖具体模型的：所选模型必须出现在 think.pixel.models 配置中——Caveman 不会从模型名称去推断其图片兼容性。

Agent 原生安装（Agent-native setup）

Claude Code 和 Codex 支持显式的原生安装，而不是仅在包装启动时临时生效：

caveman setup --agent-native claude
caveman setup --agent-native codex

移除方式为：

caveman setup --agent-native claude --remove

原生安装只落盘该 Agent 实际需要的文件；Caveman 的钩子与插件把本地状态保留在 Caveman 自己的目录或 Agent 自有的配置路径下。文档特别提醒：在把 dotfiles 或项目配置提交进版本库之前，先审查这些改动。

运行中的上下文恢复

被压缩的上下文里会带有 ccr_... 句柄或带类型的 ccr://... 指针。有 MCP 集成的 Agent 可以通过工具调用取回精确的原始内容；操作者也可以在终端直接取回：

caveman tools retrieve <handle>

恢复机制默认是纯本地的：句柄只在它的后端存储可用期间有效。这与压缩侧"有损必须可恢复"的约束构成闭环——压缩不是丢弃，而是把原文挪到了本地存储。

Skill 与 Hook 的职责分离

文档明确区分了两类正交的控制系统：

• Response skills 改变 Agent"怎么写"（输出风格）；
• Engine 压缩改变"发给模型的上下文"。

钩子则可以追加提醒、暴露恢复工具、或压缩命令输出。两条独立的推断规则值得记住：装了 skill 不代表请求压缩已激活，流量经过代理也不代表 response skill 已激活。二者的生命周期与信任边界，文档指引继续参见 skills-hooks-and-plugins.md。

排障清单

官方给出的六步排障顺序：

1. 运行 caveman status，确认当前选中的模式；
2. 运行 caveman setup，确认运行时二进制存在；
3. 以 --off 模式启动：如果失败依旧，问题在请求变换之外（Agent 本身、网络或凭据）；
4. 检查 provider 凭据环境变量——只确认存在，不要打印密钥值；
5. 确认 Agent 实际使用的是 profile 输出的本地端点；
6. 使用所装版本的自带 help——上游 profile 的要求可能随版本变化。

最后一条是兜底语义：当一次变换无法解析输入、无法存储恢复数据、或无法产出更小的安全输出时，Caveman 会原样发送原始输入——即网关自身永远不会成为单点故障源，退化行为是可预期的透传。

延伸阅读

• profile 注册与数据流的完整规则：agent-profile-registry.md
• skill、hook、插件的生命周期与信任边界：skills-hooks-and-plugins.md
• 网关与 provider 细节：proxy-and-providers.md
• profile 数据源目录：agents/profiles，编译脚本 agents/compile.mjs，编译产物 agents/agents.json
• 恢复存储（CCR）实现：engine/ccr/store.go