集中管理多个 Codex OAuth 账户、凭证和带认证的 HTTPS Proxy 出口，并为 Pi 转发 Codex SSE/WebSocket 请求。Pi 客户端只持有分配给自己的 pi_as_... token。
- Server 镜像：
ghcr.io/metolab/pi-auth-server - Pi Package：
@metolab/pi-auth-server - 源码：https://github.com/metolab/pi-auth-server
- 架构与安全不变量：docs/architecture.md
Pi client token
→ account
→ Codex OAuth credential + HTTPS Proxy
→ HTTPS Proxy CONNECT
→ chatgpt.com
每个客户端 token 绑定一个服务端账户，由账户选择 OAuth 凭证和 HTTPS Proxy。OAuth exchange、refresh、Codex SSE 和 WebSocket 均通过该代理；代理不可用时请求失败，不会直连回退。
要求 Docker Compose v2。克隆公开仓库并生成控制台密钥：
git clone https://github.com/metolab/pi-auth-server.git
cd pi-auth-server
cp .env.example .env
CONTROL_PANEL_TOKEN="$(openssl rand -hex 32)"
perl -pi -e "s/replace-with-a-random-secret/$CONTROL_PANEL_TOKEN/" .env
docker compose up -d默认使用 ghcr.io/metolab/pi-auth-server:latest，只监听宿主机 127.0.0.1:8787，SQLite 数据保存在 named volume pi-auth-server_pi-auth-data。生产环境建议固定版本：
PI_AUTH_SERVER_IMAGE=ghcr.io/metolab/pi-auth-server:0.3.2打开 http://127.0.0.1:8787/dashboard，依次完成：
- 添加 HTTPS Proxy；
- 添加账户并绑定代理；
- 点击账户的 OAuth，登录后将浏览器最终的完整
localhost:1455/auth/callback?...URL 粘贴回控制台； - 创建绑定该账户的客户端 token。
OAuth provider 固定使用 http://localhost:1455/auth/callback。远程控制台无法监听浏览器本机 localhost 是正常的，只需复制最终回调 URL。
停止服务不会删除数据：
docker compose down只有明确需要销毁数据库时才执行：
docker compose down -v生产环境应在 Server 前部署支持 WebSocket Upgrade 和长连接的 HTTPS 反向代理，不要直接公开 8787。数据库包含明文客户端 token、代理密码和原始 OAuth 凭证，应使用加密持久卷并限制控制台访问。
Extension 作为 npm public package 发布。安装不需要 registry 配置或 npm token：
pi install npm:@metolab/pi-auth-server配置 Server 地址和控制台创建的客户端 token：
export PI_AUTH_SERVER_URL=https://auth.example.com
export PI_AUTH_SERVER_TOKEN='pi_as_...'
pi --model openai-codex/gpt-5.4如果 Server 就在本机默认端口，可以省略 PI_AUTH_SERVER_URL：
export PI_AUTH_SERVER_TOKEN='pi_as_...'
pi --model openai-codex/gpt-5.4Package 只覆盖内置 openai-codex provider 的 transport/auth，不复制模型目录，因此 Pi 原生模型元数据、工具协议、session、缓存和 WebSocket 行为保持不变。更新 Package：
pi update npm:@metolab/pi-auth-server| 环境变量 | 默认值 | 用途 |
|---|---|---|
PORT |
8787 |
HTTP 监听端口 |
CONTROL_PANEL_TOKEN |
无 | 控制 API 必需的 Bearer token |
PI_AUTH_SERVER_DB |
data/pi-auth-server.sqlite |
SQLite 文件 |
PI_AUTH_SERVER_DATA_DIR |
./data |
默认数据目录 |
CODEX_BASE_URL |
https://chatgpt.com/backend-api |
Codex upstream；主要供隔离测试使用 |
OAUTH_BASE_URL |
https://auth.openai.com |
OAuth upstream；主要供隔离测试使用 |
UPSTREAM_TIMEOUT_MS |
120000 |
上游超时 |
CODEX_CANONICAL_USER_AGENT |
pi (darwin 25.5.0; arm64) |
发往 Codex 的默认公共 UA |
REQUEST_LOG_MAX_BYTES |
1000000 |
审计请求 body 上限 |
审计请求日志永久保留，不会自动删除；请按需管理数据库磁盘空间。
每个 token 可以显式覆盖公共 UA。machine_id 仅保存在服务端数据库并展示于控制台，不发送到 Codex。Pi 的 session-id、x-client-request-id、prompt_cache_key 和 Responses ID 保持原有逻辑。
要求 Node.js 24+：
npm ci
npm run check本地启动：
npm run build
export CONTROL_PANEL_TOKEN="$(openssl rand -hex 32)"
npm start构建本地镜像：
docker build -t pi-auth-server:dev .
PI_AUTH_SERVER_IMAGE=pi-auth-server:dev docker compose up -d主要目录：
server/ Server、控制 API 和上游 transport
dashboard/ React/Vite 管理控制台
shared/ Server/Dashboard 共享 HTTP contracts
packages/pi-auth-server-extension/ 发布到 npm 的 Pi Package
test/ fake transport HTTP/WebSocket E2E
.github/workflows/ CI 和 tag release
推送 v<package version> tag 会运行 release workflow：
- 执行完整
npm run check； - 构建
linux/amd64、linux/arm64镜像并发布到ghcr.io/metolab/pi-auth-server； - 通过 npm Trusted Publishing 发布
packages/pi-auth-server-extension到 public npm registry。
例如：
npm version 0.3.1 --no-git-tag-version
npm version 0.3.1 --prefix packages/pi-auth-server-extension --no-git-tag-version
git add .
git commit -m 'release: v0.3.1'
git tag v0.3.1
git push origin main --tagsTag 必须与 packages/pi-auth-server-extension/package.json 的版本一致。npm package 使用 GitHub Actions OIDC Trusted Publishing 和最小化的 id-token: write 权限，不需要在仓库保存 npm token。
审计日志会移除 HTTP Authorization、Cookie 等 headers。SSE 保存解压后的审计副本；WebSocket 旁路解析消息但不修改原始 frame。控制台按产品要求可查看原始凭证 JSON、代理密码和客户端 token 明文，因此数据库、备份和控制 API 都是高敏感边界。
SQLite 使用 WAL、foreign keys、busy timeout 和 synchronous=NORMAL。同一个 SQLite 文件只能由单 Server writer 使用；多实例部署前应迁移到共享数据库。安全问题请按 SECURITY.md 私下报告。