Codex Tools反代安全指南:本地API Key机制、模型白名单与账号数据保护详解

原创2026-10-15 12:25:361,347 阅读

Codex Tools反代安全指南:本地API Key机制、模型白名单与账号数据保护详解

Codex Tools 是一款面向多账号场景的桌面工具,集 Codex 账号快捷切换、用量监控 与 本地 OpenAI 兼容 API 反代 于一体,并支持多语言界面。当你把账号池暴露成 /v1 接口供 Cursor、ChatWise、CC Switch 或本地脚本调用时,"这个接口被谁调用、能调哪些模型、账号数据存在哪里"就成了绕不开的安全问题。本文用新手友好的方式,讲清楚本地 API Key 的运作机制、模型白名单的最小权限策略,以及账号数据在磁盘上的保护细节。

Codex Tools 工作台整体界面,包含账号管理与 API 反代面板

一、本地 API Key:反代的"门锁"是怎么工作的

启动 API 反代后,Codex Tools 会在本地 127.0.0.1:8787 起一个 OpenAI 兼容服务,并自动生成一把形如 sk-... 的 本地代理专用 Key。

Codex Tools 反代面板界面,展示 Base URL、API Key 与运行状态

新手最容易混淆的一点是这把 Key 的"身份",它有三层含义上的区别:

概念 作用范围 是否可直接调 OpenAI
本地代理 Key(sk-...) 只对本机反代的 /v1 接口有效 ❌ 不行
OpenAI 官方 API Key OpenAI 官方接口 ✅ 官方计费
账号池里的 access_token Codex 上游登录态 ❌ 由代理内部持有

也就是说,反代 Key 只是一道本地门锁:所有打到 /v1/chat/completions、/v1/models 等接口的请求,都必须先通过这把 Key 的校验(支持 Authorization: Bearer sk-... 或 X-API-Key 两种传法),校验失败会直接返回 401 Invalid proxy api key.,请求根本不会触达上游账号。

几个对新手很实用的细节:

  • Key 在 Key 管理面板中维护:可以创建多把 Key、启停、重命名、一键重新生成(轮换)。想立即作废一把泄露的 Key,直接"重新生成"即可,旧 Key 马上失效;
  • Key 会持久化保存到应用数据目录的 api-proxy-keys.json,重启后无需重配;
  • 先鉴权、再读请求体:代理在完成 Key 校验之后才会读取并限制请求体大小,未认证的超大请求不会占用你的内存。

相关实现可以参考 src-tauri/src/proxy_service.rs 中的 authorize_proxy_request 与 docs/api-proxy.md 第 7 节。

二、模型白名单:给每把 Key 做"最小权限"

如果说 Key 是门锁,那白名单就是每把钥匙能开的房间。Codex Tools 的每把 Key 都支持三类独立权限:

  1. 模型白名单(allowedModels):只允许请求勾选的模型;
  2. 推理强度白名单(allowedReasoningEfforts):限制可请求的 reasoning effort 档位;
  3. 速度等级白名单(allowedServiceTiers):限制 default、fast 等服务档位。

Codex Tools API 账号导入表单,展示 API Key 字段的填写位置

这套机制带来的实际好处:

  • 按用途分 Key:给 Cursor 配一把只允许 gpt-5.6-sol 的 Key,给脚本配一把只允许 fast 档的 Key,互相隔离;
  • 白名单未勾选 = 直接拒绝:请求了 Key 未绑定的模型会明确报"平台 Key 未绑定请求模型",而不是静默降级;
  • 升级不会偷偷扩权:当代理新增模型(如 GPT-6.1 Sol)时,已有 Key 的白名单不会自动扩大,需要你在面板里显式勾选。Key 被禁用或撤销后,绑定的 Codex 客户端模型选择器也不会再展示可选模型;
  • 权限修改即时生效:Key 权限保存在 api-proxy-keys.json,修改后运行中的代理会热加载,无需重启服务。

Key 管理的前端逻辑见 src/components/proxy/ProxyKeys.tsx,服务端校验逻辑见 ensure_api_proxy_key_allows_payload(同文件 src-tauri/src/proxy_service.rs)。

三、账号数据保护:accounts.json 存在哪、怎么防泄露

反代的"弹药"是账号池文件 accounts.json(位于应用数据目录),其中保存了每个账号的 auth_json(登录态 token)等敏感信息。Codex Tools 在存储层做了三重保护:

Codex Tools 账号管理界面,展示账号列表、用量与计划标签

  • 私有文件权限:accounts.json、Key 文件等敏感文件在创建瞬间就使用 0600 权限(仅当前用户可读写),避免"先创建再收权"之间的时间窗口;Windows 上则会自动收紧文件 ACL。逻辑见 src-tauri/src/utils.rs 的 private_create_new_options 与 set_private_permissions;
  • 原子写入 + 自动备份:写入前先写临时文件再替换,并维护 accounts.json.last-good.json、accounts.json.prev-good.json 两级健康备份,异常损坏时可回导入;
  • token 刷新的可控回写:当代理发现账号 token 过期(401、token expired 等信号)会先刷新,刷新成功后只回写到账号池;仅当该账号是当前激活账号时,才会同步到 ~/.codex/auth.json,不会悄悄改动其他账号。

存储与备份的实现集中在 src-tauri/src/store.rs。给新手的建议:

  • 不要手动把 accounts.json 发到聊天工具或公开仓库,它等同于你的账号密码本;
  • 备份/迁移请用面板或 ctc export 导出后再妥善保管,而不是截图;
  • 如果部署在多人共用的 Linux 机器上,独立代理进程 codex-tools-proxyd 的数据目录(accounts.json + api-proxy.key)同样应限制属主权限,说明见 docs/linux-proxyd.md。

四、反代上公网之前:一份快速自查清单

本地反代默认只监听本机地址,本身是安全的。但开启 cloudflared 隧道(面板内"公网访问")把反代暴露到公网后,攻击面会变大,建议按下面的清单逐项自查:

# 自查项 建议
1 公网访问是否真的必要 仅本地工具使用时保持关闭
2 是否使用了多把分权 Key 每个客户端一把独立 Key,方便逐个吊销
3 白名单是否收窄 只勾选该客户端真正需要的模型与速度档位
4 Key 是否泄露过 泄露后立刻在面板"重新生成",旧 Key 即时失效
5 账号池文件权限 Unix 确认 0600、目录 0700;Windows 检查 ACL
6 用量监控 定期查看反代用量统计,发现异常 Key 的调用量及时禁用

五、写在最后

Codex Tools 的反代安全模型可以概括为一句话:Key 管"谁能进门",白名单管"进门能用什么",文件权限管"家底是否安全"。三层各管一段,互不替代——只开白名单不给公网客户端独立 Key,等于把门锁也交给了别人。

按本文的清单把本地反代配置好之后,你就可以放心地把 Codex 账号池交给 Cursor、ChatWise 或 CC Switch 等客户端使用了。完整链路细节(协议转换、账号轮换、失败分类)可继续阅读官方文档 docs/api-proxy.md。

登录后查看全文
codex-tools