@xicode/pi-codex-pat

为 Pi 注册独立的 openai-codex-pat Provider，使用 OpenAI Codex Personal Access Token 访问 Codex backend。

插件不会修改 Pi，也不会把 PAT 写入 ~/.pi/agent/auth.json。认证信息按以下优先级读取：

1. pi --api-key at-... 传入的运行时凭据（不落盘）
2. CODEX_ACCESS_TOKEN
3. 文件型 $CODEX_HOME/auth.json
4. 未设置 CODEX_HOME 时的 ~/.codex/auth.json

显式提供的凭据不会回退到其它来源：--api-key 一旦给出，Account ID 就来自这个 token 自己的 whoami，不会混用环境变量或 auth.json 里的账号。

系统 Keyring 不在支持范围内。

安装

pi install npm:@xicode/pi-codex-pat

安装后选择 openai-codex-pat/<model>。原生 openai-codex OAuth Provider 保持不变， 两种认证方式可以同时存在。

凭据

PAT 必须匹配 at- 前缀加 URL-safe base64 字符集（可带 = 填充）。含空格、换行或其它控制 字符的畸形 token 会被直接拒绝，不会进入 HTTP 请求 —— 这类值会让 HTTP 客户端把整条 Authorization header 拼进异常信息。

环境变量必须包含以 at- 开头的 PAT：

$env:CODEX_ACCESS_TOKEN = "at-..."
pi

也可以复用 Codex 文件型认证：

{
  "auth_mode": "personalAccessToken",
  "personal_access_token": "at-..."
}

为了兼容 Codex 已有行为，auth_mode 可以缺失；如果显式设置为其他认证模式，插件不会 读取残留的 personal_access_token。

当 CODEX_ACCESS_TOKEN 包含非 PAT 凭据时，环境变量被视为显式认证选择，插件不会继续 回退到 auth.json。

认证行为

• Provider 可用性检查只读取环境变量和本地文件，不访问网络。
• 首次模型请求通过 OpenAI AuthAPI whoami 获取 Account ID 和 FedRAMP 信息。
• 元数据只缓存在当前进程内，不写入磁盘。
• PAT 变化或 Pi reload 后重新解析认证。
• PAT、Authorization header 和完整 auth.json 不进入日志和错误信息。

兼容性

当前 transport 已验证基线：

@earendil-works/pi-coding-agent 0.81.1
@earendil-works/pi-ai 0.81.1
Pi commit 24bace27cf308c89707cf8005b4795d873e23f17

该基线是下限，不是精确锁：

• 宿主低于基线时插件拒绝注册。打包的 transport 是基线版本的补丁副本，更旧的宿主可能 缺少它调用的 API，加载期失败比请求中途崩溃更容易定位。
• 宿主等于基线时正常工作，不提示。
• 宿主高于基线时插件照常注册，并在会话开始时给出一次告警。Provider 契约通常能跨越 patch 和 minor 更新，因此这里只提示风险而不阻断 —— 否则 Pi 每发一个版本，插件就立刻 不可用。若升级后请求开始失败，先检查是否有更新的 pi-codex-pat。
• 版本探测失败（例如独立 bun 二进制没有可读的 package.json）时同样只告警。

升级 Pi 后如果 transport 行为异常，应重新完成协议测试并更新基线。

开发

插件的认证和 Provider 代码位于 src/。Codex transport 从 vendor/pi 的固定提交复制到 构建临时目录，应用 patches/openai-codex-pat.patch 后打包：

pnpm build
pnpm typecheck
pnpm test

构建时同时编入匹配版本的 Codex 模型目录和轻量 lazy-stream helper。运行时不导入宿主 Pi AI 大入口；transport 延迟到首次模型请求才加载，不增加启动阶段的协议模块解析。