dsh-plugin-llm-codex

让 DeepSeek Harness（DSH） 通过 ChatGPT/Codex 订阅调用 openai-codex 模型，无需配置 OpenAI API Key。

插件提供 OAuth 设备码登录、令牌持久化与自动刷新、Web 设置面板，以及可在对话中调用的认证工具。

[!IMPORTANT] 本插件负责 Codex OAuth 认证，不负责创建模型路由。首次使用时仍需在 DSH 设置中声明 openai-codex provider，详见快速开始。

功能特性

• 免 API Key：使用 ChatGPT 账号完成 OAuth 设备码授权。
• 自动维护令牌：通过 DSH credentials 服务保存 access/refresh token，并在 access token 到期前自动刷新。
• 独立凭据存储：不读写 ~/.codex/auth.json，避免影响 Codex CLI 的登录状态。
• Web 设置面板：查看登录状态、账号、订阅计划、限流窗口用量、令牌到期时间及可用模型。
• 对话内认证工具：支持登录、状态查询和登出，无需离开当前会话。
• 同源 HTTP API：为设置面板和外部状态检查提供 no-store JSON 端点。

快速开始

1. 获取并构建插件

需要已安装 DSH、Node.js 和 pnpm。

git clone https://github.com/jasper-zsh/dsh-plugin-llm-codex.git
cd dsh-plugin-llm-codex
pnpm install

pnpm install 会通过 prepare 脚本自动构建 lib/。也可以随时手动执行 pnpm build。

2. 安装到 Web profile

在插件仓库目录中运行：

dsh plugin --profile web add "$PWD"

如果 dsh 不在 PATH 中，可以直接调用 DSH 构建产物：

node <dsh-checkout>/lib/bin.js plugin --profile web add "$PWD"

该包不是 profile bundle；安装时若出现 declares no dsh.bundle 提示属于正常现象，下一步会显式挂载插件。

3. 挂载插件

编辑 $DSH_HOME/profiles/web/cordis.patch.yml（默认路径为 ~/.dsh/profiles/web/cordis.patch.yml），将下面的 patch 项合并到现有顶层数组中：

- insert:
    - id: llm-codex
      name: dsh-plugin-llm-codex

如果文件当前内容为 []，直接用上面的内容替换即可；如果已有其他 patch，请保留它们并追加该项。

4. 配置模型路由

编辑 $DSH_HOME/settings.yaml（默认路径为 ~/.dsh/settings.yaml），加入：

llm-pi-ai:
  providers:
    openai-codex:
      apiKeyEnv: CODEX_OAUTH_ACCESS_TOKEN

apiKeyEnv 在这里是 DSH 凭据引用，而不是需要手动填写的环境变量。插件登录成功后会写入同名凭据，llm-pi-ai 会在每次请求时解析最新值。

5. 重启并登录

初次安装后重启 dsh web，然后：

1. 打开 设置 → Codex 订阅。
2. 点击 使用 ChatGPT 账号登录。
3. 在打开的 OpenAI 页面中登录，并输入面板显示的一次性验证码。
4. 等待页面自动显示“已登录”。
5. 在模型选择器中选择 openai-codex 下的模型。

设备码有效期为 15 分钟。浏览器未自动打开时，可手动访问 https://auth.openai.com/codex/device。

验证安装

检查插件状态：

curl http://127.0.0.1:3080/llm-codex/status.json

重点关注以下字段：

• loggedIn：OAuth 凭据是否已保存。
• providerRegistered：openai-codex 路由是否已注册。
• codexModels：该路由当前公布的模型列表。
• usage：订阅计划及限流窗口用量；查询失败不会影响模型认证。

如不需要实时查询订阅用量，可使用：

curl 'http://127.0.0.1:3080/llm-codex/status.json?usage=0'

使用方式

Web 设置面板

“Codex 订阅”页面提供：

