解决 IDEA 2026.1 中 AI Assistant 功能不可用问题：配置 Claude Code 指南

1. 升级 IDEA 2026.1 后 AI Assistant 变灰的真实场景IDEA 2026.1 把 AI Assistant 的 Agents 面板做了一次比较大的改版很多人在升级之后第一反应是「功能被砍了」打开 AI ChatAgents 列表里 Claude Code、Codex 之类的条目全是灰色点不动鼠标悬停也没有任何提示。我这边升级当天也遇到了同样的情况一开始以为是插件没装重装 AI Assistant 插件、清缓存、Invalidate Caches 全试了一遍灰色依旧。后来把日志翻出来看才明白2026.1 的 AI Assistant 不再内置 Claude Code 的运行时它改成通过 ACPAgent Client Protocol去拉起一个本地的 agent 进程。也就是说IDEA 这边只是一个「客户端」真正干活的是你本机通过 npm 装的那个claude-code-acp。面板灰色本质上是 IDEA 找不到可用的 agent server或者找到了但acp.json里的启动命令写错了。所以这篇不是教你「怎么装插件」而是聚焦三件事acp.json到底该怎么写、npm 全局环境怎么校验、以及重启后怎么确认 Claude Code 真的被拉起来了。适合已经装好 IDEA 2026.1 和 AI Assistant 插件、但 Agents 面板点不动的同学。如果你还没装插件先把 AI Assistant 装上那步确实没什么坑略过。另外提一句Claude Code 本身要能跑通得有一个可用的模型通道。我这边是用 TaoToken 统一管的 Key后面会讲怎么把通道配进去避免你本地 agent 起来了却因为鉴权失败又变灰。2. 前置准备npm 环境与 TaoToken 通道在动acp.json之前先把两个前置条件确认掉不然配完还是灰的你会怀疑人生。第一个是 npm 全局环境。claude-code-acp是通过 npm 全局安装的IDEA 拉起它的时候用的是npx.cmdWindows或npxmacOS/Linux所以你的 Node 和 npm 必须在系统 PATH 里而且全局 bin 目录也要在 PATH 里。很多人 Node 是用 nvm 装的IDEA 作为 GUI 程序启动时读不到 nvm 注入的环境变量这是灰色问题里最常见的一类。第二个是模型通道。Claude Code 默认会走 Anthropic 官方通道但国内直连经常超时agent 进程起不来或者起来后请求失败IDEA 侧表现同样是灰色或转圈。我的做法是用 TaoToken 把 Key 和 API 地址统一收口本地 agent 只认一个 base URL 和一个 Key换模型、换通道都不用改acp.json。TaoToken 的定位是统一的模型 API 网关官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。它的好处是你不用在每台机器、每个工具里分别配不同厂商的 KeyClaude Code、Coding Plan、控制台都走同一套凭证。具体操作上先去控制台建一个 API Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite建好 Key 之后先别急着写进acp.json我们先用命令行验证通道是通的这样能把「通道问题」和「IDEA 配置问题」分开排查。验证命令后面第 4 节会给。如果你只是想先确认模型能不能调通不折腾本地 agent可以直接用模型对话页面试模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite3. 可复制配置npm 安装与 acp.json 骨架3.1 全局安装 claude-code-acp 并校验版本先装 ACP 适配器。它是 Zed 那边维护的作用是把 Claude Code 包装成符合 ACP 协议的 agent serverIDEA 才能通过协议跟它对话。# 全局安装 claude-code-acp npm install -g zed-industries/claude-code-acp # 查看全局包列表确认装上了 npm list -g --depth0正常输出里应该能看到类似这样一行-- zed-industries/claude-code-acp0.x.x如果npm list -g里没有它说明全局安装没成功或者你当前 shell 用的 npm 和 IDEA 能读到的 npm 不是同一个。这时候用下面两条命令定位# 看 npm 全局 bin 目录在哪 npm bin -g # 看 npx 实际解析到哪个路径 which npx # macOS / Linux where npx # Windows PowerShell / CMD把npm bin -g的输出记下来等会儿要确认它在系统 PATH 里。Windows 上如果where npx找不到基本就是 PATH 没配好IDEA 里必然灰色。3.2 acp.json 配置骨架在 IDEA 里打开 AI Assistant 的 ACP 配置入口AI Chat 设置里能找到 ACP 相关项会看到一个空的acp.json。把下面这份骨架贴进去{ default_mcp_settings: {}, agent_servers: { Claude Code: { command: npx.cmd, args: [ zed-industries/claude-code-acp ], env: { ACP_PERMISSION_MODE: bypassPermissions, ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的_TaoToken_Key }, use_idea_mcp: true, use_custom_mcp: true } } }几个字段逐个说明别照抄完就不管了command在 Windows 上写npx.cmdmacOS 和 Linux 写npx。这是最容易错的一处Windows 写npx有时能跑有时不能写npx.cmd最稳。args就是包名让 npx 去拉起这个包。注意这里不需要写-yIDEA 拉起时是非交互的加了反而可能出问题。env里ACP_PERMISSION_MODE设成bypassPermissions意思是 agent 执行工具调用时不再逐条弹权限确认。本地开发图省事可以这么设但你要清楚这意味着 agent 能直接读写文件、跑命令别在存着重要数据的目录里乱试。ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY就是接 TaoToken 的地方。base URL 用 https://taotoken.net/api Key 换成你在控制台建的那个。这样 Claude Code 的所有请求都走 TaoToken不用再单独配 Anthropic 官方通道。use_idea_mcp和use_custom_mcp保持 true让 IDEA 自带的 MCP 能力和自定义 MCP 都能被 agent 用上。注意acp.json是 JSON 格式不能有注释不能有多余逗号。贴完先用编辑器的 JSON 校验看一眼格式错了 IDEA 会静默忽略整个文件表现还是灰色。3.3 环境变量方式的替代写法如果你不想把 Key 明文写在acp.json里这个文件可能会被同步或备份可以把 Key 放到系统环境变量acp.json里只留 base URL{ default_mcp_settings: {}, agent_servers: { Claude Code: { command: npx.cmd, args: [zed-industries/claude-code-acp], env: { ACP_PERMISSION_MODE: bypassPermissions, ANTHROPIC_BASE_URL: https://taotoken.net/api }, use_idea_mcp: true, use_custom_mcp: true } } }然后在系统里设ANTHROPIC_API_KEY。Windows 用setx ANTHROPIC_API_KEY 你的KeymacOS/Linux 写进~/.zshrc或~/.bashrc。设完要重启 IDEA因为 GUI 程序只在启动时读一次环境变量。4. 验证请求命令行先跑通再回 IDEA配完别急着重启 IDEA先在终端里手动拉一次 agent确认通道和包都没问题。这一步能把 90% 的问题挡在 IDEA 之外。# 手动启动 ACP agent看它能不能正常初始化 npx zed-industries/claude-code-acp --help如果这条命令能打印出帮助信息说明包安装和 npx 解析都没问题。接着验证 TaoToken 通道# 用 curl 直接打 TaoToken 的 API确认 Key 有效 curl https://taotoken.net/api/v1/messages \ -H x-api-key: 你的_TaoToken_Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [{role: user, content: ping}] }返回里带content字段就说明通道通了。如果返回 401是 Key 不对返回 404检查 base URL 有没有多写或少写/api连接超时检查本机网络到 taotoken.net 的连通性。两条都通过之后重启 IDEA。打开 AI Chat 窗口在引擎选择列表里找Claude Code这时候它应该不再是灰色可以选中。选中后随便发一句「列出当前项目根目录的文件」看它能不能正常返回并调用工具。实测下来从灰色到可用卡点基本就三个npx 路径、acp.json格式、通道鉴权。命令行这两步跑通IDEA 里基本一次过。如果你更想先确认模型侧没问题也可以直接在模型对话页面发同样的 ping对比一下返回模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite5. 本篇常见错排查5.1 Agents 面板依旧全灰先看 IDEA 日志里有没有 ACP 相关报错。Help → Show Log in Explorer搜acp或agent_servers。如果日志里压根没有拉起 agent 的记录说明acp.json没被读到检查文件路径对不对、JSON 是否合法。如果日志里有spawn npx ENOENT就是 PATH 问题。Windows 上把command改成npx.cmd或者把 npm 全局 bin 目录加进系统 PATH 后重启 IDEA。5.2 agent 起来了但对话报鉴权失败这种是通道问题不是 IDEA 问题。回到第 4 节的 curl 验证确认 Key 和 base URL。常见错误是 base URL 写成了https://taotoken.net少了/api或者 Key 复制时带了空格。5.3 npx 每次都要重新下载包如果你看到日志里 npx 在反复下载zed-industries/claude-code-acp说明全局安装没生效npx 走了临时下载。回到 3.1 节确认npm list -g里有这个包没有就重装并检查 npm 全局目录权限。5.4 权限模式导致工具调用卡住ACP_PERMISSION_MODE如果没设成bypassPermissionsagent 每次读写文件都会等确认IDEA 侧看起来像卡死。本地开发可以设 bypass但生产目录慎用。想更安全可以改成默认模式接受每次弹窗确认。5.5 重启后引擎列表里没有 Claude Code确认agent_servers的 key 名字就是Claude CodeIDEA 是拿这个 key 当显示名的。名字写错比如写成claude-code列表里就不会出现对应条目。6. 长期编码场景的通道收口如果你只是偶尔用一下 AI Assistant上面这套配完就够了。但如果你是长期在 IDEA 里跑 Claude Code 做重构、写测试、跑 agent 任务建议把通道收口这件事做彻底一点。我现在的做法是本地所有 AI 编码工具——IDEA 里的 Claude Code、命令行的 Claude Code、以及一些自动化脚本——全部指向同一个 TaoToken base URLKey 用同一个。这样换模型、看用量、排查问题都只在一个地方。Coding Plan 页面可以看长期编码场景的用量和额度Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite接入文档里有各语言 SDK 和不同工具的配置示例acp.json里那两个环境变量就是从文档里对出来的接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteClaude Code 相关的接入细节文档里也有单独一节Claude Code 接入https://taotoken.net/doc/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite最后留一个我踩过的坑acp.json改完之后IDEA 有时候不会自动重载必须完全退出再启动光点 Restart 不够。尤其是 Windows 上托盘里还留着进程的时候重启只是开了个新窗口旧配置还在内存里。彻底退干净再开灰色问题基本就没了。