tf-cli 项目提供命令 tf，用于启动和管理 AI 编程客户端（Claude Code、Codex、opencode、Pi）的网关凭据。它将 TokenFlux 或自建 TokenRouter 网关的密钥、模型路由及槽位配置以纯进程级方式注入各客户端，不读写各工具的全局配置文件，支持多 Key 隔离与多模型槽协同。
- 非侵入式注入：仅在子进程生命周期内通过环境变量与 CLI 参数注入配置，不修改
~/.claude/settings.json、~/.codex/config.toml或~/.pi；~/.claude/settings.json的env可覆盖进程注入，tf会在启动前检查并告警。 - 全模型槽位管理：自动配置主对话模型及后台任务模型（如 Claude 的
fast摘要槽、Codex 的review审查槽、opencode 的small模型槽、Pi 的default主对话槽），避免因缺省配置导致静默调用失败。 - 协议探测与路由过滤：登录及需要模型候选或校验时刷新模型列表，通过零 token 探测过滤不兼容模型。绑定与槽位完整的启动和补全直接读取本地缓存。
- 多凭据隔离：按 harness 独立绑定 Key，支持单凭据跨分组前缀路由，无需切换全局环境。
- 环境诊断与冲突预警：内置状态检查与配置冲突检测，实时识别本地覆盖环境变量及配额耗尽状态。
Windows PowerShell 5.1 / PowerShell 7：
irm https://raw.githubusercontent.com/tokenflux/tf-cli/main/install.ps1 | iex安装为 %USERPROFILE%\.local\bin\tf.exe，不需要管理员权限、Git Bash、curl 或 Scoop。支持 TF_INSTALL_DIR，下载校验与安装使用 Windows 自带 API；脚本会提示如何配置 PATH，不自动修改系统设置。下载到本地后也可使用 -InstallDir 自定义目录、-Proxy 指定 HTTP 代理。
macOS / Linux，或 Windows Git Bash：
curl -fsSL https://raw.githubusercontent.com/tokenflux/tf-cli/main/install.sh | sh默认安装至 ~/.local/bin/tf（可通过环境变量 TF_INSTALL_DIR 自定义安装路径），无需管理员权限。
Windows x64 在 Git Bash 中使用同一脚本，安装为 ~/.local/bin/tf.exe，依赖 Git Bash 提供的 unzip、cygpath 和 curl。脚本校验发行包的 SHA-256，再替换程序；不会自动修改系统 PATH。按安装后的提示配置 PATH，或在当前会话执行 export PATH="$HOME/.local/bin:$PATH"。
若 Git 自带的 curl 报 CRYPT_E_REVOCATION_OFFLINE，可用 scoop install curl 安装新版，然后在当前会话执行 export PATH="$HOME/scoop/apps/curl/current/bin:$PATH" 后重试。无需关闭 TLS 校验。
npm 官方包名为 @tokenflux/tf（未加 scope 的 tf 与 tf-cli 属于无关项目）。主包通过 optionalDependencies 分发平台对应的 Go 二进制，无 postinstall 外部下载脚本：
# 全局安装
npm install -g @tokenflux/tf
tf login
# 或单次执行
npx @tokenflux/tf status
# 或
pnpx @tokenflux/tf status安装时请勿添加 --omit=optional 或 --no-optional。通过 npm 全局安装时，升级请运行 npm install -g @tokenflux/tf@latest（tf update 检测到 node_modules 路径时会提示该命令，不会自行覆盖包管理器文件）。
通过 go install 直接安装：
go install github.com/tokenflux/tf-cli/cmd/tf@latest或克隆源码仓库本地编译：
git clone https://github.com/tokenflux/tf-cli.git
cd tf-cli
make build- 检查更新：
tf update --check - 自动升级：
tf update（独立脚本安装支持自动校验并替换；npm 安装请运行npm install -g @tokenflux/tf@latest）
-
npm 安装：
npm uninstall -g @tokenflux/tf
-
PowerShell 脚本安装：
# 默认保留凭据和配置 irm https://raw.githubusercontent.com/tokenflux/tf-cli/main/uninstall.ps1 | iex # 同时清理凭据、配置和缓存 & ([scriptblock]::Create((irm https://raw.githubusercontent.com/tokenflux/tf-cli/main/uninstall.ps1))) -Purge
自定义安装目录使用
TF_INSTALL_DIR，或下载脚本后传入-InstallDir。-Purge不遍历目录链接或 junction 指向的位置。 -
install.sh 安装：
# 默认仅删除 tf 二进制，保留当前配置与凭据 curl -fsSL https://raw.githubusercontent.com/tokenflux/tf-cli/main/uninstall.sh | sh # 同时删除 ~/.tf 或 XDG 对应的配置、凭据与缓存 curl -fsSL https://raw.githubusercontent.com/tokenflux/tf-cli/main/uninstall.sh | sh -s -- --purge
Windows 在 Git Bash 中使用相同的卸载命令，会删除
tf.exe及自更新留下的tf.exe.old，默认仍保留凭据。若安装时指定了自定义目录，请在管道右侧传入环境变量（例如
curl -fsSL https://raw.githubusercontent.com/tokenflux/tf-cli/main/uninstall.sh | TF_INSTALL_DIR=/原安装目录 sh）。 -
源码 / go install 安装： 删除安装时设置的 GOBIN 中的 tf；若 GOBIN 为空，则位置为
$(go env GOPATH)/bin。若需清理配置与凭据，再按需删除配置目录（默认~/.tf，或tf config显示的路径）。
操作系统支持：Linux 与 macOS 支持完整交互。Windows 自 v0.9.0 起支持原生控制台交互，可在 Windows Terminal 的 PowerShell 或 Git Bash 中运行，也可通过 Windows OpenSSH 分配的终端运行。经典 mintty 无原生控制台时使用
winpty tf.exe。npm/pnpm 安装的客户端需要 Git Bash 在 PATH 中。
tf login 默认高亮“从网页导入”。选定登录方式后，CLI 会让你选择默认 TokenFlux 网关或输入自定义地址，再建立本机监听并打开对应的 Keys 页面。显式传入 --host 会跳过网关选择；管道与非交互登录保持原行为。
$ tf login
选择登录方式
❯ 从网页导入 自动打开 Keys 页面
粘贴 API Key 终端隐藏输入
等待网页导入
监听 http://127.0.0.1:43110
来源 https://tokenflux.dev
打开 https://tokenflux.dev/keys#tfcli=1.43110.<session-secret>
10 分钟内没有请求会自动退出需要粘贴时，在选择器中选择第二项，或使用 tf login --with-key；交互模式下同样可以选择网关。自定义地址支持省略 https:// 和末尾误带的 /v1，会在读取 Key 前校验。已有自建网关账户优先沿用原地址；取消选择不会修改账户，导入成功后才保存选定地址。
如使用私有化部署的 TokenRouter 网关：
tf login work --host https://router.example.com也可以用 flag 直接进入网页导入：
tf login work --from-web网页和终端确认页会对终端链接显示“已验证当前 tf 会话”；直接打开页面仍可导入，但两端都会显示未验证会话警告。网页请求到达后，终端会展示 Origin、网关、分组和脱敏 Key，只有手动确认后才会继续。
未在命令中指定名称时，CLI 校验 Key 后会让用户选择按可用模型自动命名、采用网页 Key 名称或自订名称。自动命名会避开已有名称；显式运行 tf login work 则使用 work；该名称已有不同 Key 时会先确认覆盖，默认取消。非交互覆盖必须添加 --force。完整前端协议见 docs/integrations/web-import.md。
直接指定目标 harness 启动。首次运行若未配置模型，将启动交互式选择器；配置后将自动持久化偏好：
$ tf claude
为 claude 选择主模型
❯ claude-opus-5 Claude/
claude-sonnet-5 Claude/
claude-haiku-4-5 Claude/
╭───────────────────────────────╮
│ ✻ Welcome to Claude Code │
╰───────────────────────────────╯若本地未安装对应 harness，tf 将提供系统包管理器安装选项；在 --no-input、--json 或无 TTY 环境下将输出标准安装命令。
运行参数仅对当前进程生效，不影响已保存的默认配置：
tf claude -m # 唤起模型交互选择器
tf codex -e high # 调整推理思考强度（reasoning effort）
tf pi -e high # 调整推理思考强度（reasoning effort）
tf codex -k work # 显式指定本次使用的 Key 别名
tf claude -- --resume # 双破折号 -- 后的所有参数将直接透传给底层工具
tf opencode --help # harness 命令后的 -h/--help 直接交给底层工具
tf --help opencode # 查看 tf 包装器对该 harness 的帮助查看当前 harness 的槽位分配：
$ tf model claude
claude
default claude-sonnet-5 — 主对话
fast claude-haiku-4-5-20251001 — 后台任务：标题、文件摘要
heavy 未配置 — /model 切换高算力档位修改指定槽位的默认模型：
tf model claude --set fast=claude-haiku-4-5-20251001各 harness 支持的槽位定义：
- Claude Code：
default（主会话）、fast（摘要与标题生成）、heavy（高算力模式） - Codex：
default（主会话）、review（代码审查） - opencode：
default（主模型）、small（轻量任务模型；未配置时将触发回退警告） - Pi：
default（主会话）
查看本地保存的凭据及其适用客户端范围：
$ tf keys
work sk-d61…5b1c
Claude/ claude
GPT/ codex opencode pi
personal sk-9f2…a047
ChatGPT/ codex opencode pitf keys --refresh 先拉每把 Key 的 /v1/models 再按最新前缀探协议；启动筛选从缓存找不到可用 Key 时同样自动刷新；这些刷新路径网络失败时沿用已有缓存。
通过 tf status 检查当前生效的凭据、各客户端模型映射、用量配额及环境冲突：
$ tf status
/Users/user/.tf
default sk-d7d…a4fe 13 个模型
额度 0/10 推理积分 额度已耗尽，请求将被拒绝
今日 8 次请求，170933 tokens
claude default claude-sonnet-5
codex default gpt-5.6-terra
opencode — claude-sonnet-5
pi default gpt-5.6-terra
警告：~/.codex/auth.json 本地已存在凭据；直接运行 codex（不经由 tf）将使用该凭据tf 作为宿主进程与 CLI 客户端之间的隔离层，采用进程级入参及环境变量注入：
| 客户端 | 验证版本 | 注入方式 | 环境清理与保护 |
|---|---|---|---|
| Claude Code | 2.1.251 | 注入 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_DEFAULT_*_MODEL |
清理继承的 ANTHROPIC_API_KEY 及 AWS Bedrock / GCP Vertex 相关环境变量 |
| Codex | 0.151.0 | 注入命令行参数 -c model_provider=…、-c model_providers.*.base_url=…、env_key |
不注入额外环境变量，避免污染 Shell 上下文 |
| opencode | 1.18.20 | 注入 OPENCODE_CONFIG_CONTENT 内联 JSON（包含 model 与 small_model） |
覆盖进程局部配置，不落盘修改全局配置文件 |
| Pi | 0.84.4 / 0.85.0 | 通过 --extension 加载进程私有临时 JS 扩展注册随机 provider，仅在专用环境变量传递凭据，注入限定 --model <provider>/<model> |
临时扩展文件权限 0600 且退出后自动删除；Key 不进入 argv 或落盘配置，不改动 ~/.pi |
执行 tf config 可输出当前配置目录位置（默认 ~/.tf，遵循 XDG 规范时为 $XDG_CONFIG_HOME/tf）：
| 文件 / 环境变量 | 权限 | 说明 |
|---|---|---|
config.json |
0644 |
存储 Key 别名、网关地址、harness 映射与模型槽配置（无敏感信息，可同步） |
credentials.json |
0600 |
明文存储 API Key，仅当前用户可读写 |
TF_API_KEY |
- | 仅本次启动使用，不覆盖已保存的 Key；默认连接默认网关，自建网关需指定 --host；显式 -k 优先使用本地 Key |
TF_LANG |
- | 强制指定 CLI 显示语言（可选 zh 或 en，默认跟随系统 Locale） |
CI/CD 与容器无需先登录：通过环境注入 TF_API_KEY 后，运行 tf codex --no-input -m=gpt-5.6-terra -- exec "your prompt"。自建网关添加 --host https://router.example.com。运行时 Key、模型目录与槽位均不落盘；tf status 和 tf keys 仍只查询本地保存的账户。
详细安全模型与凭据存储机制请参考 SECURITY.md。
- 遇到问题或功能建议，请提交 GitHub Issue。
- 涉及安全漏洞请参阅 SECURITY.md 的披露流程进行反馈。
本项目采用 Apache-2.0 许可证。相关名称与商标归各自权利人所有，本项目与其无商业从属关系。