如何将Gemini CLI集成到IntelliJ IDEA？2026年ACP协议配置全教程

🎯 先用人话说明：这个集成能做什么？

想象一个场景：你在 IDEA 里疯狂写代码，突然卡壳了。以前你必须：切换到终端 → 打开 Gemini CLI → 复制代码 → 粘贴 → 等待回复 → 再切回 IDEA。现在？直接在 AI Assistant 聊天框里 @Gemini，它就能看懂你的项目、帮你改代码，甚至执行终端命令！✨

Let me explain it in plain language: what can this integration do?
Imagine you're coding furiously in IDEA and suddenly hit a wall. In the old days, you had to: switch to terminal → open Gemini CLI → copy code → paste → wait for response → switch back to IDEA.
Now? Simply @Gemini in the AI Assistant chat box – it understands your project, helps you modify code, and even runs terminal commands! ✨

这就是 Agent Client Protocol (ACP) 的魔力：让外部 AI 代理（例如 Gemini CLI）直接“住进”你的 IDE，实现无缝协作。

This is the magic of Agent Client Protocol (ACP) : it allows external AI agents (like Gemini CLI) to directly "live inside" your IDE, enabling seamless collaboration.

---

📋 前置条件（别跳过，否则容易踩坑）

📋 Prerequisites (don't skip, or you'll hit issues)

Requirement	Description	Verification Command
IntelliJ IDEA	2025.3 or later (also works with other JetBrains IDEs)	Help → About
Node.js	Version 20+ recommended; the runtime for Gemini CLI	node --version
Gemini CLI	The key component – must be installed first	gemini --version

---

🔧 四步完成集成

Step 1️⃣ 安装 Gemini CLI（如果还未安装）

npm install -g @google/gemini-cli

安装后验证：

gemini --version
# 看到版本号？恭喜，第一步完成！✅

Step 1️⃣ Install Gemini CLI (if not yet installed)

npm install -g @google/gemini-cli

Verify after installation:

gemini --version
# See a version number? Congratulations, step one is done! ✅

💡 小贴士：如果权限报错，试试加 sudo（Mac/Linux）或以管理员身份运行终端（Windows）。

💡 Tip: If you get a permission error, try adding sudo (Mac/Linux) or run the terminal as Administrator (Windows).

---

Step 2️⃣ 找到 gemini 可执行文件的“真实路径”

ACP 配置需要绝对路径，不能模糊。

🍎 macOS / 🐧 Linux 用户：

which gemini
# 示例输出：/Users/yourname/.nvm/versions/node/v22.16.0/bin/gemini

🪟 Windows 用户：

where gemini
# 示例输出：C:\Program Files\nodejs\gemini.cmd

Step 2️⃣ Find the real absolute path of the gemini executable

ACP configuration requires an absolute path – no ambiguity allowed.

🍎 macOS / 🐧 Linux users:

which gemini
# Example output: /Users/yourname/.nvm/versions/node/v22.16.0/bin/gemini

🪟 Windows users:

where gemini
# Example output: C:\Program Files\nodejs\gemini.cmd

⚠️ 重点：把此路径复制好，稍后要用。如果用 nvm，确保路径指向当前激活的 Node 版本，否则 IDEA 会无法找到文件。

⚠️ Important: Copy this path – you'll need it shortly. If you use nvm, make sure the path points to the currently active Node version, otherwise IDEA won't find the file.

---

Step 3️⃣ 配置 ACP 的“户口本” —— acp.json

JetBrains IDE 会从固定位置读取此配置文件：

Step 3️⃣ Configure the ACP registration file – acp.json

JetBrains IDE looks for this config file in a fixed location:

System	File Path
macOS / Linux	~/.jetbrains/acp.json
Windows	%USERPROFILE%\.jetbrains\acp.json

新建或编辑文件，填入以下内容（记得替换 command 里的路径）：

{
  "agent_servers": {
    "Gemini CLI": {
      "command": "/你的/实际/路径/gemini",
      "args": [
        "--experimental-acp"
      ],
      "use_idea_mcp": true,
      "use_custom_mcp": true
    }
  }
}

Create or edit the file with the following content (remember to replace the path in command):

{
  "agent_servers": {
    "Gemini CLI": {
      "command": "/your/actual/path/gemini",
      "args": [
        "--experimental-acp"
      ],
      "use_idea_mcp": true,
      "use_custom_mcp": true
    }
  }
}

