RTK 安装与配置教程
重点讲 Windows 场景、二进制安装、Claude Code 初始化与常见问题。
RTK（Rust Token Killer）是一个给 AI Coding 场景用的命令行代理工具，作用是压缩和过滤终端输出，减少大模型在读命令结果时消耗的 token。配好之后，你最直接能感受到的变化是：终端输出更短、更干净，AI 不再被大段噪音淹没，长会话里更省 token。
配好之后你会得到什么
- 常见命令输出会被压缩，减少无关噪音。
- 官方资料给出的典型节省区间是 60% - 90% token。
- README 的 30 分钟 Claude Code 会话示例里，总 token 从约 118,000 降到约 23,900，约节省 80%。
- Windows 用户也可以不用 cargo，直接下预编译二进制就能开始。
先确认你装的是不是“对的 RTK”
官方文档反复强调，安装前和安装后都要做这一步，因为存在同名项目冲突。
先跑这三个命令
不管你是第一次安装，还是怀疑自己已经装过，都先验证当前机器上的 RTK 到底是什么。
rtk --version
rtk gain
which rtk # Windows PowerShell 可改用: where.exe rtk正确结果是什么
如果 rtk gain 能显示 token 节省统计，你装的是 Rust Token Killer。若 rtk --version 能跑，但 rtk gain 提示不是有效命令，你多半装成了另一个同名项目。
rtk gain。
误装后怎么处理
如果你是通过 cargo 装错的，先卸载，再走下面推荐的安装路径。
cargo uninstall rtk你该选哪条安装路径
按“是否需要编译环境”和“是不是 Windows”来选，最不容易绕路。
路径 A：Quick Install
适合 Linux / macOS 用户，想最快装上。
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh- 这是官方 INSTALL 文档里的快捷安装方式。
- 默认安装到
~/.local/bin。 - Windows 不走这条。
路径 B：Cargo
适合已经装好 Rust，想按源码路径安装的人。
cargo install --git https://github.com/rtk-ai/rtk- 这是当前最稳的 cargo 安装方式。
- 推荐显式写
--git，避免同名包混淆。 - 装完一定再跑一次
rtk gain验证。
路径 C：预编译二进制
适合没有 cargo、只想直接下载来用的人，尤其是 Windows。
从 Releases 页面下载对应平台压缩包
macOS: *.tar.gz
Linux: *.tar.gz
Windows: rtk-x86_64-pc-windows-msvc.zip- 不用装 Rust。
- 下载、解压、加 PATH 就能跑。
- 这是 Windows 新手最省事的路线。
不推荐的做法
不要把下面这条当默认方案：
cargo install rtk- 因为存在“装到同名错误项目”的风险。
- 如果你真的这么装了，至少要马上用
rtk gain复核。
Windows 用户最推荐的配置路线
如果你主要是为了在 Claude Code、Cursor、Copilot 这类 AI Coding 工具里用 RTK，Windows 直接走“预编译二进制 + init”最省心。
下载 Windows 预编译包
打开 RTK 的 Releases 页面，下载 rtk-x86_64-pc-windows-msvc.zip。
解压到一个固定目录
建议放到你自己容易记住的位置，比如：
C:\Users\你的用户名\tools\rtk
# 或
C:\tools\rtk关键点不是目录名，而是后面要把这个目录加入 PATH。
把 rtk.exe 所在目录加入 PATH
最稳的办法是用系统环境变量界面，把上面的目录加入用户级 Path。你也可以先临时加到当前 PowerShell 会话里测试：
$env:Path += ";C:\Users\你的用户名\tools\rtk"
rtk --version
rtk gain初始化 Claude Code
RTK 不只是“装上就结束”，通常还要把 hook 接到 AI 工具里，才会自动把 Bash 命令改写成 rtk ...。
rtk init -g
# 如果你不想交互确认，可用：
rtk init -g --auto-patch
rtk init --showrtk init -g 会安装 hook、写入 RTK.md，并尝试补丁 Claude Code 的 settings.json。完成后要重启 Claude Code。
最后做一次真实验证
打开新的终端或重启 AI 工具后，至少跑下面这些：
rtk --version
rtk gain
rtk init --show如果你已经在用 Claude Code，还可以再试一个常见命令，例如 git status，看输出是否变得更紧凑。
如果你已经装了 cargo，推荐这样装
这条路径更适合开发者，尤其是已经有 Rust 环境的人。
直接从 GitHub 仓库安装
cargo install --git https://github.com/rtk-ai/rtk这样能明确指向 Rust Token Killer 仓库，不容易装错。
如果命令找不到，多半是 PATH 没配
官方 Troubleshooting 里专门提到：很多人编译成功了，但 ~/.cargo/bin 没在 PATH 里。
# bash / zsh
export PATH="$HOME/.cargo/bin:$PATH"
# 然后重新打开终端，或 source 对应配置文件Windows 上要注意版本别太老
官方 Troubleshooting 提到，Windows 对 .CMD / .BAT 包装脚本的解析问题在 v0.23.1+ 已修复。现在只要用较新的 RTK 版本，一般不需要你自己补 workaround。
Claude Code / Cursor / 其他工具怎么配
RTK 的价值不只是单独跑命令，而是接到 AI 工具的 hook 里，让命令自动改写。
Claude Code
rtk init -g
# 或
rtk init -g --auto-patch这是默认主线。官方说明会安装 hook 到 ~/.claude/hooks/rtk-rewrite.sh，并处理 RTK.md / settings.json。
Cursor
rtk init -g --agent cursor会写入 Cursor 的 hook 配置，适合你已经把主力环境放在 Cursor。
Gemini CLI
rtk init -g --gemini适合想把同一套 token 压缩逻辑接到 Gemini CLI 上的人。
Codex / Copilot / Cline
rtk init -g --codex
rtk init -g --copilot
rtk init --agent cline不同工具的接入方式不同，但思路一样：先装 RTK，再跑对应的 init 命令，最后重启工具。
常见问题
Q: 没有 cargo，能不能直接下载二进制文件？
A: 可以，尤其 Windows 很适合这样做。去 Releases 下载 rtk-x86_64-pc-windows-msvc.zip，解压后把 rtk.exe 所在目录加到 PATH，再跑 rtk --version 和 rtk gain 验证即可。
Q: 为什么 rtk --version 能跑，但 rtk gain 不行？
A: 这通常说明你装错了同名项目，装成了 Rust Type Kit。先卸载，再改用 cargo install --git https://github.com/rtk-ai/rtk 或直接下载官方预编译二进制。
Q: Windows 上 rtk lint、rtk vitest 报 “program not found” 怎么办？
A: 官方 Troubleshooting 提到这是旧版在 Windows 解析 .CMD/.BAT 包装脚本时的已知问题，升级到 v0.23.1+ 或更新版本即可。
Q: 明明装好了，Claude Code 里还是没生效？
A: 先跑 rtk init --show 检查 hook 状态，再重启 Claude Code。若你选择了手动配置模式，还要确认 settings.json 里确实已经注册 RTK 的 PreToolUse hook。
Q: Quick Install 为什么不推荐给 Windows？
A: 因为官方快捷脚本主要是 Linux/macOS 路线。Windows 用户直接下载 zip 并配 PATH，更直观，也更少碰到 shell 差异问题。
这页主要依据
内容按你给的三个入口整理，安装命令和判断标准都以官方仓库文档为准。
https://github.com/rtk-ai/rtk/blob/master/docs/TROUBLESHOOTING.md