RTK 省 token 配置

RTK 是给 Claude Code / Codex 这类 coding agent CLI 用的本机命令输出压缩工具。

一句话：你正常给 agent 发任务；agent 跑长命令时，RTK 把测试日志、diff、报错堆栈压短，再交给模型读取。

不是 prompt 前缀不要写“rtk 请运行测试”。你照常发任务，RTK 只处理命令输出路径。

不是 Pragma API 服务RTK 装在你的电脑，不进入 pragma.academic-ruc.cc 的模型中转热路径。

终端 CLI 最有效VSCode terminal 按 CLI 处理；官方 sidebar 和桌面端不承诺自动省 token。

Claude 是透明 hookClaude transcript 可能仍显示原始 Bash；是否命中 RTK 要看 session 和 gain，不只看聊天记录里有没有 rtk 前缀。

本页与图像生成分开

本页只讲 RTK 省 token。图像生成配置见图像生成与 skill。

先分清两类省 token 问题

RTK 和 cache-fix 不是互相替代的工具。先按你的问题选路线，避免把两个环境变量和两套验证方式混在一起。

命令输出太长测试日志、git diff、docker logs、报错堆栈太长，先看 RTK。本页解决的是 shell 输出进入模型上下文前的压缩。继续看 RTKClaude Code 缓存不稳经常 resume、MCP/Skills 很多、长会话额度掉得快，去看 cache-fix。它是 Claude Code 请求层代理，不适用于 Codex。查看 cache-fix

不要混用同一个 ANTHROPIC_BASE_URL

直连 Pragma 的 Claude Code 使用 ANTHROPIC_BASE_URL=https://pragma.academic-ruc.cc。启用 cache-fix 时，这个变量必须改成本机代理 http://127.0.0.1:9801，再由 CACHE_FIX_PROXY_UPSTREAM=https://pragma.academic-ruc.cc 转回 Pragma。

认证方式不会改变 RTK 结论

RTK 位于本机 shell 输出层，不读取 API key，也不代理模型请求。因此下面四条认证路径使用同一套 RTK 逻辑：

Agent	认证 / provider	RTK	cache-fix
Claude Code	Pragma API key	可用	可选；upstream 指向 Pragma
Claude Code	官方 API key	可用	可选；默认官方 upstream
Claude Code	OAuth / Max / Pro	可用	可选；OAuth refresh 默认保持 off
Claude Code	其他 Anthropic-compatible 中转	可用	条件适用，先验证协议与认证头
Codex	OAuth / API key / custom provider	可用	不适用
Copilot CLI	GitHub 认证	可用	不适用

如果你还没确定组合，先用省 token 决策中心。不要为了安装 RTK 改写现有 OAuth、API key、Base URL 或 provider。

先选你的使用环境

先判断路径，再看安装命令。这样避免 Windows 原生、VSCode sidebar、Codex bridge 被误读成“稳定自动生效”。

系统WSL 推荐

AgentClaude CLI hook 最稳

入口terminal 才按 CLI 规则

安装和自动生效分开看

“能安装”不等于“能自动省 token”。用户最容易在这里误判。

能安装吗？

Windows WSL / Claude CLI是

Windows WSL / Codex CLI是，需信任 hook

Windows 原生 PowerShell是，有限

macOS / terminal CLI是

VSCode sidebar / 桌面端不作为入口

能自动省 token 吗？

WSL/macOS + Claude CLI稳定 hook

WSL/macOS + Codex CLI已验证，仍需本机 E2E

Windows 原生 PowerShell不保证

VSCode terminal按 CLI 环境

VSCode sidebar / 桌面端不承诺

安装前先做边界自检

WSL 用户必须先看一眼 claude / codex 到底装在哪里。这个检查在 WSL terminal 里运行，不是在 agent 聊天框里运行：

bash

which claude || true
which codex || true

如果看到类似下面这种路径：

text

/mnt/c/Users/你的用户名/AppData/Roaming/npm/claude
/mnt/c/Users/你的用户名/AppData/Roaming/npm/codex

这说明你虽然在 WSL 里敲命令，但实际启动的是 Windows 端 agent。这种情况下 WSL hook 不会被 Windows agent 读取，当前安装脚本会主动停止并提示 STOP_WITH_GUIDANCE。这是保护机制，不是脚本坏了。

你有两个选择：

选择	适合谁	结果
在 WSL 内安装/使用 Claude Code 或 Codex，再跑 WSL 安装命令	想要稳定自动省 token 的用户	推荐
回到 Windows PowerShell 跑 Windows 原生命令	只想装 RTK.exe、接受手动/实验能力的用户	Claude 无自动 hook

