在 IntelliJ IDEA 中通过 ACP 协议集成 Claude Code 的完整实践指南
JetBrains 自 2025 年底起在 AI Assistant 插件中正式引入对 Agent Client Protocol（ACP） 的原生支持，标志着 IDE 级 AI 集成进入标准化新阶段。该能力允许开发者将任意兼容 ACP 的外部 AI Agent（如 Claude Code、Gemini CLI 或 Docker cagent）无缝接入 IntelliJ IDEA、PyCharm 等 IDE，无需依赖定制插件或 Web UI 中转。
什么是 ACP？
ACP 是一种基于 JSON-RPC 2.0 的开放通信协议，由 Zed Industries 主导设计，旨在统一 AI Agent 与代码编辑器之间的交互方式。其核心目标是解耦：IDE 作为客户端（Client），Agent 作为独立服务端（Server），双方仅需遵循同一消息规范即可互通。这类似于 LSP（Language Server Protocol）之于语言功能，但聚焦于 AI 智能体的上下文感知、工具调用与任务执行能力。
为什么 ACP 改变了开发体验？
传统方式下，每个 AI 工具需为不同 IDE 单独开发适配层——Claude Code 要写 IDEA 插件，Cursor 要做 VS Code 扩展，维护成本高且更新滞后。ACP 将适配逻辑下沉至 Agent 侧：只要 Agent 实现 ACP Server 接口，它便天然兼容所有支持 ACP 的 IDE；反之亦然。这种"一次实现，多端可用"的范式显著提升了生态互操作性。
当前主流支持情况
- IDE 端：IntelliJ Platform（2024.2+）、Zed 编辑器、VS Code（通过扩展）
- Agent 端：Claude Code（via
@zed-industries/claude-code-acp）、Google Gemini CLI、Docker cagent、Kimi CLI、Qoder CLI - 基础设施：Docker Desktop 自 2025.11 起内置 cagent 运行时，并启用 ACP 接口，支持容器内托管 AI Agent 服务
底层通信模型
ACP 使用标准 stdin/stdout 流进行进程间通信，Agent 启动后作为一个长期运行的 JSON-RPC Server 进程，IDE 通过本地管道与其交换结构化请求与响应。该设计确保 Agent 完全独立于 IDE 生命周期，便于调试、版本管理及资源隔离。
前置准备
- IDE 版本：IntelliJ IDEA 2024.2 至 2025.3.x（推荐使用 2025.2 或更高构建）
- 插件状态：已安装并启用 JetBrains AI Assistant 插件（v2025.12+）
- 运行时环境：Node.js 18+ 与 pnpm（或 npm/yarn）已全局配置
- Claude Code：本地可执行命令
claude-code已通过官方方式安装并验证可用
集成步骤详解
1. 启用 ACP 配置界面
打开 AI Assistant 面板（快捷键 Ctrl+Shift+X 或点击右下角图标），点击右上角模型选择器 → 选择 "配置智能体服务器"，IDE 将自动生成并打开项目根目录下的 acp.json 文件。
2. 安装 ACP 适配器
执行以下命令安装 Zed 提供的官方桥接器：
pnpm add -g @zed-industries/claude-code-acp安装完成后，可通过 which claude-code-acp 确认二进制路径（例如：/Users/alex/.local/share/pnpm/claude-code-acp）。
3. 编写 acp.json 配置
在 acp.json 中定义 Agent Server 实例。示例配置如下（支持多 Agent 并存）：
{
"agent_servers": {
"Claude-Task": {
"command": "/Users/alex/.local/share/pnpm/claude-code-acp",
"args": ["--model", "claude-4.5-sonnet"],
"env": {
"CLAUDE_API_KEY": "${env.CLAUDE_API_KEY}",
"HTTP_PROXY": "${env.HTTP_PROXY}"
}
},
"Gemini-Pro": {
"command": "gemini-acp",
"args": ["--model", "gemini-2.0-flash"]
}
}
}注意：env 字段支持变量注入，可用于安全传递敏感凭据；args 可覆盖默认模型或启用调试模式。
功能特性对比
| 能力维度 | ACP 集成（Claude Code） | 内置 JetBrains Claude 插件 |
|---|---|---|
| MCP（Model Context Protocol）工具链 | ✅ 全面支持文件读写、Git 操作、Shell 执行、自定义 HTTP API 调用 | ❌ 仅限有限 IDE 内部 API，不支持本地系统级工具 |
| 执行模式 | ✅ 原生 Plan/Act 分阶段工作流，适合复杂重构或跨文件任务 | ⚠️ 以对话轮次为主，缺乏显式任务规划层 |
| 模型切换自由度 | ✅ 支持任意 Claude 官方模型 + 第三方中转服务（如 OneAPI、FastGPT） | ⚠️ 绑定插件预设模型列表，扩展需修改源码 |
| 部署灵活性 | ✅ Agent 可运行于容器、远程服务器或本地沙箱 | ❌ 强依赖 JetBrains 云服务或本地插件进程 |
常见问题排查
- "Command not found" 错误：检查
command路径是否绝对且可执行；若使用相对路径，请确保已加入$PATH；也可改用sh -c "exec /full/path/claude-code-acp"包装 - Agent 启动后无响应：在终端手动运行配置命令，确认输出是否含
ACP server listening on stdin；检查 IDEA 日志（Help → Show Log in Finder）中是否有 JSON-RPC 解析错误 - MCP 工具未生效：确认
claude-code本身已启用对应 MCP 插件（如fs-mcp,git-mcp），ACP 适配器会自动透传其能力
未来演进方向
ACP 协议目前处于活跃迭代期，社区关注的重点包括：
– JetBrains 正在开发 per-project 级别的 .acp.json 支持，实现工程粒度的 Agent 配置隔离；
– Cursor、Windsurf 等商业 AI IDE 已宣布将在 Q2 2026 发布 ACP Server 实现；
– 开源社区正推动 MCP 工具注册中心（MCP Hub），支持一键发现与安装跨平台工具包。
