## 前言

随着 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 官方维护的适配器：

```bash
npm 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）：

```json
{
  "agent_servers": {
    "Claude Code (Custom)": {
      "command": "/bin/zsh",
      "args": [
        "-c",
        "pkill -f 'npx.*@zed-industries/claude-code-acp' || true; fnm exec -- npx @zed-industries/claude-code-acp"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "your-custom-api-key-here",
        "ANTHROPIC_BASE_URL": "https://your-custom-api-url.com/v1"
      }
    }
  }
}
```

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

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

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`）。
*   建议先在终端手动测试连接：
    ```bash
    ANTHROPIC_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 官方文档](https://www.jetbrains.com/help/ai-assistant/acp.html)
*   [Zed Claude Code ACP Adapter (GitHub)](https://github.com/zed-industries/claude-code-acp)
*   [Claude Code 官方文档](https://code.claude.com/docs)


【ACP】WebStorm + Claude Code

### 编程指南

- [AI协同编程指南](https://vibercoding.zxiaoruan.cn/vibe-coding/欢迎.html)

### 编程工具

- [AI编程工具汇总对比](https://rysonai.com)