安装主线

正常安装路径只讲主线。失败原因统一放到后面的“问题排查”，不打断流程。

进入 WSL不要在 PowerShell 里跑这条

边界自检which claude/codex 不能指向 /mnt/c

执行脚本优先从本站镜像下载

重启工具重启 Claude/Codex/VSCode terminal

正常发任务不用在 prompt 前加 rtk

看 gain~/.pragma/bin/rtk gain --history

Windows WSL 安装命令

curl -fsSL https://docs.academic-ruc.cc/downloads/pragma_agent_setup.py -o /tmp/pragma_agent_setup.py
python3 /tmp/pragma_agent_setup.py --mode wsl --agents codex,claude

前置条件已安装 WSL / Ubuntu，python3 可用

成功信号RTK present 只是本体安装；E2E 才算自动生效

如果停止检测到 Windows shim 时会 STOP_WITH_GUIDANCE，这是保护不是故障

装完以后怎么用

安装完成后，先在 WSL/macOS terminal 里确认 RTK 本体可用：

bash

source ~/.bashrc 2>/dev/null || source ~/.zshrc 2>/dev/null || true
type rtk || command -v rtk || ~/.pragma/bin/rtk --help

看到类似下面任意一种结果，就说明 RTK 本体装好了：

text

rtk is /home/你的用户名/.pragma/bin/rtk
/home/你的用户名/.pragma/bin/rtk
RTK - Repository Tool Kit

然后关闭并重新打开 Claude Code / Codex / VSCode terminal。重启以后，正常发任务：

请检查当前项目的 git diff 和测试结果，定位最需要修复的问题。读取长命令输出时请优先使用 RTK。

不要把 RTK 写进聊天前缀

不要写 rtk 请运行测试。RTK 是命令输出过滤器，不是聊天指令前缀。

怎么证明真的省 token

不要只看“安装成功”。当前安装器把结果分成四层：

层级	含义	能不能说自动省 token 已生效
`install_success`	RTK 二进制能运行	不能
`hook_configured`	RTK 自己识别 hook，或 Codex bridge 条目 + fixture 通过	还不能
`fixture_passed`	样例命令能被改写	还不能
`e2e_verified`	重启真实 agent 后，`rtk session` 或 `gain --history` 出现新的真实任务记录	可以

判断顺序不要反过来：先看 session 是否记录当前 Claude/Codex 会话，再看 gain --history 省了多少，最后用 discover 找漏网命令。discover 不是判断 hook 是否失效的唯一依据。

1. 先确认短命令可用

这一步在 WSL/macOS terminal 里运行，不是发给 Claude/Codex 的聊天 prompt：

bash

type rtk || command -v rtk || ~/.pragma/bin/rtk --help

如果这里找不到 rtk，先不要测省 token，直接看下方“rtk 找不到”。

2. 重启 agent，跑一次真实长输出任务

关闭旧的 Claude Code / Codex，重新打开。然后在 agent 聊天里发这种任务：

text

请检查当前项目的 git diff 和测试结果，定位最需要修复的问题。读取长命令输出时请优先使用 RTK。

这句话是发给 agent 的。它会让 agent 自己去跑 shell 命令；RTK 只在这些 shell 命令输出进入模型上下文前起作用。

3. 回到 terminal 看当前会话是否命中

这条命令不是发给 Claude/Codex 的聊天 prompt。它是在 WSL/macOS terminal 里运行的：

可以退出 Claude/Codex 后，在同一个 WSL terminal 里运行。
也可以另开一个 WSL terminal 运行。
当前 terminal 如果提示 rtk: command not found，先用完整路径。

bash

~/.pragma/bin/rtk session

如果你刚退出的 Claude Code 提示类似 claude --resume 2da271fe-...，而 rtk session 里也出现 2da271fe 这一行，并且 RTK 列大于 0，就说明这次 Claude 会话已经命中 RTK。Adoption 表示这次会话里有多少 Bash 命令走到了 RTK，不要求必须是 100%。

4. 再看实际省了多少

继续在 WSL/macOS terminal 里运行：

bash

~/.pragma/bin/rtk gain --history

如果你使用本站一键脚本，也可以在真实 agent 任务跑完后执行二次校验：

bash

python3 /tmp/pragma_agent_setup.py --mode wsl --verify-rtk

macOS 把 --mode wsl 换成 --mode macos。Windows PowerShell 用：

powershell

py -3 "$env:TEMP\pragma_agent_setup.py" --mode windows-native --verify-rtk

新开的 WSL/macOS terminal 会读取 shell profile，通常也可以直接运行：

