开局先交代背景Claude Code 和 Codex 这两个 AI 编码助手最近几乎是开发者圈子里绕不开的话题。一个是 Anthropic 家的一个是 OpenAI 家的能力各有侧重但真有一个共同槽点——它们默认都是命令行工具。你想在 IDEA 里写代码的同时用它们就只能在编辑器窗口和终端窗口之间来回切贴路径、贴代码、贴报错折腾得很。所以我自己动手做了一个开源的 IDEA 插件IDEA Claude Code or Codex GUI 插件。简单说就是把这两个 CLI 的完整交互能力搬进 IDE 的图形界面里。这篇文章就把这个插件的来龙去脉、设计思路、安装配置和踩坑记录一次说清楚适合所有在 IDEA 系 IDE 里写代码、又想用上 Claude Code 和 Codex 的开发者。1. 为什么要在 IDEA 里给 AI 编码助手套一个 GUI1.1 命令行工具的强大掩盖不了体验上的割裂先给没接触过这两个工具的朋友交代一下背景。Claude Code 是 Anthropic 推出的终端编程助手可以理解为在命令行里给你做代码理解、重构、调试的智能体Codex 是 OpenAI 的产品同样以终端交互为主擅长把工程级任务拆解成一步步工具调用去执行。两者在模型能力和工具链上各有千秋Claude Code 在长对话和代码理解上表现更稳定Codex 在自主执行和检索方面有自己的优势。但有一个体验短板是共同的它们都是跑在终端里的 CLI 应用。我自己的使用经历是这样的。平时主力 IDE 是 IntelliJ IDEA项目以 Java 和 Kotlin 为主。以前用 Claude Code 帮忙重构一个模块时得先切到终端手动 cd 到项目目录然后用自然语言描述需求。AI 回答里给出一堆文件引用和 diff 片段我还要回到 IDEA 里一个个找到对应文件人工比对。再比如 Codex 在调试一个自动化脚本时它会自己执行命令、观察输出、修改文件但这些过程在终端里是一行行的日志你只能干看着没法方便地跳转到它正在操作的那个文件或那行代码。这种割裂带来的损失不仅仅是“麻烦”而是潜移默化地降低了 AI 编码助手的使用频率。你想想人和工具的交互流畅度直接决定了工具被使用的次数。如果一个能力很强的助手使用成本高到让你犹豫“这次要不要切终端”那它在你工作流里的价值就打了折扣。我见过不少同事装上 CLI 之后就再也没打开过基本都是被这种上下文切换劝退的。1.2 三合一GUI 层、会话层、变更层到底解决什么我想要的不是把命令行输出原样贴到面板里而是做一个真正适合 IDE 场景的交互方式。整个插件围绕三个层面来组织。第一层是 GUI 层。Claude Code / Codex 的输入框、流式输出、按钮操作都要在 IDEA 的 Tool Window 里原生呈现符合 IDE 的使用习惯。你能像用终端一样和 AI 对话但不必离开编辑器。第二层是会话层。CLI 工具本身是有会话概念的你可以针对一个任务开启对话上下文AI 能记住前面聊的内容。插件把多轮会话的界面做出来并且把会话以树形结构保存在项目目录下。再次打开 IDEA能直接看到上一次任务聊到哪了不用像终端那样从历史输出里翻。第三层是变更层。这是我觉得体验提升最大的地方。AI 在生成代码、修改文件、执行重构时会在对话里给出具体的 diff。插件解析这些 diff转换成 IDEA 原生 Diff Viewer 可以展示的格式每一处修改都可以单独接受或拒绝还能直接跳转到对应文件。也就是说AI 的输出从“给你看一段文本”升级成了“给你一份可操作的文件变更清单”。这三个层面的组合才是我定义里的“GUI 化”。它不是把终端改成深色背景然后放两个按钮而是让 IDE 的工程能力、文件系统和 AI 的执行过程真正联动起来。1.3 插件的边界不碰模型不碰密钥只做体验增强决定动手写的时候我给自己定了几条很明确的边界这里也分享给想自己造轮子的朋友。第一条不走模型 API只调官方 CLI。市面上很多 AI 插件是直接封装模型接口比如填一个 API Key然后自己拼 prompt、自己管理上下文。这么做有好处但一旦你想要完整复刻 Claude Code 或 Codex 的智能体行为难度就指数级上升。所以我从一开始就决定所有底层智能都交给官方 CLI插件只负责把子进程的输入输出接到 GUI。CLI 怎么规划工具调用、怎么管理上下文我统统不碰。第二条不接管密钥和登录。官方 CLI 有自己的一套登录授权体系插件直接沿用。用户在本机上完成授权之后CLI 能跑插件就能跑。插件自己的设置里不需要存任何 API Key也没有必要。这样既减少安全风险也省了很多麻烦的授权流程设计。第三条GUI 只是表现层不覆盖 CLI 的能力。你可以完全继续用命令行的方式操作插件只是在旁边多提供一个图形入口。哪怕插件某天挂了也不会影响你原本的 CLI 工作流。边界定清楚之后开发的范围就很明确了一个能稳定拉起子进程并解析流式输出的引擎层一个能展示会话和 diff 的 UI 层再加上设置页面。这也是后面项目能保持轻量、迭代速度还比较快的原因。2. 核心设计思路双引擎抽象与 GUI 交互层2.1 双引擎架构一个 EngineAdapter 接口两套协议适配刚开始我打算只支持 Claude Code界面里写死了它的事件解析逻辑。后来 Codex 的用户呼声越来越高我硬着头皮加支持结果发现如果把解析逻辑全写在 UI 里两个引擎混在一起之后代码根本没法维护。于是我把引擎这层彻底抽象出来设计了EngineAdapter接口。接口大概长这样interface EngineAdapter { fun startSession(project: Project, config: EngineConfig): Session fun sendMessage(session: Session, message: String): FlowEngineEvent fun cancel(session: Session) fun getState(session: Session): SessionState fun parseRawOutput(line: String): ListEngineEvent }EngineEvent是所有引擎输出被归一化之后的事件模型主要类型有TextDelta、ToolCall、ToolResult、FileChange、SessionEnd这些。Claude Code 适配器做的工作是把 CLI 的stream-json输出映射到这些事件上Codex 适配器则解析它的执行日志和文件变更记录。这样做的好处显而易见。上层 UI 只依赖EngineAdapter和EngineEvent完全不关心底层跑的是哪个 CLI。用户切换引擎本质上是切换一个适配器实例。后面有合适的第三方工具想接入只要有人能写出一个实现EngineAdapter的类就能在插件里跑起来。开源社区里已经有人在研究把某种带推理能力的本地 CLI 接进来用的就是这个口子。2.2 GUI 设计会话导航、对话流、变更预览三个面板联动UI 布局我参考了 JetBrains 自家工具窗口的风格不做花哨交互只追求信息密度和操作效率。主 Tool Window 从左到右分成三个区域。左边是会话列表展示当前项目下所有历史会话带模糊搜索、重命名、删除操作。会话记录以 JSON 文件保存在项目的.idea/目录下不污染 Git 仓库也方便备份。中间是对话主面板消息列表支持完整 Markdown 渲染代码块有语法高亮文件引用可以 Ctrl 加点击跳转。右边是变更面板展示当前 AI 会话产生的所有文件修改。三个面板之间实时联动。当 AI 输出里提到某个文件名时对话面板会自动把文件名渲染成可点击的芯片样式点击后在右边变更面板里选中对应的 diff 预览。用户在右侧每做一个“接受”“拒绝”操作对话流里会对应生成一条操作记录这样整个 AI 的任务执行历史和你的决策痕迹都能完整回溯。这个设计在真正用起来的时候特别像 IDE 里跑代码评审。AI 是那个提交 PR 的人你是 reviewer右侧 diff 就是评审界面。你可以先看整体变更列表再逐文件把 diff 过一遍对不满意的地方直接拒绝。长期使用下来这种带审阅感的工作流比盲目全盘接受 AI 修改要靠谱得多。2.3 技术选型为什么用 Kotlin Swing而不是 Compose技术选型是很多插件开发者关心的话题。我的选择是 Kotlin Swing基于 IntelliJ Platform SDK。先说为什么不选 Compose for Desktop。虽然 Compose 写 UI 的语法更现代但作为 IDE 插件最重要的是接入平台本身的深度能力。Diff Viewer、Editor、Tool Window 这些组件和 JetBrains 的 GUI 体系是深度绑定的直接在 Swing 体系中操作它们最顺手。Compose 插件支持这几年进步不少但涉及到焦点管理、Tool Window 浮动、与 Editor 双向联动这种细节时坑还是比较多的。插件场景里稳定性优先级高于 UI 代码的写法舒适度。再说为什么不用纯 Java。Kotlin 的空安全、协程和数据类在处理流式输出和并发状态机时省了很多样板代码。尤其是Flow处理流式事件比 Java 的回调嵌套可读性强太多了。还有一点IntelliJ Platform 新版插件已经普遍采用 Kotlin遇到平台 API 用法问题社区里 Kotlin 的示例也更多。Swing 在这里还有一个隐形的优点对老版本 IDEA 的兼容性更好。很多公司还在用 2021 或 2022 版本的 IDEACompose 插件的兼容线一般卡得比较靠后而 Swing 插件的兼容范围可以拉得很宽。我插件的最低支持版本就定在了 2021.2这对有历史包袱的团队来说很友好。2.4 流式渲染的细节缓冲、EDT 与批量刷新做这类工具UI 性能的坑避不开这里单独讲讲流式渲染的实现经验。CLI 的输出是持续不断的事件流。如果你天真地把每个TextDelta事件立刻追加到 Swing 的文本组件里很快就会发现两个问题一是界面卡顿因为 GUI 更新跑在 EDT 线程高频更新的代价很大二是文字跳动看起来像浏览器里不停重排文本人的眼睛根本跟不上。解决思路是缓冲 批量刷新。我在ChatMessageViewModel里维护一个待渲染的字符串缓冲每隔 80 毫秒检查一次如果累计长度超过阈值就一次性把缓冲内容写入文档。整个过程在 EDT 上通过invokeLater调度。这样即使 CLI 输出非常密集界面也能保持很稳定的刷新节奏。另一个关键点是所有引擎子进程的输出读取绝对不能跑在 EDT 上。我用了协程的Dispatchers.IO去读 stdout读取到的原始行先做编码解码再投递到主线程的消息队列。命令行工具有时候会输出二进制内容或者非 UTF-8 字符读取的时候要容错否则一个解码异常就能让整个面板白屏。这个经验同样适用于你用其他语言写类似工具的场景。不管前端还是桌面端流式文本的渲染都该走“多生产者单消费者 缓冲批量提交”的模式这是绕不开的通用方案。3. 安装与配置实操从零到一跑通3.1 插件安装市场安装与本地安装两条路插件已经上架 JetBrains Marketplace最简单的方式是在 IDEA 里打开 Settings / Plugins / Marketplace搜索插件名称点击 Install 然后重启 IDE。但有几个细节值得提醒。第一插件对 IDEA 的版本有最低要求2021.2 以下版本装不上。如果你的 IDE 版本比较老可以先升级再装。第二如果你所在的网络环境访问 Marketplace 不稳定可以直接从 GitHub Releases 页面下载 zip 包然后在 Settings / Plugins 里选择 Install Plugin from Disk。这个方法同样适用于想抢先体验开发版的朋友。第三安装完成之后在右侧边栏找到插件图标第一次打开时如果 Tool Window 没有自动出现可以在 View / Tool Windows 菜单里手动点开。还有一个值得提的入口插件第一次运行时会自动检测本机环境把缺失的依赖项直接展示在欢迎页上。比如检测到没有 Node.js会显示“未找到 Node.js安装 Claude Code 前请先安装 Node 18”检测到没有 Codex CLI会显示官方安装命令。这个设计省去了很多“为什么按钮点了没反应”的初级问题。3.2 Claude Code 接入先把官方 CLI 跑通再连 GUI接入 Claude Code 前我强烈建议你先在终端里把官方 CLI 完整跑通一遍。这样做的好处是后续任何问题你都可以先确认“是 CLI 的问题还是插件的问题”排查范围缩小一半。第一步安装 Node.js 18 以上版本。macOS 用户有 Homebrew 环境的话一条命令就能装好Ubuntu 用户别直接用系统源里的旧 Node建议用 NodeSource 或 nvm 安装新版。第二步通过 npm 全局安装 Claude Codenpm install -g anthropic-ai/claude-code。第三步在终端执行claude按提示完成登录授权。登录成功后随便发一句话确认它能正常回复。第四步回到 IDEA打开插件的设置页在引擎路径里检查claude是否被自动识别。识别不到的手动填上which claude的结果。以上四步做完基本就能在插件里流畅对话了。有一个细节要特别留意插件启动子进程时的环境与你的 shell 不完全一致。比如 macOS 上如果你把 CLI 的安装路径写进了.zshrc而 IDEA 是通过 GUI 方式启动的它未必会加载.zshrc这时就需要在插件设置里手动指定可执行文件的绝对路径。这个问题在 Ubuntu 下也出现过解决方式完全一致。顺便说一句如果你更习惯图形化的安装方式官方也提供桌面版的安装包。下载安装后同样在插件的设置页里把可执行文件路径指到桌面版对应的二进制位置即可。两者底层是同一套协议插件不关心你用的是 CLI 版还是桌面版。3.3 Codex 接入官方登录与自定义 AI 端点Codex 的接入流程和 Claude Code 类似但有一点不同Codex 的会话模型更偏向“任务执行型”它会显式地调用读取文件、执行命令、写文件等工具。因此在插件里你会看到比 Claude Code 更丰富的工具调用事件卡片。第一步按照官方文档安装 Codex CLI。第二步在终端执行codex走完登录授权。第三步回到 IDEA 插件里把引擎切换到 Codex新建会话测试。第四步如果要接入自定义 AI 提供方在插件设置里找到“自定义 AI 端点”配置 Base URL、模型名和密钥。配置自定义端点时有几个细节必须说清楚。第一端点协议必须是 OpenAI 兼容的 chat completions 格式。第二Base URL 的路径要看你用的服务有些服务要求填到/v1有些已经包含了完整路径填错会直接 404。第三如果你配置的模型本身不支持某些功能比如没有 reasoning 能力那官方 Codex 默认发送的请求参数可能不被接受需要配合本地的模型参数调整。这一点在下一节讲 400 报错时会详细展开。顺便提一句我见过不少人在 VSCode 里用相关插件配置 Claude Code用法思路类似但在 IDEA 里这套 GUI 插件因为直接复用平台的 Diff Viewer审阅 AI 修改的体验会更顺手。3.4 环境变量与跨平台注意事项Windows、macOS、Ubuntu这个插件在 macOS 和 Linux 下的表现最稳定Windows 用户则建议优先走 WSL 环境。原因主要有两点这两个 CLI 在某些 Windows 原生 shell 环境下对符号链接和长路径的处理会出现奇怪的问题另外IDE 进程与 WSL 中的 CLI 通信时路径映射需要额外处理所以我在插件里专门做了 WSL 虚拟文件系统到 Windows 路径的转换。如果你在 Ubuntu 上开发有两点建议。第一Node.js 版本必须保证在 18 以上否则 Claude Code 可能因为语法不支持直接报错。第二不要忘了给 CLI 可执行文件正确的执行权限chmod x这类操作有时候被忽略导致插件报“permission denied”。环境变量方面插件子进程会继承 IDEA 的启动环境而不是用户打开终端时的 shell 环境。这带来一个坑如果你在.bashrc或.zshrc里设置了某些网络相关、或模型默认参数相关的环境变量插件在不经意间也会继承下来。反过来如果你想在插件里单独调整环境变量设置页里也提供了自定义键值对配置。这个功能在遇到“终端里正常、插件里异常”的情况时非常有用。4. 踩坑实录与排查手册4.1 API error 400thinking mode 引发的参数问题先看这个报错本身API error: 400 the content[].thinking in the thinking mode。这是自定义端点场景下最常遇到的一个 400 返回原因可以拆成两层来看。第一层消息内容里出现了thinking类型的 content 块。Claude Code 和 Codex 在开启思考模式时会在消息序列里插入这种“中间推理”块这是模型侧的常见设计。第二层你的自定义端点或网关在校验请求时不允许 content 数组里出现thinking类型的块于是直接返回 400把整个请求拒绝掉。排查顺序建议是第一步先用官方端点复现同样请求。如果官方端点也报 400那大概是 CLI 版本和官方端点的兼容问题。第二步如果只有自定义端点报那就临时关闭思考模式测试。Claude Code 里可以用/config关掉 thinkingCodex 里通过配置参数或环境变量关掉。关闭后如果 400 消失基本就可以确定是端点不支持该消息类型。第三步用命令行原样执行一遍请求看 CLI 单独跑的时候会不会报同样的 400进一步把问题限定在“远端服务”还是“GUI 接入”上。为了方便用户插件在 0.3 版本之后加了一个开关叫“过滤 thinking 消息块”。打开之后请求发送前会先把thinking类型的 content 块从消息数组中剥掉。这样即使端点不够兼容也能绕开 400。但要注意去掉推理块可能会影响模型在部分任务上的输出质量所以这个开关默认是关闭的只在确认端点有这个问题时才需要打开。4.2 本地代理服务异常一个容易误判的报错另一个高频报错长这样cc switch local proxy failed while handling codex endpoint /responses。第一眼看过去很像插件网络模块出了问题。实际上这是 CLI 的网络代理配置和服务端通信失败导致的插件只是一个“传话人”。要理解这个报错关键在于明白这些 CLI 都允许配置一个本地代理服务来转发 HTTPS 请求。如果你的环境里存在代理相关配置但代理服务的端口没有启动或者该服务对响应流的转发处理有问题那么 CLI 在向/responses端点发送流式请求时就会失败。插件面板的表现是消息发出去之后很快就弹错没有任何模型输出。排查步骤我是这么做的。第一步在插件设置里把自定义网络配置全部清空改用 CLI 直连。第二步在终端里手动执行对应 CLI 的会话看能否正常连接远端服务。如果终端正常继续第三步检查代理服务的运行状态和日志确认它是否收到了来自 CLI 的连接请求。第四步检查 shell 配置文件里是否持久化了代理相关变量因为这些变量会被插件子进程继承即使你在插件设置里改了也可能被环境变量覆盖。解决方式是在插件设置中显式清空或覆盖这些变量。这个坑之所以容易误判是因为报错信息里出现了“local proxy”和“endpoint”两个词看起来像插件的网络层在报错。实际上插件在这个过程中只是按 CLI 的方式启动子进程并透传输出。我后来在插件里加了一个“查看原始输出”的按钮把 CLI 的 stdout 和 stderr 直接暴露给用户遇到这类网络层报错一眼就能看到真正的根因不用再猜。4.3 高频问题速查表与日志定位技巧把群里和 issue 区反复出现的问题汇总成一张速查表方便拿来即用。现象可能原因处理建议面板空白无响应插件未启用或 CLI 未安装检查插件启用状态在设置里手动指定 CLI 路径发送消息后无任何输出CLI 登录态失效在终端重新运行 claude / codex 完成授权输出文字跳字、卡顿渲染缓冲参数过小设置里调大批量刷新阈值默认 80ms / 200 字符Diff 预览与实际文件不一致CLI 基于旧缓存生成 diff清理 IDE 缓存或刷新文件索引后重新触发会话历史丢失插件存储目录权限异常检查 .idea/claude-code-gui 目录写入权限自定义端点返回 404Base URL 路径不对确认服务要求的路径是否包含 /v1 后缀自定义端点返回 400thinking 消息块不被接受按 4.1 步骤排查打开过滤 thinking 开关流式输出没有到达面板代理服务或环境变量干扰按 4.2 的排查步骤处理先清空代理配置日志定位是排查一切问题的关键。插件在 Tool Window 的设置菜单里提供“导出日志”入口导出的 zip 包含插件自身的运行日志、CLI 的 stdout/stderr、以及关键配置信息脱敏后。提交 issue 的时候带上这份日志基本能省掉两三轮沟通。我经常在 issue 区看到类似“我遇到了一个 bug”却没附日志的反馈回一句“先导出日志”的效率比反复追问高得多。5. 开源社区反馈与后续规划5.1 社区反馈带来的设计改变项目开源之后收到的反馈远超预期。最开始上线时只有 Claude Code 支持评论区陆续有人问 Codex于是我把双引擎架构做出来。也有人问了 Edge case比如“会话里 AI 提到了一个图片文件为什么 URL 渲染不出来”“为什么某些代码块的折叠状态不能保存”等等。这些反馈多数来自真实使用场景对打磨细节帮助非常大。有一个印象深刻的改进来自一位用插件做大型前端项目重构的开发者。他提到右侧变更面板在文件变多时很难按目录浏览建议做成类似 Git 工具窗口的树形分组结构。我花了一个周末把变更列表从平铺改成树形按顶层目录聚合再点开每个目录看文件。改完之后我自己的日常使用效率也明显提升尤其在 AI 一次改多个模块的场合。还有一位用户提了个很刁钻的需求希望在对话流里支持对 AI 给出的代码块做一键复制同时复制的时候自动保持缩进规则。这个看着简单实则涉及 IDEA 的代码风格配置读取后来我通过读取项目级 code style 规则做掉了。这种“IDE 原生感”的特性正是命令行工具做不到的。5.2 后续路线图与扩展思路接下来主要做几件事。第一JetBrains 全家桶适配。现在插件在 IDEA Community 和 Ultimate 上表现稳定但 PyCharm、GoLand、WebStorm 的 Tool Window 布局细节还有差异需要逐套调整。第二会话模板系统。内置“代码 review”“生成单元测试”“解释报错”等模板选择后自动填充首条提示词。第三diff 应用逻辑的精细化。目前支持的是整体开关文件下个版本希望做到基于 hunk 的接受/拒绝并且保留用户对 diff 的人工修改痕迹。扩展思路上我一直在想一个问题CLI 工具的 GUI 化到底应该“模拟终端交互”还是“提供 IDE 原生交互”。现在的版本偏向后者因此很多体验都是 IDE 用户熟悉的模式而不是终端模式的搬运。后续新功能也会延续这个理念。比如计划中的断点调试联动、与测试结果面板结合都是希望把 AI 行为嵌入到 IDE 的工作流而不是让 AI 在 IDE 里“假装是个终端”。5.3 给想做 CLI 工具 GUI 封装的人一点建议最后分享几条经验给同样有这个想法的开发者参考。第一先把 CLI 的输出格式研究透。写 GUI 之前先用脚本把 CLI 在各种场景下的 stdout 全部落盘一行行研究它的输出结构。你至少要搞清楚“哪些行是流式增量”“哪些事件表示工具调用”“diff 是从哪个字段解析出来的”。数据格式都还没摸清就画界面后面大概率返工。第二约定好问题的排查边界。GUI 层天然容易被当成背锅侠——网络问题是 GUI 的登录问题是 GUI 的模型问题是 GUI 的。所以从设计第一天起就要把日志做完整CLI 原始输出和插件自身日志分开记录。这样用户报错时你能快速判断根因属于哪边。第三别贪快先支持一个引擎跑通核心闭环会话、流式渲染、diff 预览、接受/拒绝。这个闭环能跑通用户就已经能感知到 GUI 的价值了。之后再谈加第二个引擎、自定义端点这些高级功能。功能太多反而会让核心体验不稳开源项目初期尤其如此。