RTK Windows 安装记录

本文档记录当前项目在 Windows 环境下安装 RTK 的实际过程，适用于已经拿到 rtk.exe 二进制文件并希望在 Codex 中使用 RTK 的场景。

环境信息

操作系统：Windows 10 / 11
终端：PowerShell
Codex：Windows 原生环境
RTK 可执行文件路径：D:\ProgramFiles\rtk\rtk.exe

背景

最开始尝试使用官方 Unix 安装命令：

bash 复制代码

curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

在 Git Bash 中会报错：

text 复制代码

Unsupported operating system: MINGW64_NT-10.0-19045

原因是官方 install.sh 仅支持 Linux 和 macOS，不支持 Git Bash 的 MINGW64_NT-* 环境。因此在 Windows 下应改用预编译好的 rtk.exe。

安装步骤

1. 下载 Windows 可执行文件

从 RTK 发布页下载 Windows 版本压缩包，解压后拿到 rtk.exe，并放到固定目录：

text 复制代码

D:\ProgramFiles\rtk\rtk.exe

注意：配置环境变量时，加入的是目录 D:\ProgramFiles\rtk，不是 D:\ProgramFiles\rtk\rtk.exe。

2. 配置用户级 PATH

在 PowerShell 中执行：

powershell 复制代码

[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";D:\ProgramFiles\rtk",
  "User"
)

$env:Path += ";D:\ProgramFiles\rtk"

说明：

第一段会把 D:\ProgramFiles\rtk 永久写入当前用户的 Path
第二段让当前终端会话立刻生效

3. 验证 RTK 是否可用

执行：

powershell 复制代码

rtk --version
Get-Command rtk

如果命令可用，说明 PATH 已经配置成功。

4. 初始化 Codex 集成

执行：

powershell 复制代码

rtk init -g --codex
rtk init --show --codex

其中：

rtk init -g --codex 用于写入 Codex 的全局 RTK 配置
rtk init --show --codex 用于查看初始化结果，不加 codex 的话会查看 .claude 下的内容

执行完成后，建议重新打开一次 Codex 或终端会话，让新配置被完整加载。

有可能需要先执行 rtk init -g，遇到选择直接 yes

安装后检查

可以重点检查以下文件是否已经生成：

text 复制代码

C:\Users\xxxxx\.codex\RTK.md
C:\Users\xxxxx\.codex\AGENTS.md

如果这两个文件存在，通常说明 rtk init -g --codex 已成功写入全局规则。

Codex 沙箱与统计排查记录

在 Windows 原生 Codex 环境下，rtk 命令本身可以正常执行，但涉及 tracking database 的统计命令在沙箱内可能失败。

1. 现象

在沙箱内执行：

powershell 复制代码

rtk gain
rtk gain --history

可能报错：

text 复制代码

rtk: Failed to initialize tracking database: unable to open database file: Error code 14: Unable to open the database file

2. 原因判断

实际排查结果表明：

rtk 配置文件存在：C:\Users\xxxxx\AppData\Roaming\rtk\config.toml
tracking.enabled = true
历史数据库存在：C:\Users\xxxxx\AppData\Local\rtk\history.db
问题主要是 Codex 当前沙箱无法稳定访问或更新该数据库

3. 处理方式

如果目标是查看统计、验证统计是否落库，或确认 rtk tracking 是否正常工作，应优先在非沙箱环境执行相关命令。

例如：

powershell 复制代码

rtk git status
rtk gain --history

本次实测中，在非沙箱执行一次 rtk git status 后，再查看 rtk gain --history，统计已正常出现，且 history.db 的 LastWriteTime 发生更新。

4. 当前推荐约定

为避免 Windows + Codex 下出现"命令能跑，但统计读写失败"的情况，当前推荐：

普通 rtk 命令默认优先在非沙箱环境执行
高风险、破坏性、或会改变系统状态的命令仍需单独评估

这条约定已手动补充到全局文件：

text 复制代码

C:\Users\xxxxx\.codex\RTK.md

5. 关于 hook

即使未安装 hook，手动执行 rtk ... 依然可以产生统计记录。

如果 rtk gain --history 输出：

text 复制代码

[warn] No hook installed --- run `rtk init -g` for automatic token savings

表示当前没有启用自动 hook 改写，属于提示信息，不影响手动 rtk 命令的统计。

常用验证命令

安装完成后，可以先用以下命令确认 RTK 工作正常：

powershell 复制代码

rtk --version
rtk init --show
rtk read .\README.md
rtk grep "Shared.LinkButton" .
rtk git status
rtk gain --history

注意事项

curl | sh 属于远程脚本直接执行方式，Windows 原生环境不适合直接照抄官方 Unix 安装命令
Git Bash 不是官方 install.sh 支持的操作系统目标
Windows 原生环境可以使用 RTK，但某些基于 shell hook 的自动重写体验通常不如 WSL 完整
在 Codex 中，涉及 rtk 统计数据库的命令更适合放在非沙箱环境执行
如果需要最完整的 Linux/macOS 级体验，建议改用 WSL 安装和运行 RTK

RTK Windows 安装记录