JetBrains CC GUI 集成 Codex SDK 快速上手指南:对称架构、统一权限映射与实战调试

【免费下载链接】jetbrains-cc-gui

Jetbrains Claude Code and Codex GUI Plugin

项目地址: https://gitcode.com/gh_mirrors/id/jetbrains-cc-gui
点击查看 免费下载

本文是 JetBrains Claude Code and Codex GUI 插件(本项目)中 Codex SDK(@openai/codex-sdk)集成 的完整技术指南,面向希望在 IDEA 内同时使用 Claude 与 Codex 的开发者。文章以官方集成文档 CODEX-INTEGRATION-QUICKSTART.md 为主体骨架,并结合 ai-bridge 与 CodexSDKBridge.java 的真实源码逐层展开。读完本文,你将掌握 Codex 集成的对称架构原理、统一三态权限模型(DEFAULT / SANDBOX / YOLO)如何翻译为 Codex 原生配置、threadId 与 sessionId 的自动映射机制,以及从 API Key 配置、命令行自测到 Java + Node.js 联调、故障排查的完整实战路径。

一、集成概览:Codex 与 Claude 在同一架构下的"完美对称"

本项目原本以 Claude Agent SDK(@anthropic-ai/claude-agent-sdk)为核心能力。本次集成引入了 OpenAI 的 Codex SDK(@openai/codex-sdk),并刻意复用了 Claude 既有的一整套优雅架构,而不是另起炉灶。集成文档明确列出了新增/变更的文件清单:

ai-bridge/
├── utils/permission-mapper.js           [NEW] Permission translation layer
├── services/codex/message-service.js    [UPDATED] Codex SDK integration
├── channel-manager.js                   [UPDATED] Enabled Codex routing
└── package.json                         [UPDATED] Added @openai/codex-sdk

src/main/java/.../CodexSDKBridge.java   [UPDATED] Unified parameter mapping

docs/
├── MULTI-PROVIDER-ARCHITECTURE.md      [NEW] Complete architecture guide
└── CODEX-INTEGRATION-QUICKSTART.md     [NEW] This file

说明:集成文档中列出的 @openai/codex-sdk 依赖(约 40MB)并非直接写在 ai-bridge/package.json 的 dependencies 中(该文件目前仅声明了 sql.js),而是由插件侧通过依赖管理器安装到独立目录。这一点在 Java 源码中有明确注释:Codex SDK is installed in ~/.codemoss/dependencies/codex-sdk/, not in ai-bridge(见 CodexSDKBridge.java),并会在每次发送前通过 setCodexExecutablePermission 为该目录下各平台 vendor 内的 codex / codex.exe 二进制设置可执行权限。

核心新增能力

  • 统一权限系统:DEFAULT、SANDBOX、YOLO 三种权限模式在所有 Provider 间一致生效,Java 层只感知一套语义;
  • 自动映射:sessionId ↔ threadId 的翻译由 channel-manager 自动完成,上层无需感知差异;
  • 流式响应:Claude 与 Codex 均支持实时逐 token 输出;
  • 模块化设计:按同一模式新增 Gemini 等 Provider 预计可在 1 小时内完成("Modular Design" 是集成文档明确给出的预期,后续代码层面由统一的服务接口与工厂模式支撑)。

二、对称架构:Java → Bridge → ai-bridge → SDK

集成文档给出了三路 Provider 的对称设计图:

Claude:  Java → ClaudeSDKBridge → ai-bridge → @anthropic-ai/claude-agent-sdk
Codex:   Java → CodexSDKBridge  → ai-bridge → @openai/codex-sdk
Gemini:  Java → GeminiSDKBridge → ai-bridge → (future)
         ↑ Perfect symmetry - easy to maintain

这一对称性在仓库中有完整落地的证据链。Node.js 侧的入口 channel-manager.js 是统一路由器:它按 process.argv[2] 的 provider 参数(claude、codex、grok、kimi、opencode、pi、omp、dsh、minimax、zcode、system)分发到对应 channel,其中 Codex 由 codex-channel.js 处理,支持 send、getMcpServerTools、listModels 三个命令。

