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

1. 升级 IDEA 2026.1 后 AI Assistant 变灰的真实场景

IDEA 2026.1 把 AI Assistant 的 Agents 面板做了一次比较大的改版，很多人在升级之后第一反应是「功能被砍了」：打开 AI Chat，Agents 列表里 Claude Code、Codex 之类的条目全是灰色，点不动，鼠标悬停也没有任何提示。我这边升级当天也遇到了同样的情况，一开始以为是插件没装，重装 AI Assistant 插件、清缓存、Invalidate Caches 全试了一遍，灰色依旧。

后来把日志翻出来看才明白，2026.1 的 AI Assistant 不再内置 Claude Code 的运行时，它改成通过 ACP（Agent 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.cmd（Windows）或npx（macOS/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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。它的好处是你不用在每台机器、每个工具里分别配不同厂商的 Key，Claude Code、Coding Plan、控制台都走同一套凭证。

具体操作上，先去控制台建一个 API Key：

  • 控制台入口：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite
  • API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite

建好 Key 之后先别急着写进acp.json，我们先用命令行验证通道是通的，这样能把「通道问题」和「IDEA 配置问题」分开排查。验证命令后面第 4 节会给。

如果你只是想先确认模型能不能调通，不折腾本地 agent，可以直接用模型对话页面试：

  • 模型对话：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite

3. 可复制配置：npm 安装与 acp.json 骨架

3.1 全局安装 claude-code-acp 并校验版本

先装 ACP 适配器。它是 Zed 那边维护的，作用是把 Claude Code 包装成符合 ACP 协议的 agent server，IDEA 才能通过协议跟它对话。

# 全局安装 claude-code-acp npm install -g @zed-industries/claude-code-acp # 查看全局包列表，确认装上了 npm list -g --depth=0

正常输出里应该能看到类似这样一行：

+-- @zed-industries/claude-code-acp@0.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.cmd，macOS 和 Linux 写npx。这是最容易错的一处，Windows 写npx有时能跑有时不能，写npx.cmd最稳。

args就是包名，让 npx 去拉起这个包。注意这里不需要写-y，IDEA 拉起时是非交互的，加了反而可能出问题。

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 "你的Key"，macOS/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_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite

5. 本篇常见错排查

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如果没设成bypassPermissions，agent 每次读写文件都会等确认，IDEA 侧看起来像卡死。本地开发可以设 bypass，但生产目录慎用。想更安全可以改成默认模式，接受每次弹窗确认。

5.5 重启后引擎列表里没有 Claude Code

确认agent_servers的 key 名字就是Claude Code，IDEA 是拿这个 key 当显示名的。名字写错（比如写成claude-code）列表里就不会出现对应条目。

6. 长期编码场景的通道收口

如果你只是偶尔用一下 AI Assistant，上面这套配完就够了。但如果你是长期在 IDEA 里跑 Claude Code 做重构、写测试、跑 agent 任务，建议把通道收口这件事做彻底一点。

我现在的做法是：本地所有 AI 编码工具——IDEA 里的 Claude Code、命令行的 Claude Code、以及一些自动化脚本——全部指向同一个 TaoToken base URL，Key 用同一个。这样换模型、看用量、排查问题都只在一个地方。Coding Plan 页面可以看长期编码场景的用量和额度：

  • Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite

接入文档里有各语言 SDK 和不同工具的配置示例，acp.json里那两个环境变量就是从文档里对出来的：

  • 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite

Claude Code 相关的接入细节，文档里也有单独一节：

  • Claude Code 接入：https://taotoken.net/doc/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode-anthropic&utm_campaign=rewrite

最后留一个我踩过的坑：acp.json改完之后，IDEA 有时候不会自动重载，必须完全退出再启动，光点 Restart 不够。尤其是 Windows 上，托盘里还留着进程的时候，重启只是开了个新窗口，旧配置还在内存里。彻底退干净再开，灰色问题基本就没了。