bash

rtk gain --history

示例：

text

recent commands
git diff
  raw tokens: 57.6K
  filtered tokens: 0.3K
  tokens saved: 57.3K (99.5%)

百分比的含义

tokens saved: 57.3K (99.5%) 只描述“某条命令输出被压缩的比例”，不代表整个 Claude/Codex 会话免费，也不代表所有 token 都被省掉。

为什么 Claude Code 里看不到 `rtk` 前缀？

Claude Code 的稳定路线是 Bash PreToolUse hook。Claude 聊天记录里通常显示 agent 原本想执行的 Bash，例如：

text

Bash(git status && git diff --stat && ls -la && cat package.json)

RTK hook 会在执行前透明改写其中可识别的命令。因此聊天记录里看不到 rtk，不代表没生效。是否生效要看 rtk session 和 rtk gain --history，例如同一个 Claude session 可能显示：

text

Session      Cmds   RTK  Adoption
2da271fe       9     5      56%

这表示该 Claude 会话 9 条 Bash 命令里有 5 条走到了 RTK。

哪些命令不会自动省 token？

RTK 不是通用 shell 沙箱，也不会改写所有 Claude 工具调用。下面这些情况不能按“自动省 token”承诺：

类型	原因
Claude 内置 `Read` / `Grep` / `Glob`	不经过 Bash hook
MCP 工具调用	不经过 Bash hook
`tmux-bridge read/message/keys`	当前 RTK 规则未覆盖
复杂 here-doc、交互式命令、特殊 shell 片段	可能被安全跳过或 fallback
VSCode sidebar / 桌面端 App	不承诺读取 CLI hooks

如果这些命令很多，rtk discover 会把它们列为 missed savings 或 unhandled commands。这是优化线索，不等于 Claude Code 没安装好。

5. 用 discover 找漏网命令

discover 用来找“本来可以省、但这次没有省”的命令，不要单独拿它判定安装失败：

bash

~/.pragma/bin/rtk discover

如果 rtk session 已经显示当前会话有 RTK adoption，但 discover 仍列出 missed savings，通常说明：

Claude transcript 里保存的是原始 Bash，hook 改写后的内部命令另记在 RTK history。
某些命令没有被 RTK 规则覆盖。
Agent 使用了内置工具或 MCP，不经过 Bash hook。

6. 再看 setup-report

安装脚本会写入：

这条也在 WSL/macOS terminal 里运行，不是在聊天窗口里发给 agent：

bash

cat ~/.pragma/setup-report.json

重点看这些字段：

字段	怎么理解
`rtk`	`present` 只说明 RTK 本体装上了。
`codex_hook`	`bridge/native` 只是配置状态，不等于 E2E 已证明。
`agent_detection`	显示 `claude/codex` 是 WSL 原生、Windows shim、Windows 原生还是 macOS 原生。
`hook_configured`	Claude 必须由 RTK 自己识别；Codex 需要条目存在并通过 fixture。
`e2e_verified`	初装后通常是 `pending`；只有二次校验通过才是真正生效。
`support_tier`	当前 agent 路径是 `stable-cli`、`experimental-cli` 还是其他状态。
`bridge_reason`	为什么选择 native / bridge / instructions-only。
`rewrite_verified`	`false` 未验证；`fixture` 只过样例；`e2e` 才能升级为已验证。

分清三件事

RTK: present = RTK 二进制装上了。

codex_hook: bridge / Claude settings 有 hook = 配置写进去了。

rtk session 或 gain --history 出现新的 Claude/Codex 任务记录 = 这次真实任务确实走到了 RTK。

辅助命令：

bash

~/.pragma/bin/rtk session
~/.pragma/bin/rtk discover

可以直接丢给 agent 的安装任务

Windows WSL

text

请帮我在 Windows WSL 中安装 Pragma RTK。
注意：RTK 不是 prompt 前缀，是 agent 读取长命令输出时用的过滤器。

请按顺序做：
1. 确认当前在 WSL 里；
2. 先执行边界自检：
   which claude || true
   which codex || true
   如果结果指向 /mnt/c/Users/...，说明当前是 Windows shim，WSL 自动 hook 不会生效；请先停下来告诉我。
3. 执行：
   curl -fsSL https://docs.academic-ruc.cc/downloads/pragma_agent_setup.py -o /tmp/pragma_agent_setup.py
   python3 /tmp/pragma_agent_setup.py --mode wsl --agents codex,claude
4. 在 WSL terminal 里执行：
   ~/.pragma/bin/rtk --help
   ~/.pragma/bin/rtk git status
   ~/.pragma/bin/rtk gain --history
   cat ~/.pragma/setup-report.json