一条 Codex 消息的完整链路为:

1. IDEA 中输入消息
2. Java 层 CodexSDKBridge 构造 stdin JSON(message / threadId / cwd / permissionMode / model ...)
   → 通过 ProcessBuilder 启动 Node.js 进程(node channel-manager.js codex send)
3. channel-manager.js 读取 stdin,按 provider 路由到 codex-channel
4. services/codex/message-service.js 调用 Codex SDK
   → 先经 PermissionMapper 映射权限
   → startThread() / resumeThread() + runStreamed() 流式执行
5. Node 侧以统一 console 协议回传事件([MESSAGE_START] / [CONTENT_DELTA] / [MESSAGE_END] ...)
6. Java 层逐行解析 stdout,通过 MessageCallback 驱动 UI 更新

该流程与 MULTI-PROVIDER-ARCHITECTURE.md 中 Message Flow 一节完全一致,可作为阅读架构设计的入口文档。

统一事件协议

不同 Provider 的原生事件格式差异很大(Claude 为 {type:'assistant', message:{...}},Codex 为 thread.* / turn.* / item.* 等),因此每个服务统一向 stdout 输出相同前缀的标记(见 MULTI-PROVIDER-ARCHITECTURE.md):

console.log('[MESSAGE_START]');
console.log('[CONTENT]', content);
console.log('[CONTENT_DELTA]', delta);
console.log('[MESSAGE_END]');

Java 侧 CodexSDKBridge.processOutputLine 则按这些前缀做协议解析:[MESSAGE_START] → message_start、[STREAM_START] → stream_start、[THREAD_ID] → session_id 回调、[CONTENT_DELTA] / [THINKING_DELTA] → 增量文本、[MESSAGE] → JSON 消息对象、[SEND_ERROR] → 错误上报。这正是"两套 SDK、一套协议"得以成立的关键。

三、统一权限模型:从三态模式到 Provider 原生配置

3.1 为什么需要 Permission Mapper

Claude 的权限是简单的字符串模式('default'、'sandbox'、'yolo'),而 Codex 的权限是一个复合配置对象:skipGitRepoCheck(是否跳过 Git 仓库检查)+ sandbox(read-only | workspace-write | danger-full-access)+ approvalPolicy(never | on-request | on-failure)+ 可选的 approvalsReviewer。两者无法直接对齐,因此项目在 ai-bridge/utils/permission-mapper.js 中实现了双向翻译层。

3.2 统一权限的四种语义(比文档多一种)

集成文档只讲了三种模式,而实际源码(permission-mapper.js)定义了四种规范化模式:

模式语义适用场景
DEFAULT危险操作前询问用户日常开发
SANDBOX只读,禁止修改与执行代码审查、探索
AUTO原生自动审查:由 Provider 的分类器/审查器决定审批需要自动审批但保留守卫的工作流
YOLO全自动批准一切操作自动化、可信环境

3.3 映射示例:YOLO

集成文档给出的核心示例在源码中完全可复现:

// User selects "YOLO" mode in IDEA
Java: permissionMode = "yolo"
  ↓
ai-bridge/utils/permission-mapper.js:
  - Claude: "yolo" → permissionMode: 'yolo'
  - Codex:  "yolo" → {skipGitRepoCheck: true, sandbox: 'danger-full-access'}
  ↓
SDK: Operates with provider-specific configuration

3.4 源码级映射细节

