tf-cli

README

tf-cli

tf-cli 项目提供命令 tf，用于启动和管理 AI 编程客户端（Claude Code、Codex、opencode）的网关凭据。它将 TokenFlux 或自建 TokenRouter 网关的密钥、模型路由及槽位配置以纯进程级方式注入各客户端，不读写各工具的全局配置文件，支持多 Key 隔离与多模型槽协同。

特性

• 非侵入式注入：仅在子进程生命周期内通过环境变量与 CLI 参数注入配置，不修改 ~/.claude/settings.json 或 ~/.codex/config.toml；~/.claude/settings.json 的 env 可覆盖进程注入，tf 会在启动前检查并告警。
• 全模型槽位管理：自动配置主对话模型及后台任务模型（如 Claude 的 fast 摘要槽、Codex 的 review 审查槽、opencode 的 small 模型槽），避免因缺省配置导致静默调用失败。
• 协议探测与路由过滤：登录及需要模型候选或校验时刷新模型列表，通过零 token 探测过滤不兼容模型。绑定与槽位完整的启动和补全直接读取本地缓存。
• 多凭据隔离：按 harness 独立绑定 Key，支持单凭据跨分组前缀路由，无需切换全局环境。
• 环境诊断与冲突预警：内置状态检查与配置冲突检测，实时识别本地覆盖环境变量及配额耗尽状态。

安装

预编译二进制（推荐）

curl -fsSL https://raw.githubusercontent.com/tokenflux/tf-cli/main/install.sh | sh

默认安装至 ~/.local/bin/tf（可通过环境变量 TF_INSTALL_DIR 自定义安装路径），无需管理员权限。

npm（自 v0.5.3 起）

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（下载最新 Release 并校验 SHA256 后执行原子替换）
• 卸载：删除配置将永久清除本机保存的 Key。默认安装和默认配置路径可执行：

  rm ~/.local/bin/tf
  rm -rf ~/.tf
  

  若安装时设置了 TF_INSTALL_DIR，二进制路径为 $TF_INSTALL_DIR/tf。若使用 XDG 路径，请先运行 tf config 确认配置与缓存目录，再删除对应目录。

操作系统支持：支持 Linux 与 macOS 全交互特性。Windows 当前仅支持非交互模式（支持通过管道传入 Key 及使用 --set 预设参数）。

快速上手

1. 登录并绑定网关

tf login 默认高亮“从网页导入”。确认后 CLI 会建立本机监听并自动打开 Keys 页面：

$ 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。

如使用私有化部署的 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。完整前端协议见 docs/integrations/web-import.md。

2. 启动客户端

直接指定目标 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 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（轻量任务模型；未配置时将触发回退警告）

凭据与多 Key 查看

查看本地保存的凭据及其适用客户端范围：

$ tf keys
work  sk-d61…5b1c
  Claude/    claude
  GPT/       codex opencode
personal  sk-9f2…a047
  ChatGPT/   codex opencode

tf 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
警告：~/.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）	覆盖进程局部配置，不落盘修改全局配置文件

配置与存储结构

执行 tf config 可输出当前配置目录位置（默认 ~/.tf，遵循 XDG 规范时为 $XDG_CONFIG_HOME/tf）：

文件 / 环境变量	权限	说明
config.json	0644	存储 Key 别名、网关地址、harness 映射与模型槽配置（无敏感信息，可同步）
credentials.json	0600	明文存储 API Key，仅当前用户可读写
TF_API_KEY	-	运行时环境变量，优先级高于本地配置文件，适合 CI/CD 与容器环境
TF_LANG	-	强制指定 CLI 显示语言（可选 zh 或 en，默认跟随系统 Locale）

详细安全模型与凭据存储机制请参考 SECURITY.md。

问题反馈

• 遇到问题或功能建议，请提交 GitHub Issue。
• 涉及安全漏洞请参阅 SECURITY.md 的披露流程进行反馈。

许可协议

本项目采用 Apache-2.0 许可证。Claude、Codex、opencode 分别为各自实体的注册商标，本项目与其无商业从属关系。