• 登录、重新登录、登出和刷新状态；
• 一次性设备码及验证链接；
• ChatGPT 账号和订阅计划；
• 主、次限流窗口用量；
• access token 到期时间；
• openai-codex 路由状态和可用模型。

对话内工具

工具	作用
codex_auth_login	发起设备码登录；force: true 可重新登录或切换账号。
codex_auth_status	查询登录、路由、模型及订阅用量状态。
codex_auth_logout	清除已保存的 OAuth 凭据并取消待处理的登录。

例如，可直接让 Agent“登录 Codex”或“检查 Codex 登录状态”。

HTTP API

方法	路径	说明
GET	/llm-codex/status.json	获取状态；传入 ?usage=0 可跳过订阅用量查询。
POST	/llm-codex/login	发起登录；JSON body 为 {"force": false}。
POST	/llm-codex/logout	清除凭据并登出。

所有响应均设置 Cache-Control: no-store，状态响应不会返回原始令牌。

令牌与安全

插件使用以下 DSH credential refs：

凭据引用	用途
CODEX_OAUTH_ACCESS_TOKEN	供 openai-codex 路由发起请求。
CODEX_OAUTH_REFRESH_TOKEN	在 access token 临近过期时换取新令牌。

工作方式：

1. access token 按 JWT exp 在到期前 5 分钟刷新；
2. OpenAI 返回轮换后的 refresh token 时立即更新存储；
3. 临时刷新失败会延迟重试；HTTP 400/401 会视为凭据失效并停止自动重试；
4. 重新登录或登出时，登录轮询与刷新定时器会相应重置。

请仅在可信环境中运行 DSH Web，不要将这些认证端点直接暴露给不受信任的网络。

常见问题

设置中没有“Codex 订阅”

确认：

• 插件已出现在 Web profile 的依赖中；
• cordis.patch.yml 中已插入 dsh-plugin-llm-codex；
• 已构建 lib/；
• 修改后已重启当前 dsh web 进程。

页面显示“openai-codex 路由未注册”

检查 $DSH_HOME/settings.yaml 中的 llm-pi-ai.providers.openai-codex 配置及 YAML 缩进。该设置支持热更新，但首次安装插件后仍建议重启 DSH Web。

登录一直处于等待状态

确认已在验证页面输入正确设备码。设备码 15 分钟后失效，超时后请重新发起登录。

令牌失效或需要切换账号

在设置页点击“重新登录（换账号）”，或先调用 codex_auth_logout，再调用 codex_auth_login。

开发

pnpm install      # 安装依赖，并通过 prepare 构建一次
pnpm build        # 构建 Host 与 Web client 到 lib/
pnpm dev          # 监听源码并持续重建
pnpm typecheck    # 执行严格 TypeScript 类型检查

lib/ 为构建产物且已加入 .gitignore。为了确保 Host 和 Web client 同时加载最新版本，完成修改后请重新构建并重启 dsh web。

项目结构

路径	说明
src/index.ts	Host 插件：OAuth 流程、令牌刷新、状态聚合、HTTP API 和模型工具。
src/client/index.tsx	Web client：注册“Codex 订阅”设置页。
src/client/styles.ts	设置页样式。
src/types.ts	Host 与 Web client 共用的 HTTP 数据类型。
tsdown.config.ts	Host ESM 与 Web client lazy-CJS 双构建配置。
package.json	包入口、脚本及 DSH Web client 声明。

实现说明与限制

• 插件依赖 DSH 的 credentials、llm、webServer 和 timer 服务；对话内工具还需要 tools 服务。
• OAuth client id、device authorization 端点和验证页与 Codex CLI 生态中的公开实现保持一致，但并非 OpenAI 面向第三方提供的稳定公共集成接口；上游变更时插件可能需要同步适配。
• 使用 ChatGPT/Codex 订阅经第三方客户端调用，受 OpenAI 条款、订阅计划和账号限制约束，请自行确认合规性。