前言¶
DeepSeek Harness (DSH) 的生态强调插件化。在使用 dsh-llm-pi-ai 适配器调用模型时，通常需要配置 API Key。如果开发者已经在 Codex CLI 中完成了 ChatGPT 的 OAuth 登录，手动维护两套凭证不仅繁琐，还容易出错。dsh-codex-auth-bridge 插件旨在解决这一重复配置问题，它允许 DSH 直接复用 Codex 的登录状态。
核心功能¶
该插件以 Host Cordis bundle 的形式提供。主要功能包括：
* 凭证读取与刷新：读取 Codex 的 auth.json，通过 @earendil-works/pi-ai 的原生实现保持 OAuth 令牌新鲜。
* 凭证同步：将同步后的访问令牌写入 DSH 的凭证服务。
* 路由配置：自动配置 pi-ai 内置的 openai-codex 模型路由。
* 安全性：插件代码及运行时均不包含、上传或提交任何令牌数据。
安装与启用¶
在运行安装命令前，请确保满足以下前置条件：
* Node.js 版本为 22.19 或更高。
* DSH 安装使用了 dsh-llm-pi-ai 适配器。
* Codex 已通过 ChatGPT 登录（即 ~/.codex/auth.json 中包含 auth_mode: "chatgpt"）。
在已登录 Codex 的设备上运行以下命令：
npx --yes github:shaomingbo/dsh-codex-auth-bridge#v0.1.0
安装过程会自动执行以下步骤：
1. 向 ~/.dsh/profiles/web/package.json 添加该包。
2. 在对应 profile 的 dsh.profile.bundles 列表中添加 dsh-codex-auth-bridge。
3. 在该 profile 目录下运行 pnpm install。
安装完成后，重启 dsh web，模型选择器将包含由 pi-ai 的 openai-codex 目录暴露的模型。
典型用法¶
- 基础安装：执行上述安装命令即可完成配置。
- 指定 Profile：如果需要在非默认配置下使用，可以通过
--profile参数指定：
npx --yes github:shaomingbo/dsh-codex-auth-bridge#v0.1.0 --profile web
- 本地源安装：从本地源码安装：
node ./bin/install.js --source file:../../packages/dsh-codex-auth-bridge
工作原理¶
插件会在启动时、每 10 分钟，以及每次 openai-codex LLM 流请求前执行同步逻辑：
1. 读取 ${CODEX_HOME:-~/.codex}/auth.json。
2. 解码访问令牌的过期时间。
3. 如果令牌过期或即将过期，通过 @earendil-works/pi-ai 刷新令牌。
4. 原子性地将刷新后的令牌写回 Codex 的 auth.json。
5. 将当前访问令牌存储在 DSH 的凭证服务中，引用名为 OPENAI_CODEX_ACCESS_TOKEN。
插件还会配置以下 Composition 基础：
llm-pi-ai:
providers:
openai-codex:
apiKeyEnv: OPENAI_CODEX_ACCESS_TOKEN
适用场景与注意¶
该插件适用于需要通过 DSH 访问 ChatGPT 模型，且已使用 Codex CLI 进行过 ChatGPT OAuth 登录的开发者。
需要注意以下几点：
* 权限与安全：Codex 的 auth.json 包含旋转的刷新令牌，必须保持私密。DSH 的本地凭证提供者会将同步的访问令牌写入 $DSH_HOME/.credentials.yaml（通常权限为 0600）。插件本身不会记录任何令牌值。
* 并发保护：插件实现了“写入前比较”机制，如果 Codex 在后台同时刷新了令牌，新的刷新令牌不会被覆盖。
* 环境变量：可以通过环境变量调整路径和刷新间隔，如 DSH_CODEX_AUTH_PATH 和 DSH_CODEX_REFRESH_MARGIN_MS。
结语¶
通过复用 Codex 的 OAuth 登录，开发者可以避免在 DSH 中重复配置 API Key。该插件通过 @earendil-works/pi-ai 实现了令牌的自动刷新与同步，确保了会话的持续性。更多细节可参考 GitHub 仓库。
