【免费下载链接】jetbrains-cc-gui
Jetbrains Claude Code and Codex GUI Plugin
本文是 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)(恢复线程)。
两个重要的实现细节:
- 恢复线程时不重复设置工作目录:
workingDirectory只在新建线程时写入,恢复线程时跳过,以便 SDK 通过 threadId 做会话查找([DEBUG] Resuming thread - skipping workingDirectory to allow session lookup); - 新线程的消息前置 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 权限模式速查表
| Mode | Behavior | Use Case |
|---|---|---|
DEFAULT | Ask before dangerous operations | Normal development |
SANDBOX | Read-only, no modifications | Code review, exploration |
YOLO | Auto-approve everything | Automation, 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 独有能力。
七、能力对比
| Feature | Claude | Codex | Notes |
|---|---|---|---|
| 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 升级。
八、快速启用:三步走
- Configure API Key:在插件设置中填入 OpenAI API Key(或启用 CLI Login 模式复用
~/.codex/auth.json); - Select Provider:在 UI 的 Provider 下拉框中选择 "Codex";
- 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),避免进程泄漏。
十三、未来增强(按集成文档)
- Gemini Integration:沿用同一模式(文档预期 1 小时内完成,
PermissionMapperFactory已预留gemini分支并抛出 "not yet implemented",见 permission-mapper.js); - Provider Fallback:主 Provider 失败时自动切换;
- Response Caching:缓存相同查询的响应;
- Multi-Provider Comparison:同一查询发送到多个 Provider 对比输出。
十四、设计哲学
集成文档总结的四条原则,与源码风格一一对应:
- "Simple is better than complex" —— Permission mapper 单一职责,只做翻译不做业务;
- "Explicit is better than implicit" ——
threadId与sessionId的差异在注释与日志中明确记录(如 message-service.js 的文件头说明); - "Practicality beats purity" —— 不同模型映射到公共接口而非追求理论统一;
- "Readability counts" —— 代码结构镜像心智模型,Java/Node 分层清晰。
延伸阅读
- 完整多 Provider 架构设计:MULTI-PROVIDER-ARCHITECTURE.md
- 权限翻译层核心实现:ai-bridge/utils/permission-mapper.js 及其测试 permission-mapper.test.js
- Codex 消息服务:ai-bridge/services/codex/message-service.js
- Codex 工具函数与错误诊断:ai-bridge/services/codex/codex-utils.js
- Java 桥接实现:CodexSDKBridge.java
- 协议级测试:CodexSDKBridgeProtocolTest.java
【免费下载链接】jetbrains-cc-gui
Jetbrains Claude Code and Codex GUI Plugin
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考