🔍 配置项逐行解读

🔍 Configuration field breakdown

Field	Purpose	Why It Matters
"Gemini CLI"	Name displayed in IDEA	Can be any descriptive name
"command"	Absolute path to the gemini executable	Incorrect path means the agent won't start
"args"	Startup arguments	--experimental-acp is critical; without it, Gemini runs in normal terminal mode
"use_idea_mcp": true	Enable access to IDEA's built-in MCP services	✨ Core feature: allows Gemini to read project structure, open files, etc.
"use_custom_mcp": true	Enable custom MCP services	Extensibility – e.g., connecting to databases or external APIs

🤔 深度思考：为什么叫 experimental？
因为 ACP 协议仍在演进中，未来可能有破坏性变更。建议先在小项目试用，不要直接用于重构核心模块（血泪教训 ⚠️）。

🤔 Deep thought: Why is it called experimental?
Because the ACP protocol is still evolving and may have breaking changes in the future. It's recommended to test it on small projects first and avoid using it to refactor core modules (lesson learned the hard way ⚠️).

---

Step 4️⃣ 重启 IDEA，召唤 Gemini！

1. 重启 IntelliJ IDEA（配置生效的必要步骤）
2. 打开 AI Assistant 面板（通常在右侧工具栏）
3. 找到 Agent 选择器（下拉菜单或 ⋯ 更多按钮）
4. 选择 “Gemini CLI”

Step 4️⃣ Restart IDEA and invoke Gemini!

1. Restart IntelliJ IDEA (required for the config to take effect)
2. Open the AI Assistant panel (usually in the right toolbar)
3. Find the Agent selector (dropdown or ⋯ more button)
4. Select “Gemini CLI”

🎉 看到聊天框中出现 Gemini CLI 标识？恭喜，集成成功！

🎉 See the Gemini CLI badge in the chat box? Congratulations, the integration is successful!

---

📦 附：一键配置脚本（懒人福利）

macOS / Linux 用户，复制粘贴以下命令，自动创建 acp.json（记得先确认路径正确）：

mkdir -p ~/.jetbrains && cat > ~/.jetbrains/acp.json << 'EOF'
{
  "agent_servers": {
    "Gemini CLI": {
      "command": "$(which gemini)",
      "args": ["--experimental-acp"],
      "use_idea_mcp": true,
      "use_custom_mcp": true
    }
  }
}
EOF

📦 Appendix: One‑click configuration script (lazy-friendly)

macOS / Linux users, copy and paste this command to automatically create acp.json (make sure the path is correct first):

mkdir -p ~/.jetbrains && cat > ~/.jetbrains/acp.json << 'EOF'
{
  "agent_servers": {
    "Gemini CLI": {
      "command": "$(which gemini)",
      "args": ["--experimental-acp"],
      "use_idea_mcp": true,
      "use_custom_mcp": true
    }
  }
}
EOF

---

总结

通过以上四个步骤，你可以将 Gemini CLI 深度集成到 JetBrains IDE 中，借助 ACP 协议实现 AI 助手与 IDE 的双向协作。从项目结构感知到终端命令执行，这一集成显著提升了开发效率。建议在非生产项目上先进行体验，并持续关注 ACP 协议的演进。

Summary

With the four steps above, you can deeply integrate Gemini CLI into JetBrains IDEs via the ACP protocol, enabling bidirectional collaboration between the AI assistant and the IDE. From project structure awareness to terminal command execution, this integration significantly boosts development productivity. We recommend trying it on non‑production projects first and staying updated on the evolution of the ACP protocol.

常见问题（FAQ）

集成Gemini CLI到IntelliJ IDEA需要哪些前置条件？

需要IntelliJ IDEA 2025.3或更新版本、Node.js 20+、以及已安装的Gemini CLI（通过npm install -g @google/gemini-cli）。

如何配置acp.json文件来注册Gemini CLI？

新建~/.jetbrains/acp.json（Windows为%USERPROFILE%.jetbrains\acp.json），填入包含gemini绝对路径的JSON，并添加--experimental-acp参数。

集成后如何在IDEA中使用Gemini CLI？

重启IDEA后，在AI Assistant聊天框中输入@Gemini，即可直接与项目交互，如修改代码或执行终端命令。