前言

随着 JetBrains 在 2025.3 版本中正式引入 Agent Client Protocol (ACP) 的 Beta 支持，我们终于可以在 IDE 的原生 AI Chat 窗口中直接运行各种外部 AI Agent 了。

Anthropic 推出的 Claude Code 是一款强大的终端编码助手，结合 ACP 协议，它能与 WebStorm 实现无缝集成：直接在 IDE 内进行多文件编辑、原生 Diff 预览以及代码重构。

但在实际配置过程中，很多开发者会遇到两个棘手问题：

1. 使用 fnm (Fast Node Manager) 管理 Node 版本时，IDE 无法找到正确的 npx 路径。
2. 需要连接自定义的 API 地址（如 LiteLLM、Bedrock 或其它中转服务），而不是官方默认端点。

本文将提供一份经过实测的完整配置方案，帮你完美避坑。

---

🛠 前提条件

在开始之前，请确保你的开发环境满足以下要求：

• IDE 版本：WebStorm 2025.3 或更高版本。
• 插件要求：已启用官方 AI Assistant 插件。
• 基础工具：
  • 已安装 Claude Code CLI（建议：npm install -g @anthropic-ai/claude-code）。
  • 使用 fnm 管理 Node.js 环境。
  • 终端运行 npx --version 能正常输出。

---

🚀 配置步骤

第一步：安装 ACP 适配器

我们需要一个“桥梁”将 Claude Code 转换为 IDE 能听懂的 ACP 协议。推荐使用 Zed 官方维护的适配器：

1npm install -g @zed-industries/claude-code-acp

第二步：配置 WebStorm ACP

这是最关键的一步。我们需要通过修改配置文件来告诉 IDE 如何启动 Claude Code，并注入必要的环境变量。

1. 打开 WebStorm，进入 AI Chat 工具窗口（View → Tool Windows → AI Chat）。
2. 点击窗口右上角的 齿轮图标 ⚙️，选择 Configure ACP Agents。
3. 系统会自动打开 acp.json 配置文件：
   • macOS / Linux: ~/.jetbrains/acp.json
   • Windows: %USERPROFILE%\.jetbrains\acp.json

请将文件内容替换为以下配置（请根据实际情况修改 API Key 和 URL）：

1{
2  "agent_servers": {
3    "Claude Code (Custom)": {
4      "command": "/bin/zsh",
5      "args": [
6        "-c",
7        "pkill -f 'npx.*@zed-industries/claude-code-acp' || true; fnm exec -- npx @zed-industries/claude-code-acp"
8      ],
9      "env": {
10        "ANTHROPIC_API_KEY": "your-custom-api-key-here",
11        "ANTHROPIC_BASE_URL": "https://your-custom-api-url.com/v1"
12      }
13    }
14  }
15}

💡 配置原理解析（为什么这么写？）

这段配置看似复杂，实则解决两个核心痛点：

1. 自动清理僵尸进程 (pkill ... || true)： 每次重启 IDE 或 Agent 时，旧的进程可能依然驻留。这行命令会在启动新服务前强制清理旧的 adapter 进程，防止端口占用或内存泄漏。|| true 保证了即使没有旧进程，命令也不会报错退出。

2. 解决 fnm 路径问题 (fnm exec --)： WebStorm 启动子进程时，默认的 $PATH 可能不包含 fnm 动态注入的 Node 路径。直接写 npx 往往会报错。 使用 fnm exec -- 可以强制在当前 shell 上下文中动态加载正确的 Node 环境，彻底解决“找不到命令”的问题。

3. 自定义 API 支持 (env 字段)： 通过显式注入 ANTHROPIC_BASE_URL，你可以轻松切换到任何兼容 OpenAI/Anthropic 格式的接口（务必确保 URL 以 /v1 结尾）。

---

💻 使用方法

1. 保存 acp.json 文件。
2. 完全重启 WebStorm（确保配置重载）。
3. 打开 AI Chat 窗口。
4. 点击输入框上方的 Agent 选择下拉菜单，你应该能看到 "Claude Code (Custom)"。
5. 选中它，开始对话！尝试让它“重构当前文件”或“修复这个 Bug”，你会发现更改会直接显示在 IDE 的 Diff 视图中，体验极佳。

---

❓ 常见问题排查 (FAQ)

Q1: Agent 选项没有出现，或者启动报错怎么办？

• 查看日志：点击 AI Chat 窗口右上角齿轮 → Get ACP Logs。
• 检查 JSON：确保 JSON 格式合法（尤其是逗号和引号）。
• 全局安装：确认适配器已安装：npm ls -g @zed-industries/claude-code-acp。

Q2: 自定义 API 似乎没有生效？

• 检查 ANTHROPIC_BASE_URL 是否包含协议头（https://）和版本后缀（/v1）。
• 建议先在终端手动测试连接：

  1ANTHROPIC_API_KEY=xxx ANTHROPIC_BASE_URL=yyy npx @zed-industries/claude-code-acp

Q3: 为什么不直接使用 /bin/bash？

• 如果你是 macOS 用户，默认 Shell 通常是 zsh，且 fnm 配置通常在 ~/.zshrc 中。如果你使用 bash，请将配置中的 /bin/zsh 改为 /bin/bash。

---

🔗 参考资料

• JetBrains ACP 官方文档
• Zed Claude Code ACP Adapter (GitHub)
• Claude Code 官方文档