CodexPermissionMapper.toProvider 的具体映射逻辑(permission-mapper.js):

  • SANDBOX → {skipGitRepoCheck: true, sandbox: 'read-only', approvalPolicy: 'on-request'}:写操作一律只读并保持询问。注释特别说明:Codex CLI v0.149 移除了 untrusted 语义,其"运行前询问"行为已并入 on-request,因此这里不再传递 untrusted(详见 codex-utils.js 与 CodexSDKBridge.java);
  • YOLO → {skipGitRepoCheck: true, sandbox: 'danger-full-access', approvalPolicy: 'never'}:完全放行;
  • DEFAULT(默认分支)→ {skipGitRepoCheck: true, sandbox: 'workspace-write', approvalPolicy: 'on-request'}:允许写入工作区,但危险操作仍提示;
  • AUTO(原生自动审查)→ {skipGitRepoCheck: true, sandbox: 'workspace-write', approvalPolicy: 'on-request', approvalsReviewer: 'auto_review'}:借助 Codex 的 guarded contract,审查器处理审批请求,执行保持在项目沙箱内;
  • bypassPermissions 别名(对应 WebView 的 Full Auto/可信模式)→ workspace-write + approvalPolicy: 'never'(完全自动批准);
  • acceptEdits / autoEdit 别名(Agent 模式)→ workspace-write + on-request(自动应用文件修改,命令仍需确认)。

Windows 特例:由于 Windows 上的沙箱支持尚属实验性,非 AUTO 模式下所有映射会把 sandbox 替换为 danger-full-access,确保写操作可用(源码通过 isWindows() 判断,见 permission-mapper.js 与 Java 侧 resolveCodexSandboxMode 相同的平台兜底逻辑)。

3.5 环境变量级联覆盖(源码补充)

Java 层在启动 Node 子进程前,还会根据 permissionMode 直接注入 CODEX_SANDBOX_MODE、CODEX_SANDBOX、CODEX_APPROVAL_POLICY 环境变量,覆盖用户 ~/.codex/config.toml 中的既有配置(见 CodexSDKBridge.java)。而 Node 侧 message-service.js 又会读取 CODEX_SANDBOX_MODE / CODEX_APPROVAL_POLICY 作为最终覆盖(resolveSandboxModeOverride / resolveApprovalPolicyOverride),并用白名单校验取值(合法值见 codex-utils.js 的 VALID_SANDBOX_MODES 与 VALID_APPROVAL_POLICIES)。此外 buildCodexCliEnvironment 会从子进程环境中剥离 CODEX_* 污染变量与代理变量(除非显式设置 CC_GUI_CODEX_INHERIT_PROXY=1/true/yes/on 选择继承 Rider 的 HTTP/SOCKS 代理),避免外部的 CODEX_APPROVAL_POLICY 等意外破坏审批行为。

反查方向:CodexPermissionMapper.fromProvider 支持从 Codex 配置反推统一模式——sandbox: 'read-only' → SANDBOX、danger-full-access → YOLO、workspace-write → DEFAULT、approvalsReviewer === 'auto_review' → AUTO,为会话历史回显权限状态提供了依据。

四、会话管理:threadId 与 sessionId 的自动映射

Claude 使用 sessionId 标识会话,Codex 使用 threadId。集成文档给出的抽象方式为:

// Java layer (provider-agnostic)
sendMessage(channelId, message, conversationId, ...)

// Node.js layer (provider-specific)
Claude: receives as 'sessionId'
Codex:  receives as 'threadId'

// Magic: channel-manager.js handles the mapping automatically

在源码中,Java 侧 CodexSDKBridge.sendMessage 的签名明确注释 threadId(而非 sessionId),并将 threadId 原样写入 stdin JSON;Node 侧 codex-channel.js 解构 stdinData.threadId 后传给 codexSendMessage;最终 message-service.js 根据 threadId 是否为空决定调用 codex.startThread(threadOptions)(新线程)还是 codex.resumeThread(threadId, threadOptions)(恢复线程)。

两个重要的实现细节:

  1. 恢复线程时不重复设置工作目录:workingDirectory 只在新建线程时写入,恢复线程时跳过,以便 SDK 通过 threadId 做会话查找([DEBUG] Resuming thread - skipping workingDirectory to allow session lookup);
  2. 新线程的消息前置 AGENTS.md 指令:仅在新建线程且提供 cwd 时,collectAgentsInstructions(cwd) 会按 AGENTS.override.md → AGENTS.md → CLAUDE.md 的优先级读取项目指令(单文件上限 32KB,见 codex-utils.js),并以 <agents-instructions> 标签拼接到用户消息前。

