如何快速安装Caveman:3分钟上手支持30+ AI编程Agent的token压缩工具教程
Caveman 是一款免费开源的 AI 编程 Agent token 压缩工具,口号是"为什么用很多 token,当少数 token 也能搞定"。它让 Claude Code、Codex、Gemini、Cursor 等 30+ 款 AI 编程 Agent 用"原始人"式的简短风格回答,实测 10 项编码任务平均节省 65% 的输出 token;配套 Caveman Proxy 还能在请求发出前压缩 Agent 读取的内容,固定基准测试中输入 token 减少 33.2%。本教程带你 3 分钟完成安装,支持 macOS / Linux / Windows 全平台。
安装前准备:3个前提条件 ⚡
| 条件 | 说明 |
|---|---|
| Node.js | Skill 安装器需 Node.js 18+;本地运行时 CLI 需 Node.js 22.13+ |
| 操作系统 | macOS / Linux / Windows(amd64 和 arm64 均有预编译二进制) |
| 至少一个 Agent | 已安装 Claude Code、Codex、Gemini CLI、Cursor、Windsurf 等任意一个 |
Caveman 有两个可以单独或同时使用的组件:
- Skill(省输出):Agent 回答更短,代码、命令、报错保持精确;
- Caveman Proxy(省输入):本地代理在每次模型调用前压缩 Agent 读取的内容,原始字节可精确恢复。
方式一:一键安装 Skill(新手最快路径)🪨
打开终端,执行一条命令:
npx skills add JuliusBrussee/caveman
安装器会自动扫描你机器上已安装的 Agent 并只配置匹配项。装完后在任意支持会话内输入 /caveman 即可激活,用 /caveman lite|full|ultra 切换强度,/caveman off 关闭。
压缩效果对比(同一个 React 重渲染问题的回答):
内置 6 档强度,其中还有文言文模式,中文用户福音:
| 档位 | 效果 |
|---|---|
lite | 去掉废话和客套,保留完整句法,专业且紧凑 |
full | 默认档。去掉冠词、允许短句片段,经典"原始人"风格 |
ultra | 极致压缩,能一词说清绝不用两句 |
wenyan-lite / full / ultra | 半文言 → 全文言 → 极致缩写,字符缩减 80–90% |
Skill 完整规则定义见 skills/caveman/SKILL.md。
方式二:安装 Caveman Proxy(再省输入 token)
想连"Agent 读什么"也一起压缩,安装本地运行时 CLI:
npm install -g @caveman-ai/cli
caveman setup --install
caveman claude # 之后用 codex / gemini / aider / opencode / hermes / openclaw / pi 替换
setup --install 会自动下载并校验签名和 SHA-256 的配套二进制,安装到 ~/.caveman/bin。之后 caveman <agent> 会持久开启该 Agent 的原生集成并启动它,不满意随时用 caveman disable <agent> 撤销;caveman wrap <agent> 则只对当前会话临时生效。
整个封装架构有 8 个原生 Agent 档案(Claude Code、Codex、Gemini、Aider、opencode、Hermes、OpenClaw、Pi),档案定义在 agents/profiles/ 目录下,只是 JSON 数据文件,扩展新 Agent 无需改代码。
方式三:克隆仓库手动安装(进阶可选)
想看清每一步执行了什么命令,可以克隆源码安装:
git clone https://gitcode.com/GitHub_Trending/caveman1/caveman
cd caveman
node bin/install.js --dry-run --all # 先预览所有将执行的命令
node bin/install.js --list # 查看完整的 30+ Agent 支持矩阵
node bin/install.js --all # 对检测到的所有 Agent 安装
常用参数:--only <id> 只装一个 Agent、--minimal 只装插件不带钩子、--with-init 为 Cursor/Windsurf/Cline 等无钩子系统的 Agent 写入 always-on 规则文件。Windows 手动回退方案见 docs/install-windows.md。
安装后验证:3步确认 Caveman 已生效 ✅
第 1 步,查看检测结果:
node bin/install.js --list
应看到约 30 行 Agent 列表,已安装的会标记出来。没标记说明该 Agent 的可执行文件不在 PATH 中,先解决 PATH。
第 2 步,在 Claude Code 中输入 /caveman,应回复一句简短的确认(如 "Caveman mode on.")。再问"JS 闭包是什么",回答应该像" grunt 式"短句——没有 "Sure! I'd be happy to help..."。
第 3 步,检查激活标志文件:
cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.caveman-active"
# 期望输出: full
安装成功后,Claude Code 底部状态栏会显示橙色的 [CAVEMAN],跑过 /caveman-stats 还会追加已节省的 token 计数。
进阶玩法:用 caveman learn 找出你的 token 大头 📊
装好 Proxy 后,Caveman 能读取你本机的 Agent 历史记录(本地只读、无需账号),输出一份"token 开销体检报告":
caveman learn # 扫描 Claude Code / Codex / Gemini / opencode 历史
caveman learn implement # 把修复计划交给你的 Agent 逐条确认执行
报告包含你的 Cave Score、按流量排序的 token 黑洞清单(每行附一行修复建议)、会话上下文深度直方图,以及"这些修复若提前执行,过去能省下多少 token"的回放测算:
常见问题速查(FAQ)❓
Q:装好了但 Claude Code 不会说"原始人话"? 按顺序排查:--list 确认检测到 claude → 检查 ~/.claude/settings.json 的 hooks 中是否有 caveman-activate.js(缺失则加 --force 重装)→ 确认 .caveman-active 存在且内容为 full → 重启 Claude Code(SessionStart 钩子只在会话开始时触发)。
Q:为什么这个窗口是 caveman 模式,另一个不是? 这是设计如此——模式按窗口独立保存,在需要的窗口里输入 /caveman 即可。
Q:Windows 上钩子报错? 用 PowerShell 的 install.ps1 而非 install.sh(Git Bash 可用 shell 版,但钩子侧需要 PowerShell 5.1+ 对应件),执行策略被拦截时先 Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass。
Q:怎么卸载?
npx -y github:JuliusBrussee/caveman -- --uninstall # 移除钩子、插件、模式状态
npm uninstall -g @caveman-ai/cli # 移除全局 CLI
注意:npx skills add 装的 Skill 需另行执行 npx skills remove caveman;~/.claude/.caveman-history.jsonl 的历史统计文件不会自动删除。
Q:数据安全吗? Skill 与钩子全部本地运行,Proxy 只把请求转发给你自己选的模型服务商,CCR 恢复副本存在本地 SQLite 文件中;CLI 默认发送的匿名统计只含命令名和 token 计数,不含提示词、代码或文件路径,一条 caveman telemetry off 可永久关闭。完整数据边界见 SECURITY.md。
延伸阅读 📚
| 资料 | 路径 |
|---|---|
| 完整安装矩阵(30+ Agent 命令表) | INSTALL.md |
| 安装/更新/卸载技术手册 | docs/technical/install-and-update.md |
| Windows 手动回退指南 | docs/install-windows.md |
| Skill 压缩规则原文 | skills/caveman/SKILL.md |
| Agent 封装档案 | agents/profiles/ |
| 技术文档总入口 | docs/README.md |
Caveman 一句话总结:让 Agent 少说、少读、少花钱——少 token,不撒谎,就这么简单。🪨
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考