5. 如果看到 RTK: present，只能告诉我“RTK 本体安装成功”；是否真的省 token，要等我重启 agent、跑真实长输出任务，再执行 --verify-rtk。

Windows PowerShell

text

请帮我在 Windows PowerShell 中安装 Pragma RTK。
注意：Windows 原生不保证自动触发省 token 功能，不保证自动在 prompt 之前加前缀 rtk；RTK 也不是聊天 prompt 前缀。

请按顺序做：
1. 执行 py -3 --version；
2. 执行：
   iwr https://docs.academic-ruc.cc/downloads/pragma_agent_setup.py -OutFile "$env:TEMP\pragma_agent_setup.py"
   py -3 "$env:TEMP\pragma_agent_setup.py" --mode windows-native --agents codex,claude
3. 执行：
   $HOME\.pragma\bin\rtk.exe --help
   $HOME\.pragma\bin\rtk.exe git status
   Get-Content "$HOME\.pragma\setup-report.json"
4. 明确告诉我：Claude Windows 原生没有自动 hook，只能手动/指令使用 rtk；如果需要稳定自动改写，请建议我改用 WSL-native。

macOS

text

请帮我在 macOS 中安装 Pragma RTK。
注意：RTK 不是 prompt 前缀，是 agent 读取长命令输出时用的过滤器。

请按顺序做：
1. 执行 python3 --version；
2. 执行：
   curl -fsSL https://docs.academic-ruc.cc/downloads/pragma_agent_setup.py -o /tmp/pragma_agent_setup.py
   python3 /tmp/pragma_agent_setup.py --mode macos --agents codex,claude
3. 执行：
   ~/.pragma/bin/rtk --help
   ~/.pragma/bin/rtk git status
   cat ~/.pragma/setup-report.json
4. 提醒我重启 Claude Code / Codex，跑真实长输出任务后，再在 macOS terminal 里用 ~/.pragma/bin/rtk gain --history 或 --verify-rtk 验证。

本站托管的安装资源

为了减少中国大陆用户访问 GitHub release 超时，Pragma docs 托管了安装需要的 RTK 文件。一键脚本会优先从本站下载，不需要用户直接访问 GitHub releases。

平台	下载
Windows x64	rtk-x86_64-pc-windows-msvc.zip
WSL / Linux x64	rtk-x86_64-unknown-linux-musl.tar.gz
WSL / Linux arm64	rtk-aarch64-unknown-linux-gnu.tar.gz
macOS Intel	rtk-x86_64-apple-darwin.tar.gz
macOS Apple Silicon	rtk-aarch64-apple-darwin.tar.gz
Codex bridge	bridge 目录说明
Manifest	manifest.json

问题排查

WSL 安装时出现 `STOP_WITH_GUIDANCE`

这通常不是故障，而是脚本检测到：

text

/mnt/c/Users/.../AppData/Roaming/npm/claude
/mnt/c/Users/.../AppData/Roaming/npm/codex

这代表你在 WSL 里启动的是 Windows 端 agent。WSL 里的 ~/.claude/settings.json、~/.codex/hooks.json 不会被 Windows 进程读取，所以脚本停止，避免制造“装好了但实际没生效”的假成功。

处理方式：

想要稳定自动省 token：在 WSL 内安装并使用 Claude Code / Codex，再重新运行 WSL 命令。
只想在 Windows 原生里使用：回到 PowerShell 跑 Windows 原生命令。注意 Claude Windows 原生没有自动 hook，只能手动/指令 rtk <cmd>。

安装包下载失败

先在浏览器打开对应下载链接。如果浏览器也打不开，先处理本机网络或 DNS。脚本默认走本站镜像，而不是 GitHub release。

`rtk` 找不到

先用完整路径验证：

bash

~/.pragma/bin/rtk --help

Windows PowerShell：

powershell

$HOME\.pragma\bin\rtk.exe --help

完整路径可用，说明 RTK 已安装，只是终端或 agent 没刷新。重启终端、VSCode、Claude Code 或 Codex。

当前 WSL/macOS terminal 不想重开，也可以先临时补一次：

bash

source ~/.bashrc 2>/dev/null || source ~/.zshrc 2>/dev/null || true
type rtk || export PATH="$HOME/.pragma/bin:$PATH"

然后再看：

bash

type rtk
~/.pragma/bin/rtk session
~/.pragma/bin/rtk gain --history

如果还不行，临时用完整路径即可：

bash