线程创建时还默认设置 maxTurns: 200,并支持 reasoningEffort(推理深度,默认 medium)、model、approvalPolicy、sandboxMode 等线程选项(message-service.js)。

五、配置:API Key 与权限模式

5.1 API Key 配置(两种方式)

方式一:插件设置(推荐)

IDEA → Settings → Codex API Key: sk-...
               → Base URL: https://api.openai.com (optional)

方式二:代码配置

CodexSDKBridge bridge = new CodexSDKBridge();
bridge.setApiKey("sk-...");
bridge.setBaseUrl("https://custom-endpoint.com"); // Optional

Java 侧的 setApiKey / setBaseUrl 方法实现于 CodexSDKBridge.java。需要留意的是:Codex SDK 也支持 CLI Login 模式——当设置启用该模式时,Java 层会跳过 apiKey / baseUrl 的传递,改用 ~/.codex/auth.json 中的原生 OAuth 令牌(isCodexCliLoginActive,见 CodexSDKBridge.java)。

Node 侧 message-service.js 收到 baseUrl / apiKey 后写入 SDK 选项;同时始终开启 model_supports_reasoning_summaries: true,确保不在 SDK 已知推理模型白名单内的自定义模型也能获得思考/推理参数;若传入 serviceTier(如 "fast",对应 Codex CLI 的 /fast),还会追加 features.fast_mode 与 service_tier 配置。

5.2 权限模式速查表

ModeBehaviorUse Case
DEFAULTAsk before dangerous operationsNormal development
SANDBOXRead-only, no modificationsCode review, exploration
YOLOAuto-approve everythingAutomation, trusted environments

(AUTO 模式及 bypassPermissions / acceptEdits 别名见上文 3.4 节源码映射。)

六、测试:从 Node 单测到 Java + Node 联调

6.1 快速自测(Node.js)

集成文档提供了两条可直接复制的命令:

cd ai-bridge

# Test permission mapper
node -e "
import {PermissionMapperFactory} from './utils/permission-mapper.js';
console.log(PermissionMapperFactory.toProvider('codex', 'yolo'));
// → {skipGitRepoCheck: true, sandbox: 'danger-full-access'}
"

# Test Codex service (requires API key)
echo '{"message":"Hello","threadId":"","cwd":"","permissionMode":"default"}' | \
  CODEX_USE_STDIN=true node channel-manager.js codex send

第一条验证的是工厂入口 PermissionMapperFactory.toProvider('codex', ...)(permission-mapper.js),第二条走的是完整的 stdin → 路由 → SDK 调用链路。除此之外,ai-bridge 还提供 npm 脚本(见 ai-bridge/package.json):

cd ai-bridge
npm run test:codex   # 等价于 node channel-manager.js codex send
npm run test:claude  # 等价于 node channel-manager.js claude send
npm run test:sdk-status  # node channel-manager.js system getSdkStatus

SDK 可用性也可用系统命令单独探测:node channel-manager.js system checkCodexSdk(由 channel-manager.js 中的 isCodexSdkAvailable() 支撑)。

6.2 Java + Node.js 集成测试

CodexSDKBridge bridge = new CodexSDKBridge();
bridge.setApiKey("sk-...");

CompletableFuture<SDKResult> future = bridge.sendMessage(
    "channel-1",
    "Explain this codebase structure",
    null, // threadId (new conversation)
    "/path/to/project",
    null, // attachments (Codex doesn't support)
    "default", // permission mode
    "gpt-5.1", // model
    new MessageCallback() {
        public void onMessage(String type, String content) {
            System.out.println(type + ": " + content);
        }
        public void onError(String error) {
            System.err.println("Error: " + error);
        }
        public void onComplete(SDKResult result) {
            System.out.println("Done: " + result.finalResult);
        }
    }
);

