@zmide/opencode-codex-provider

English

面向同时使用 opencode 与 Codex app-server 用户的生产级桥接包。

它让 opencode 与 ai-sdk-provider-codex-cli 的对接路径更直接、可维护，包括：

• Provider 参数字段差异（如 reasoningEffort / reasoningSummary）
• 工具名差异（exec 与 bash）
• 会话恢复时历史 tool-result 结构不一致
• 工作区内频繁审批

适用场景

• 你主要在 opencode 工作，但核心模型依赖 Codex app-server
• 你希望通过已发布 npm 包接入，不再维护本地兼容封装
• 你希望降低线上使用中的工具调用、会话恢复和审批摩擦风险

安装

npm install @zmide/opencode-codex-provider

最小配置（推荐）

将 provider 与 plugin 指向同一个 npm 包：

{
  "plugin": ["@zmide/opencode-codex-provider"],
  "provider": {
    "codex-app-server": {
      "name": "Codex App Server",
      "npm": "@zmide/opencode-codex-provider"
    }
  },
  "models": {
    "codex-app-server/gpt-5.3-codex": {
      "name": "gpt-5.3-codex",
      "provider": "codex-app-server"
    }
  },
  "defaultSettings": {
    "codex-app-server": {
      "approvalPolicy": "on-request",
      "sandboxPolicy": "workspace-write",
      "threadMode": "stateless",
      "minCodexVersion": "0.105.0",
      "effort": "medium",
      "codexPath": "/absolute/path/to/codex",
      "configOverrides": {
        "example_provider": "example-provider",
        "example_provider_feature_flag": false
      }
    }
  }
}

说明：

• plugin[] 与 provider.codex-app-server.npm 建议保持同一包名。
• codexPath 和 configOverrides 请按你的环境替换。

快速验证

先确认 Codex CLI 本身可用：

codex exec --skip-git-repo-check -m gpt-5.3-codex "Reply with exactly: codex ok"

然后启动 opencode，验证：

1. 对话可以正常发起
2. 工具调用不再出现 exec 不可用错误
3. 会话恢复不再触发 ModelMessage[] schema 错误

Asciinema 演示（脱敏 + 沙盒）

建议用 asciinema 展示基于 npm 发布包的完整接入效果（包含模型使用与认证相关占位配置）：

• 仓库内已提供录制文件：docs/asciinema/opencode-codex-demo.cast
• 可选发布流程：
  1. asciinema upload docs/asciinema/opencode-codex-demo.cast
  2. 将下面嵌入代码中的 <CAST_ID> 替换为实际 ID： [![asciicast](https://asciinema.org/a/<CAST_ID>.svg)](https://asciinema.org/a/<CAST_ID>)

请务必在独立沙盒目录录制，不要在真实项目目录执行：

mkdir -p /tmp/opencode-codex-demo && cd /tmp/opencode-codex-demo
npm init -y
npm install @zmide/opencode-codex-provider

使用仅含示例值的演示配置（认证字段也使用占位）：

{
  "plugin": ["@zmide/opencode-codex-provider"],
  "provider": {
    "codex-app-server": {
      "name": "Codex App Server",
      "npm": "@zmide/opencode-codex-provider"
    }
  },
  "models": {
    "codex-app-server/gpt-5.3-codex": {
      "name": "gpt-5.3-codex",
      "provider": "codex-app-server"
    }
  },
  "defaultSettings": {
    "codex-app-server": {
      "codexPath": "/absolute/path/to/codex",
      "configOverrides": {
        "example_provider": "example-provider",
        "example_provider_auth_mode": "api-key",
        "example_provider_api_key_env": "CODEX_API_KEY"
      }
    }
  }
}

发布录像前请逐项确认：

• 画面中不包含用户名、主机名、家目录或本机项目绝对路径
• 不包含任何真实 token、cookie、API key、账号 ID
• 登录/认证过程要么提前完成，要么完全打码/剪掉
• 演示中仅使用 example_provider、CODEX_API_KEY 这类占位值

这个包做了什么

• 重写 providerOptions["codex-app-server"] 下的兼容字段
• 清理不兼容参数，仅保留合法字段
• 在生成与流式输出阶段统一工具名 exec -> bash
• 规范化 provider 执行的 tool-result 结构
• 注入 workspace-aware 的审批处理
• 导出 opencode 插件，修复历史消息里的异常 tool parts

审批策略（默认）

• 当 cwd 在当前工作区内时，命令审批为 acceptForSession
• 当 grantRoot 在当前工作区内时，文件变更审批为 acceptForSession
• 网络审批为 decline
• execution policy amendment 为 decline
• 若你自定义了审批 handler 且返回决策，则以你的决策为准

更多文档

• Architecture
• Troubleshooting

开发（维护者）

npm run validate

该命令会执行 format、lint、typecheck、test coverage 与 build。