export PATH="$HOME/.pragma/bin:$PATH"
~/.pragma/bin/rtk gain --history

安装脚本会把这条 PATH 写入 shell profile；新开的 WSL/macOS terminal 会自动生效。

Codex 还是没有自动使用 RTK

先看：

bash

cat ~/.pragma/setup-report.json

如果 codex_hook 是 bridge 或 native，只能说明配置已经写入。真正是否生效，要继续看 rewrite_verified、~/.pragma/bin/rtk session 和 ~/.pragma/bin/rtk gain --history。

如果你用的是 VSCode Codex sidebar，不要直接按 CLI 结果判断。当前可解释、可验证的是 CLI / terminal 路线，sidebar 是否读取 CLI hooks 不作为承诺。

没有 `session` / `gain --history` 记录

常见原因：

你用的是 VSCode sidebar 或桌面端，不是 terminal CLI。
WSL 里 which claude / which codex 指向 /mnt/c/...，实际 agent 在 Windows 侧。
Agent 用了内建 Read/Grep/Glob，而不是 shell 命令。
Windows 原生 PowerShell 跑了复杂管道、变量或 cmdlet，bridge 故意跳过。

如果 rtk session 已经显示当前 Claude 会话有 adoption，但 rtk discover 仍列出 missed savings，优先解释为“还有命令没有被 RTK 覆盖”。不要直接判定 Claude Code 没装好。

不要用 `rtk --version` 当唯一验证

部分版本下 rtk --version 行为可能和预期不一致。更稳的验证方式是：

bash

~/.pragma/bin/rtk --help
~/.pragma/bin/rtk git status
~/.pragma/bin/rtk session
~/.pragma/bin/rtk gain --history

上游与 bridge 状态

项	当前口径
一键脚本版本	`2026.07.10-r10`
RTK 镜像版本	`v0.43.0`
Codex 默认路线	`bridge`；macOS/WSL CLI 已做 E2E，新机器仍需信任与复验
`rtk init --codex`	稳定版已支持写入 Codex 指令，但不等于透明命令 hook
`rtk hook codex`	稳定版尚未发布，因此仍需 bridge
PR #2927 / issue #1812	官方 Codex command rewrite 的跟踪入口，仍为 open
Codex hook 输出	必须同时返回 `permissionDecision=allow` 与 `updatedInput.command`；sandbox/审批仍由 Codex 执行

RTK 省 token 配置 ​

先分清两类省 token 问题 ​

认证方式不会改变 RTK 结论 ​

先选你的使用环境 ​

推荐路径：WSL/macOS 原生 Claude Code CLI

安装和自动生效分开看 ​

能安装吗？

能自动省 token 吗？

安装前先做边界自检 ​

安装主线 ​

Windows WSL 安装命令

装完以后怎么用 ​

怎么证明真的省 token ​

1. 先确认短命令可用 ​

2. 重启 agent，跑一次真实长输出任务 ​

3. 回到 terminal 看当前会话是否命中 ​

4. 再看实际省了多少 ​

为什么 Claude Code 里看不到 rtk 前缀？ ​

哪些命令不会自动省 token？ ​

5. 用 discover 找漏网命令 ​

6. 再看 setup-report ​

可以直接丢给 agent 的安装任务 ​

Windows WSL ​

Windows PowerShell ​

macOS ​

本站托管的安装资源 ​

问题排查 ​

WSL 安装时出现 STOP_WITH_GUIDANCE ​

安装包下载失败 ​

rtk 找不到 ​

Codex 还是没有自动使用 RTK ​

没有 session / gain --history 记录 ​

不要用 rtk --version 当唯一验证 ​

上游与 bridge 状态 ​

RTK 省 token 配置

先分清两类省 token 问题

认证方式不会改变 RTK 结论

先选你的使用环境

安装和自动生效分开看

安装前先做边界自检

安装主线

装完以后怎么用

怎么证明真的省 token

1. 先确认短命令可用

2. 重启 agent，跑一次真实长输出任务

3. 回到 terminal 看当前会话是否命中

4. 再看实际省了多少

为什么 Claude Code 里看不到 `rtk` 前缀？

哪些命令不会自动省 token？

5. 用 discover 找漏网命令

6. 再看 setup-report

可以直接丢给 agent 的安装任务

Windows WSL

Windows PowerShell

macOS

本站托管的安装资源

问题排查

WSL 安装时出现 `STOP_WITH_GUIDANCE`

安装包下载失败

`rtk` 找不到

Codex 还是没有自动使用 RTK

没有 `session` / `gain --history` 记录

不要用 `rtk --version` 当唯一验证

上游与 bridge 状态