注意:以上为集成文档中的示例签名(model 参数直接跟在 permissionMode 之后)。实际仓库中的 sendMessage 签名在此基础上扩展了 agentPrompt(Codex 不支持 system prompt,因此 Agent 角色指令以 ## Agent Role and Instructions 追加到用户消息末尾)、reasoningEffort(默认 medium)、serviceTier 三个参数,调用时需按实际签名为准。

仓库内置的协议级测试同样值得参考:CodexSDKBridgeProtocolTest.java 与 CodexSDKBridgeHistoryTest.java 覆盖了 Java 侧的协议解析与会话历史读取行为。

6.3 关于图片附件的差异

集成文档的能力对比中标注 Codex 不支持附件。更精确的源码事实是:Codex SDK 支持 local_image 类型的图片输入,但要求本地文件路径而非 base64。Java 侧 buildCodexAttachments 会把 UI 传入的 base64 图片解码后写入应用数据目录(codex-images/),再以 {type:'local_image', path: ...} 传给 Node 侧;Node 侧 buildCodexRunInput 在存在图片附件时将输入组装为 [{type:'text',...}, ...imageInputs] 数组形式(空文本时使用哨兵字符 \u2063 规避 Codex CLI 对空 stdin 的拒绝)。文本、文件等非图片附件仍为 Claude 独有能力。

七、能力对比

FeatureClaudeCodexNotes
Streaming✅✅Real-time responses
Session Resume✅✅Continue conversations
Attachments✅❌Images, files (Claude only)
Permission Control✅✅Unified 3-mode system
Custom Models✅✅Model selection supported
IDE Context✅⚠️openedFiles (Claude only)

补充的源码事实:Codex 侧在新建线程时会自动读取并注入项目 AGENTS.md 指令(见第四节),可视为对 IDE 上下文缺口的部分弥补;且 message-service.js 对 auto 模式强制校验 SDK 版本不低于 0.146.0(CODEX_NATIVE_AUTO_REVIEW_MIN_VERSION),否则报错提示到 Settings > Dependencies 升级。

八、快速启用:三步走

  1. Configure API Key:在插件设置中填入 OpenAI API Key(或启用 CLI Login 模式复用 ~/.codex/auth.json);
  2. Select Provider:在 UI 的 Provider 下拉框中选择 "Codex";
  3. Start Chatting:发送一条消息,流式输出应立刻生效;随后可依次尝试 DEFAULT、SANDBOX、YOLO 三种权限模式验证映射行为。

九、故障排查

"Codex support is temporarily disabled"

Cause:@openai/codex-sdk 未安装 Fix:SDK 由插件依赖管理(Settings > Dependencies)安装到 ~/.codemoss/dependencies/codex-sdk/。Node 侧 ensureCodexSdk() 在缺失时会抛出 SDK_NOT_INSTALLED 错误并提示安装(见 codex-utils.js):

cd ai-bridge
npm install @openai/codex-sdk

"API key not found"

Cause:未配置 API Key Fix:在插件设置中配置,或通过 bridge.setApiKey(...) 注入;使用 CLI Login 模式时则无需 Key。

"Permission denied"

Cause:权限模式与 Provider 配置不匹配 Fix:核对 permission-mapper.js 中对应模式的映射(含环境变量覆盖),确认沙箱模式与审批策略组合符合预期。

Thread ID not captured

Cause:事件解析问题 Fix:确认控制台日志中 [THREAD_ID] 前缀被正常输出——Java 侧 processOutputLine 正是依赖该标记触发 session_id 回调(CodexSDKBridge.java)。

常见运行期错误(源码内置诊断)

buildErrorPayload 会对错误自动分类并给出中文排查建议:鉴权错误(API key / 401 / CODEX_API_KEY 缺失等)、网络错误(ECONNREFUSED / ETIMEDOUT / fetch failed 等)、以及 thread writer 冲突(already has an active writer)——后者是本地进程重叠而非线程过期,插件会先自动停止上一轮再重发,遇到时等待几秒重发即可,无需新建会话。此外 Java 侧设有 10 分钟静默看门狗(CODEX_NO_OUTPUT_TIMEOUT_MS):只有持续无输出的"假死"才会被终止,长时间流式输出(大重构、全量测试)不会被误杀(CodexSDKBridge.java)。

十、高级用法

10.1 恢复 Codex 线程

// First message (creates thread)
SDKResult result1 = bridge.sendMessage(..., null, ...).get();
String threadId = extractThreadId(result1); // From session_id callback

// Continue conversation
SDKResult result2 = bridge.sendMessage(..., threadId, ...).get();

从源码看,threadId 会在流式过程中通过 [THREAD_ID] 事件实时回传(session_id 回调),Node 侧最终结果 JSON 也包含 threadId 字段(message-service.js),Java 侧 getSessionMessages 则可结合 CodexHistoryReader 读取持久化的会话历史用于 UI 恢复。

10.2 自定义沙箱模式

集成文档给出了在 permission-mapper 中扩展自定义映射的范式:

// In permission-mapper.js, create custom mapping
case 'CUSTOM_MODE':
  return {
    skipGitRepoCheck: true,
    sandbox: 'workspace-write',
    additionalRestrictions: {...}
  };

实际落地时还要注意两点:新模式的字符串需先能被 normalizeUnifiedMode 归一化(permission-mapper.js),并且 CODEX_SANDBOX_MODE / CODEX_APPROVAL_POLICY 的取值必须落在 VALID_SANDBOX_MODES / VALID_APPROVAL_POLICIES 白名单内,否则会被 resolveSandboxModeOverride / resolveApprovalPolicyOverride 忽略(codex-utils.js)。

十一、代码模式:错误处理与取消

错误处理

future.exceptionally(ex -> {
    SDKResult errorResult = new SDKResult();
    errorResult.success = false;
    errorResult.error = ex.getMessage();
    return errorResult;
});

取消

String channelId = "my-channel";
// ... start operation ...

// Cancel if needed
bridge.interruptChannel(channelId);

取消的底层保证来自两点:Java 侧 channelSendLocks(按 channelId 串行化每一轮的发送,阻止快速 Stop/Send 产生重叠的线程 writer)与 processManager.interruptChannel(终止进程树);Node 侧每个 turn 持有独立的 AbortController,通过 signal 传入 thread.runStreamed 以实现流级中断(message-service.js)。Java 侧 processOutputLine 检测到 wasInterrupted 时以 "User interrupted" 回调 onComplete。

十二、性能说明

集成文档给出的量级(属项目自述,非外部基准数据):

  • Package Size:@openai/codex-sdk 约为插件增加 40MB 体积;
  • Startup Time:Node.js 子进程启动约 100-200ms;
  • Streaming:首个 token 通常在 500-1000ms 内到达;
  • Memory:每个活动 channel 约占用 50-100MB 内存。

对应源码侧的配套设计:SDK 采用动态懒加载(ensureCodexSdk 缓存单例,见 codex-utils.js);Java 侧按 channel 复用进程管理并在 finally 中统一回收(unregisterProcess + waitForProcessTermination),避免进程泄漏。

十三、未来增强(按集成文档)

  1. Gemini Integration:沿用同一模式(文档预期 1 小时内完成,PermissionMapperFactory 已预留 gemini 分支并抛出 "not yet implemented",见 permission-mapper.js);
  2. Provider Fallback:主 Provider 失败时自动切换;
  3. Response Caching:缓存相同查询的响应;
  4. Multi-Provider Comparison:同一查询发送到多个 Provider 对比输出。

十四、设计哲学

集成文档总结的四条原则,与源码风格一一对应:

  1. "Simple is better than complex" —— Permission mapper 单一职责,只做翻译不做业务;
  2. "Explicit is better than implicit" —— threadId 与 sessionId 的差异在注释与日志中明确记录(如 message-service.js 的文件头说明);
  3. "Practicality beats purity" —— 不同模型映射到公共接口而非追求理论统一;
  4. "Readability counts" —— 代码结构镜像心智模型,Java/Node 分层清晰。

延伸阅读

【免费下载链接】jetbrains-cc-gui

Jetbrains Claude Code and Codex GUI Plugin

项目地址: https://gitcode.com/gh_mirrors/id/jetbrains-cc-gui
点击查看 免费下载

创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值