1. Windows 下 IDEA 接入 Claude Code 到底在解决什么问题很多在 Windows 上写 Java 的朋友第一次听到「IDEA 接入 Claude Code」会以为要装一个能直接连海外服务的插件结果折腾半天卡在连接失败。其实这条链路的核心不是让 IDEA 自己去连远端而是让 IDEA 通过本地已经跑起来的服务把代码上下文交给 Claude Code 处理再把结果回填到编辑器里。理解这一点后面所有配置都会顺很多。我自己在 Windows 11 IDEA 2023.2 上完整跑过一遍最直观的感受是只要本地服务是通的IDEA 这一侧其实只有三件事要做——装插件、填地址和令牌、验证连通。真正容易翻车的地方几乎都集中在「本地服务没起来」和「IDEA 内置代理拦截了 localhost」这两个点上。这篇教程面向的是已经在 Windows 上完成前置安装、本地服务能正常访问的读者。如果你还没装好前置环境建议先把本地服务跑通再回来否则 IDEA 里怎么点测试连接都会失败。整篇会按「前置确认 → 插件直连 → 内置终端 CLI 兜底 → 报错排查 → 验证请求」的顺序展开每一步都给可复制的命令和配置项尽量让你一次跑通。需要先明确一个概念这里的 Claude Code 能力是通过本地服务暴露出来的IDEA 只是它的一个前端。所以你在 IDEA 里看到的「连接成功」本质是 IDEA 插件成功访问了http://localhost:18789这个本地端口。端口、令牌、连接模式这三样对上了链路就通了。另外提醒一句Windows 上 IDEA 默认会读取系统代理设置。如果你之前配过任何全局代理localhost 请求有可能被拦下来表现就是「浏览器能打开、IDEA 里测试连接失败」。这个坑后面会专门讲怎么处理。2. 接入前的本地服务与令牌准备TaoToken 前置在动 IDEA 之前先把本地这一侧的状态确认清楚。这一步做扎实后面能省掉一大半排查时间。我习惯用「三查一备」来概括查服务、查端口、查令牌备份好连接参数。第一查是服务是否在跑。打开 Windows 的浏览器直接访问http://localhost:18789。如果能看到登录页或者服务状态页说明本地服务进程是活的。如果浏览器都打不开那 IDEA 里必然连不上先去把服务启动起来再说。启动命令通常是openclaw gateway start如果提示命令不存在说明环境变量没生效需要重启终端或者手动切到安装目录执行。第二查是端口占用。18789 这个端口如果被别的程序占了服务会启动失败或者行为异常。用下面这条命令看一下端口状态netstat -ano | findstr 18789正常应该能看到一个 LISTENING 状态的进程。如果发现端口被占用又找不到是谁可以重置一下 Windows 的网络地址转换服务再重启本地服务net stop winnat net start winnat openclaw gateway restart第三查是令牌。IDEA 插件连接本地服务时需要带上访问令牌这个令牌就是本地服务生成的。重新生成一条的命令是openclaw token generate执行后会输出一串令牌字符串先复制到记事本备用。注意令牌是有时效的如果你之前生成过又隔了很久建议重新生成一条避免用到过期令牌导致 401。关于模型侧的能力来源如果你希望本地服务背后对接的是稳定的模型通道可以在 TaoToken 的控制台里管理密钥和额度。它的 API 地址是https://taotoken.net/api控制台入口在 console密钥管理在 api-keys。需要说明的是这一步是给本地服务提供模型能力和 IDEA 插件本身的连接配置是两回事别混在一起。「一备」就是把三个参数记下来服务地址http://localhost:18789、访问令牌、连接模式选 Local Host。这三个值在 IDEA 插件配置里会原样用到提前备好能避免来回切换窗口。3. 可复制的 IDEA 插件配置与本地服务启动这一节是整篇的核心给你可以直接抄的配置。先说插件安装再说配置项最后给一份可复制的 settings 片段。插件安装走 JetBrains 市场最省事。按CtrlAltS打开设置左侧选 Plugins切到 Marketplace搜索Claude Code或OpenClaw。找到标注 Beta 的适配插件点 Install装完必须完全重启 IDEA——注意是关掉所有 IDEA 窗口重新打开最小化不算重启插件不会生效。重启后右侧边栏会出现插件图标点开首次会弹配置界面。这里要填的核心就是前面备好的三件套。为了让你少踩坑我把配置项整理成一张对照表配置项填写值说明服务地址 Base URLhttp://localhost:18789固定本地端口不要带结尾斜杠访问令牌 API Key上一步生成的令牌过期就重新 generate连接模式Local Host切勿选远程模式模型 Model ID本地服务配置的模型标识与本地服务保持一致如果你用的是支持 JSON 配置的插件版本可以直接把下面这段贴进插件的 settings 文件里。路径一般在C:\Users\你的用户名\AppData\Roaming\JetBrains\IDEA版本\options\下文件名以插件名为准{ claudeCode: { baseUrl: http://localhost:18789, apiKey: 在这里粘贴你的本地令牌, connectionMode: local, model: claude-code-local, timeout: 60000, proxy: { enabled: false, noProxy: [localhost, 127.0.0.1] } } }这里有几个细节值得单独说。proxy.enabled设成 false 是为了避免 IDEA 把 localhost 请求也走代理这是 Windows 上最常见的连接失败原因之一。noProxy里显式加上 localhost 和 127.0.0.1 是双保险。timeout给到 60000 毫秒是因为首次请求本地服务可能要加载模型上下文太短会误报超时。如果你更习惯 TOML 风格的配置等价写法是这样[claudeCode] baseUrl http://localhost:18789 apiKey 在这里粘贴你的本地令牌 connectionMode local model claude-code-local timeout 60000 [claudeCode.proxy] enabled false noProxy [localhost, 127.0.0.1]配置写完后先别急着在 IDEA 里点测试。回到 Windows 终端确认本地服务是启动状态openclaw gateway start openclaw --versionopenclaw --version能输出版本号说明 CLI 环境是通的。这两条命令跑通再回 IDEA 点 Test Connection成功率会高很多。整个链路是「IDEA 插件 → 本地服务 → 模型通道」任何一环断了都会表现为连接失败所以按顺序确认最省事。4. 验证请求与成功结果确认配置填完接下来就是验证。验证分两层先验证 IDEA 到本地服务的连通再验证一次真实的代码请求能不能拿到结果。第一层验证在插件配置界面点 Test Connection。成功会提示Connection Successful。如果失败先别改配置去浏览器再访问一次http://localhost:18789确认服务还活着。浏览器能开、IDEA 报失败基本就是代理或令牌问题。第二层验证是发一次真实请求。在 IDEA 里选中一段 Java 代码右键找插件提供的「优化代码」或「解释逻辑」指令。也可以按CtrlEsc调出对话面板输入一句自然语言比如「帮我解释这段代码的执行流程」。如果本地服务正常几秒内会返回结果。如果你想用命令行方式验证IDEA 内置终端也能直接调本地 CLI。按Ctrl反引号打开底部终端先确认环境openclaw --version然后跑一次分析命令openclaw analyze Demo.java正常会输出这段代码的分析结果。再试一下交互模式openclaw chat进入对话后输入一句代码相关问题能收到回复就说明整条链路完全打通了。这一步的意义在于它绕过了 IDEA 插件直接验证本地服务本身是否健康。如果 CLI 能通、插件不通问题就锁定在插件配置或 IDEA 代理上。成功的结果长这样插件面板返回结构化的代码建议CLI 返回文本分析两者内容风格一致。如果返回的是空结果或者报reading choices之类的错误说明请求发出去了但响应解析失败通常是模型标识或返回格式对不上回到配置里核对 Model ID。验证通过后建议把这次成功的配置参数再备份一份。Windows 上 IDEA 升级或者插件更新后偶尔会重置配置有备份能快速恢复。5. 常见报错排查对照这一节按真实报错来对照遇到问题直接查表。401 Unauthorized / 令牌无效最常见。原因是令牌过期或复制时带了空格。解决方法是重新生成openclaw token generate把新令牌完整粘贴到插件配置的 apiKey 字段注意首尾不要有空格或换行。local proxy failed / 连接被代理拦截Windows 上 IDEA 读取了系统代理localhost 请求被转发出去导致失败。解决方法是确认配置里proxy.enabled为 falsenoProxy包含 localhost 和 127.0.0.1。如果还不行去 IDEA 的Settings → Appearance Behavior → System Settings → HTTP Proxy里选 No proxy。reading choices 报错 / 响应解析失败请求发出去了但返回结构不符合预期。多半是 Model ID 填错或者本地服务背后的模型通道没配好。核对插件里的 Model ID 和本地服务配置是否一致必要时在 TaoToken 控制台确认密钥状态。OAuth 相关报错如果插件提示 OAuth 失败说明它尝试走了云端鉴权而不是本地模式。检查连接模式是否误选成了远程改回 Local Host。插件装了不显示IDEA 没完全重启或者版本低于 2021.3。关掉所有 IDEA 进程重开仍无效就升级 IDEA 到 2022 以上再重装插件。端口 18789 占用 / 连接超时按前面给的方式重置网络服务再重启本地服务net stop winnat net start winnat openclaw gateway restart内置终端识别不了 openclaw 命令环境变量没生效。重启电脑或者在终端里手动切到安装目录再执行。排查时记住一个原则先确认本地服务健康浏览器能开、CLI 能跑再查 IDEA 侧配置。顺序反了会浪费很多时间。6. 长期使用与能力扩展建议跑通之后日常使用其实很轻。选中代码右键、CtrlEsc调面板、内置终端敲命令三种方式按场景切换就行。写业务代码时我更多用右键指令做重构或者批量分析时用 CLI 更顺手。如果你打算长期把 Claude Code 用在编码和 Agent 场景上可以关注一下 Coding Plan它更适合持续性的编码任务。日常想快速验证某个模型的表现用 模型对话 直接试就行。接入过程中遇到配置问题接入文档 里有更细的参数说明密钥管理统一在 API Keys 里操作。最后给一个实用习惯每次 IDEA 或插件升级后先跑一遍openclaw --version和浏览器访问本地端口确认本地服务没被升级影响再打开 IDEA 用插件。这样能把问题挡在编辑器之外排查成本最低。
