dsh-plugin-llm-codex

dsh-plugin-llm-codex

让 https://github.com/deepseek-ai/DeepSeek-Harness 通过 **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。 ``bash 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

在插件仓库目录中运行： `bash dsh plugin --profile web add "$PWD" ` 如果 dsh 不在 PATH 中，可以直接调用 DSH 构建产物： `bash 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 项合并到现有顶层数组中： `yaml - insert: - id: llm-codex name: dsh-plugin-llm-codex ` > 如果文件当前内容为 []，直接用上面的内容替换即可；如果已有其他 patch，请保留它们并追加该项。

4. 配置模型路由

编辑 $DSH_HOME/settings.yaml（默认路径为 ~/.dsh/settings.yaml），加入： `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>。

验证安装

检查插件状态： `bash curl http://127.0.0.1:3080/llm-codex/status.json ` 重点关注以下字段： - loggedIn：OAuth 凭据是否已保存。 - providerRegistered：openai-codex 路由是否已注册。 - codexModels：该路由当前公布的模型列表。 - usage：订阅计划及限流窗口用量；查询失败不会影响模型认证。 如不需要实时查询订阅用量，可使用： `bash 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。

开发

`bash pnpm install # 安装依赖，并通过 prepare 构建一次 pnpm build # 构建 Host 与 Web client 到 lib/ pnpm dev # 监听源码并持续重建 pnpm typecheck # 执行严格 TypeScript 类型检查 ` lib/ 为构建产物且已加入 .gitignore。为了确保 Host 和 Web client 同时加载最新版本，完成修改后请重新构建并重启 dsh web。

项目结构

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

实现说明与限制

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