PyCharm 2026.2 智能体（Claude/Codex）集体罢工实录：从 ACP 运行时安装竞态到 npx 缓存的三层排雷指南

标签：PyCharm · AI Agent · ACP · Claude · Codex · Node.js · npx · 排错

时间：2026-08-15
环境：Windows 11 24H2 / PyCharm 2026.2.1 (Build #PY-262.9437.214) / 火绒安全
关键路径：%LOCALAPPDATA%\JetBrains\PyCharm2026.2\acp-agents

---

一、现象：大量 ACP 智能体无法初始化

2026 年 8 月，我把 PyCharm 升级到 2026.2.1 后发现 AI 聊天面板里大部分 Agent（Claude Agent、Codex、Cline 等）都无法使用，报错集中在：

无法解析 'Claude Agent' 的智能体启动配置。

图 1：多个 ACP 智能体同时报错，界面提示“智能体运行时可能已损坏”。

图 2：聚焦的 Claude Agent 启动配置解析失败，红色提示“无法解析 ‘Claude Agent’ 的智能体启动配置”。

官方提示让“清除已下载的 ACP 运行时并重启”，但重启后问题反复出现。
深入排查后，发现这其实不是单一错误，而是三层独立但先后暴露的问题。

---

二、先给一张总览图

图 3：三层故障点。第一层是 Node.js 运行时安装竞态；第二层是内置 AI Chat 的 LLM Profile 未绑定；第三层是 npx 非交互安装被 cancel。

---

三、第一层根因：ACP 运行时安装竞态（AccessDeniedException）

3.1 关键日志

打开 %LOCALAPPDATA%\JetBrains\PyCharm2026.2\log\acp\acp.log，发现 PyCharm 在反复尝试安装 Node.js 运行时：

Installing Node.js v24.13.0 ... into
  C:\Users\love\AppData\Local\JetBrains\PyCharm2026.2\acp-agents\.runtimes\node\24.13.0
Runtime validation passed in 649ms: npx --version -> 11.6.2
Failed to promote staged install ...24.13.0.incomplete -> ...24.13.0
java.nio.file.AccessDeniedException
Failed to clean up staging dir ...24.13.0.incomplete
node.exe: 另一个程序正在使用此文件，进程无法访问。

同样的模式从 8 月 14 日 18:07 重复到 20:44，死循环。

3.2 根因解释

PyCharm 2026.2 的 ACP runtime 安装逻辑大致是：

1. 下载 Node.js v24.13.0 到 .runtimes\node\24.13.0.incomplete
2. 启动 node.exe 跑 npx --version 做验证
3. 验证通过 → 把 .incomplete 目录重命名为正式目录 24.13.0

问题就出在第 3 步：PyCharm 刚启动 node.exe 验证完，子进程句柄还没释放，就立即 Files.move() 重命名整个目录，导致 node.exe 被自己占用 → AccessDeniedException。
残留进程又把 .incomplete\node.exe 锁住，后续清理也失败，于是进入无限重试。

关于杀软的误区
我一开始怀疑是 Windows Defender / ESET / 火绒在扫描时锁了 node.exe，但用户机器实际装的是 火绒安全，而且该目录不在 Defender 保护范围内。
重读日志后发现，锁定文件的是 PyCharm 自己刚启动的 node 子进程，不是杀毒软件。
所以“加杀软排除项”并不能根治这个问题。

---

四、修复第一层：手动补齐 Node.js 运行时

既然 PyCharm 自己完成不了“下载 → 验证 → 重命名”这一步，我直接帮它把解压好的 Node.js 放到正式目录，让 PyCharm 重启后认为“已安装”，跳过会失败的 promoteStagedInstall。

4.1 关闭 PyCharm 并清理残留

以管理员 PowerShell 执行：

$target="C:\Users\love\AppData\Local\JetBrains\PyCharm2026.2\acp-agents\.runtimes";
Get-Process -Name node -ErrorAction SilentlyContinue |
  Where-Object { $_.Path -like '*JetBrains\PyCharm2026.2\acp-agents*' } |
  Stop-Process -Force -ErrorAction SilentlyContinue;
if (Test-Path $target) { Remove-Item $target -Recurse -Force };
if (-not (Test-Path $target)) { Write-Host "OK: 已清理" } else { Write-Host "WARN: 目录仍存在" }

注意：执行前请保存 PyCharm 中未保存的工作。

4.2 手动安装 Node.js v24.13.0

PyCharm 2026.2 指定要 v24.13.0，必须严格对应。可以从 Node.js 官网下载 zip 包，解压到正式目录。

$version='24.13.0'
$zipUrl="https://nodejs.org/dist/v$version/node-v$version-win-x64.zip"
$zipPath="$env:TEMP\node-v$version-win-x64.zip"
$targetDir="C:\Users\love\AppData\Local\JetBrains\PyCharm2026.2\acp-agents\.runtimes\node\$version"

# 下载
Invoke-WebRequest -Uri $zipUrl -OutFile $zipPath -UseBasicParsing

# 解压到临时目录。注意：PowerShell 的 Expand-Archive 会漏掉 node_modules/npm/bin 下的部分文件，
# 导致 npx 不可用，建议用 7z 或 tar。
$tmp="$env:TEMP\node-v$version-win-x64"
if (Test-Path $tmp) { Remove-Item $tmp -Recurse -Force }
& 'D:\Scoop\apps\7zip\current\7z.exe' x -y $zipPath -o"$tmp"

# 移到 ACP 运行时目录
if (Test-Path $targetDir) { Remove-Item $targetDir -Recurse -Force }
New-Item -ItemType Directory -Path $targetDir -Force | Out-Null
Copy-Item -Path "$tmp\node-v$version-win-x64\*" -Destination $targetDir -Recurse -Force

# 验证
& "$targetDir\node.exe" --version
& "$targetDir\npx.cmd" --version

验证通过会输出：

v24.13.0
11.6.2

4.3 重启 PyCharm

手动补齐运行滞后，重启 PyCharm。此时 PyCharm 发现 24.13.0 目录已存在，会跳过下载/重命名，直接进入 Agent 包初始化。

---

五、第二层问题：内置 AI 聊天的 No available model

重启后可能会遇到另一个新报错：

java.lang.IllegalArgumentException: No available model for ij.chat.request.new-chat-on-start feature
    at com.intellij.ml.llm.core.models.LlmProfileService.getLlmProfileIdV2(LlmProfileService.kt:162)

5.1 这其实是另一个独立问题

• 它属于 JetBrains 内置 AI Assistant 聊天，不是 ACP Agent 的问题。
• 原因是 PyCharm 被配置为“启动/新建聊天时自动打开对话”，但没有把具体模型绑定给 Core features / Instant helpers。

5.2 修复方法（二选一）

方案 A：绑定模型（如果你想用内置 AI 聊天）

1. Settings → Tools → AI Assistant → Providers & API keys
2. 登录 JetBrains AI，或添加 OpenAI / Anthropic / 本地 Ollama 等 provider 的 API key
3. 在 Core features 选择一个具体模型（如 Claude / GPT / qwen 等），Instant helpers 也选择同一个模型
4. 重启验证

方案 B：关掉启动时自动打开聊天（最快）

在 Settings 里搜索 chat on start / startup，取消“启动时打开聊天”相关选项即可。

---

六、第三层问题：npx 非交互安装被取消

第一层修好后，Claude Agent 可以正常更新了，但点击 Codex 等智能体时可能继续报错：

ACP process exited unexpectedly. Exit code: 1.
npm warn Unknown env config "min-release-age"...
npm error npx canceled due to missing packages and no YES option:
  ["@agentclientprotocol/codex-acp@1.3.0"]

6.1 根因

看 %LOCALAPPDATA%\JetBrains\PyCharm2026.2\acp-agents\registry.json 里的分发方式：

• 38 个 agent 中只有 claude-acp 是 bundled: true（PyCharm 安装时已解包）
• 其余 37 个 agent 都走 distribution.npx.package，PyCharm 启动时会执行 npx @agentclientprotocol/codex-acp@1.3.0
• PyCharm 没给 npx 传 -y；而 npx 在非交互模式下如果没缓存，会直接取消安装

6.2 通用修复：让 npx 自动确认

在用户级 .npmrc 中加入 yes=true：

Add-Content -Path "$env:USERPROFILE\.npmrc" -Value "yes=true" -Encoding UTF8

也可以直接编辑 C:\Users\love\.npmrc：

registry=https://registry.npmmirror.com
yes=true

这样 npx 在首次下载任何 ACP agent 包时都会自动确认，不再卡在 no YES option。

6.3 彻底修复：预缓存全部 npx 包

如果不想每次打开新 agent 都等它联网下载，可以把剩余 npx 包一次性预缓存到 PyCharm 实际使用的缓存目录（注意不是全局 npm cache）：

$rt = "C:\Users\love\AppData\Local\JetBrains\PyCharm2026.2\acp-agents\.runtimes\node\24.13.0"
$env:npm_config_cache = "$rt\npm-cache"

# 示例：预缓存 Codex
& "$rt\npx.cmd" -y @agentclientprotocol/codex-acp@1.3.0 --version

# 同理预缓存其他非 bundled agent（从 registry.json 中提取 package 名称）

关键细节：PyCharm 启动 npx 时通过 npm_config_cache 把缓存指向 ...\.runtimes\node\24.13.0\npm-cache，所以预缓存必须落到这个目录才会命中。

完成这一步后，首次打开这些 agent 就能秒开，不再请求网络。

---

七、验证：Claude Agent 已正常更新

全部修复后，PyCharm 智能体面板显示：

智能体 claude-acp 已自动更新至 v0.66.0

并进入认证方式选择界面（JetBrains / API 密钥 / Anthropic Console）。

图 4：修复成功，Claude Agent 已自动更新至 v0.66.0，并提示选择身份验证方式。

这意味着 “无法解析智能体启动配置”的问题已经彻底解决。后续只需要按自己的情况选择认证方式（API 密钥或 JetBrains 账号）即可。

---

八、总结：三层问题与对应修复

层级	报错关键字	根因	修复
Layer 1	AccessDeniedException promoteStagedInstall	PyCharm 启动 node.exe 验证后句柄未释放就重命名目录	手动把 Node.js v24.13.0 放到 \.runtimes\node\24.13.0
Layer 2	No available model for ij.chat.request.new-chat-on-start	内置 AI Chat 启动时没有绑定模型	绑定模型给 Core features / Instant helpers，或关闭 chat-on-start
Layer 3	npx canceled due to missing packages and no YES option	PyCharm 未传 -y，npx 非交互模式下拒绝安装	.npmrc 加 yes=true，并预缓存 npx 包

几个关键认知

1. 不是杀软问题。虽然一开始很容易怀疑 Defender / 火绒 / ESET 锁了 node.exe，但日志显示锁定文件的是 PyCharm 自己刚启动的 node 子进程，属于 PyCharm 的安装竞态 bug。
2. bundled 和非 bundled 的区别。Claude Agent 是 PyCharm 安装包自带的（bundled: true），所以修好后能自动更新；Codex 等 37 个 agent 全都要走 npx 现下载。
3. 缓存目录很特别。PyCharm 运行时使用专属的 npm-cache 目录，不是用户全局 npm cache，预缓存时必须落对位置。
4. 三个报错是独立的。不要混为一谈：运行时问题修好后，后续可能还会遇到 LLM Profile 配置和 npx 下载问题，要分层定位。

---

九、如果还有问题

如果按上述步骤操作后，仍反复出现第一层 AccessDeniedException，说明这是 PyCharm 2026.2 的确定性竞态 bug（而不是偶发），建议：

1. 升级到 PyCharm 2026.2 的最新补丁版；
2. 或在 JetBrains YouTrack 提交日志，附上 acp.log 中 promoteStagedInstall + AccessDeniedException 的关键堆栈。

---

十、参考链接

1. JetBrains 官方文档 - Activate agents | AI Assistant
   https://www.jetbrains.com/help/ai-assistant/activate-agents.html
2. JetBrains - Agent Client Protocol (ACP)
   https://www.jetbrains.com/acp/
3. JetBrains Blog - ACP Agent Registry Is Live
   https://blog.jetbrains.com/ai/2026/01/acp-agent-registry/
4. JetBrains 中文文档 - JetBrains IDE 中的 AI Assistant
   https://www.jetbrains.com/zh-cn/help/pycharm/junie.html
5. What’s New in PyCharm 2026.2
   https://blog.jetbrains.com/pycharm/2026/07/what-s-new-in-pycharm-2026-2/
6. Agent Client Protocol (ACP) 协议解析（danilchenko.dev）
   https://www.danilchenko.dev/posts/agent-client-protocol
7. JetBrains Support - AI Assistant authentication / LlmProfileService 相关问题讨论
   https://intellij-support.jetbrains.com/hc/en-us/community/posts/15623292044818/comments/15700327185042
8. npm 官方文档 - npx
   https://docs.npmjs.com/cli/v11/commands/npx
9. Node.js 官方下载页
   https://nodejs.org/en/download

---

本文记录的是一次真实排错过程。如果你也遇到 PyCharm 2026.2 智能体无法使用的问题，建议先按“Layer 1 → Layer 3 → Layer 2”的顺序排查，避免把三个独立报错混为一谈。