IntelliJ IDEA 接入 Codex 全面指南（2026.1 版本）

🚀 IntelliJ IDEA 接入 Codex 全面指南（2026.1 版本）

摘要

本文详细介绍了在IntelliJ IDEA 2026.1版本中接入Codex AI编程助手的完整指南。主要内容包括：三种接入方式（ACP协议、MCP服务器和插件方式）的对比与配置步骤，环境准备要求（系统配置、前置软件安装），以及详细的ACP协议配置流程（安装Codex CLI、启动服务、IDEA连接设置）。文章还提供了配置文件示例和常见问题解决方案，帮助开发者快速实现AI编程辅助功能，提升开发效率。

📋 目录

一、摘要与概述

1.1 版本信息

当前版本：IntelliJ IDEA 2026.1（发布日期：2026年3月26日）

核心更新：

• ✅ 内置支持 Codex、Cursor 等多种 AI 智能体
• ✅ 引入 ACP（Agent Client Protocol）协议
• ✅ 新增 ACP 注册表，一键安装 AI 智能体
• ✅ 支持 MCP（Model Context Protocol）服务器

1.2 什么是 Codex？

Codex 是一个强大的 AI 编程助手，能够：

• 🤖 自动生成代码
• 📝 解释复杂逻辑
• 🔧 重构和优化代码
• 🐛 调试和排查问题
• 📚 生成文档

1.3 接入方式对比

二、环境准备

2.1 系统要求

# IntelliJ IDEA 版本
IDEA 2026.1 或更高版本

# 操作系统
Windows 10/11
macOS 10.15+
Linux (Ubuntu 20.04+, CentOS 7+)

# 内存
建议 8GB 以上
推荐 16GB 以上

# 磁盘空间
至少 5GB 可用空间

2.2 前置软件安装

安装 Node.js（可选，用于某些 Codex 功能）

# Windows
# 下载安装包：https://nodejs.org/
# 或使用 winget
winget install OpenJS.NodeJS.LTS

# macOS
brew install node

# Linux (Ubuntu)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash –
sudo apt-get install -y nodejs

# 验证安装
node –version
npm –version

安装 uv（Python 包管理，用于某些 ACP 服务）

# Windows (PowerShell)
winget install uv
# 或
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 验证
uv –version

2.3 检查插件状态

# 确保以下插件已启用
1. AI Assistant (JetBrains AI Assistant)
2. MCP Server
3. Code With Me AI (可选)

# 检查方法
Settings → Plugins → Installed
搜索上述插件，确认已启用

三、Codex 接入方式详解

3.1 方式一：ACP 协议接入（推荐）

适用场景：IDEA 2026.1+ 版本，本地或远程 Codex

配置步骤

# 步骤 1：打开 ACP 配置面板
方法一：AI Chat 窗口 → 点击右上角齿轮图标 → Manage Agents
方法二：Settings → Tools → AI Assistant → Agents

# 步骤 2：添加自定义 ACP 服务
1. 点击 "Add ACP Agent" 按钮
2. 选择 "Custom ACP Server"
3. 填写配置信息：
– Name: Codex (Local) 或 Codex (Remote)
– Host: localhost 或远程服务器地址
– Port: 5000 (默认 Codex 端口)
– Protocol: http (本地) 或 https (远程)
– API Key: (如果需要认证)

# 步骤 3：测试连接
点击 "Test Connection" 按钮
看到 "Connection successful" 表示配置成功

配置文件示例

// ~/.idea/ai-assistant.json
{
"default_agent": "codex",
"agents": {
"codex": {
"type": "custom_acp",
"name": "Codex (Local)",
"host": "localhost",
"port": 5000,
"protocol": "http",
"api_key": "",
"enabled": true
},
"codex_remote": {
"type": "custom_acp",
"name": "Codex (Remote)",
"host": "your-server.com",
"port": 5000,
"protocol": "https",
"api_key": "your-api-key",
"enabled": false
}
}
}

3.2 方式二：MCP 服务器接入

适用场景：需要外部工具（如 VS Code、Cursor）访问 IDEA

配置步骤

# 步骤 1：启用 MCP 服务器
Settings → Plugins
搜索 "MCP Server"
确认已启用（默认已集成）

# 步骤 2：配置 MCP 服务器
Settings → Tools → MCP Server
勾选 "Enable MCP Server"
设置端口：默认 3000

# 步骤 3：配置允许列表（可选）
在 ~/.idea/mcp-servers.json 中添加：
{
"allowed_clients": [
"codex",
"cursor",
"vscode"
]
}

MCP 配置文件示例

// ~/.codex/config.json
{
"mcp_servers": {
"idea": {
"command": "mcp-idea-server",
"args": ["–port", "3000"],
"env": {
"IDEA_MCP_TOKEN": "your-token"
}
}
}
}

3.3 方式三：ACP 注册表一键安装

适用场景：使用官方或社区提供的 ACP 服务

# 步骤 1：打开 ACP 注册表
AI Chat 窗口 → 点击右上角 "+" → Browse ACP Registry

# 步骤 2：搜索 Codex
在搜索框中输入 "Codex"
选择合适的版本

# 步骤 3：安装
点击 "Install" 按钮
等待安装完成

# 步骤 4：配置
安装完成后会自动跳转到配置页面
填写必要的参数（如 API Key）

四、ACP 协议配置详细步骤

4.1 安装 Codex CLI（如果使用本地 Codex）

# 全局安装 Codex CLI
npm install -g @openai/codex

# 验证安装
codex –version

# 配置 Codex
codex config set api_key "your-api-key"
codex config set model "codex-2026"

4.2 启动 Codex 服务

# 启动本地 Codex 服务
codex serve –port 5000

# 或使用自定义配置
codex serve –port 5000 –host 0.0.0.0 –config ~/.codex/config.json

# 后台运行（Linux/macOS）
nohup codex serve –port 5000 > codex.log 2>&1 &

# Windows 后台运行
Start-Process -FilePath "codex" -ArgumentList "serve –port 5000" -WindowStyle Hidden

4.3 IDEA 中配置 ACP 连接

# 步骤 1：打开配置
Settings → Tools → AI Assistant → Agents

# 步骤 2：添加新 Agent
点击 "+" 按钮
选择 "Custom ACP Server"

# 步骤 3：填写配置
Name: Codex Local
Host: localhost
Port: 5000
Protocol: http
Timeout: 30000 (毫秒)
Max retries: 3

# 步骤 4：高级配置（可选）
在 "Advanced" 标签页：
– Enable streaming: 勾选（实时流式响应）
– Max tokens: 4096
– Temperature: 0.7
– Top p: 0.9

# 步骤 5：测试连接
点击 "Test Connection"

4.4 配置文件详解

// ~/.idea/ai-assistant-agents.json
{
"version": "1.0",
"agents": [
{
"id": "codex-local",
"name": "Codex (Local)",
"type": "custom_acp",
"enabled": true,
"default": true,
"config": {
"host": "localhost",
"port": 5000,
"protocol": "http",
"path": "/v1/chat/completions",
"timeout": 30000,
"headers": {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
"parameters": {
"model": "codex-2026",
"temperature": 0.7,
"max_tokens": 4096,
"top_p": 0.9,
"stream": true
}
},
"capabilities": {
"code_generation": true,
"code_explanation": true,
"code_refactoring": true,
"debug_assistance": true,
"documentation": true
}
}
]
}

五、MCP 服务器配置

5.1 启用 MCP 服务器

# 步骤 1：确认插件启用
Settings → Plugins
搜索 "MCP Server"
确保状态为 "Enabled"

# 步骤 2：配置 MCP 服务器
Settings → Tools → MCP Server

# 配置项：
– Enable MCP Server: ✅ 勾选
– Port: 3000 (默认)
– Allowed clients: codex, cursor, vscode
– Authentication: Token-based
– Token: your-mcp-token (自动生成或手动设置)

# 步骤 3：应用配置
Click "Apply" → "OK"

5.2 Codex 中配置 MCP 连接

// ~/.codex/config.json
{
"mcp_servers": {
"idea": {
"command": "mcp-idea-client",
"args": [
"–host", "localhost",
"–port", "3000",
"–token", "your-mcp-token"
],
"env": {
"IDEA_PROJECT_PATH": "/path/to/your/project"
}
}
},
"default_mcp_settings": {
"timeout": 30000,
"retry_count": 3
}
}

5.3 MCP 功能测试

# 在 Codex 中测试连接
codex mcp test idea

# 预期输出
✓ Connected to IDEA MCP Server
✓ Available tools: 15
✓ Project loaded: /path/to/your/project

六、常见陷阱与问题解决

6.1 连接失败问题

问题 1：Connection refused

# 症状
Test Connection 失败，提示 "Connection refused"

# 可能原因
1. Codex 服务未启动
2. 端口被占用
3. 防火墙阻止

# 解决方案
# 1. 检查 Codex 服务状态
netstat -tuln | grep 5000 # Linux/macOS
netstat -ano | findstr 5000 # Windows

# 2. 重启 Codex 服务
codex serve –port 5000

# 3. 检查防火墙
# Windows
netsh advfirewall firewall add rule name="Codex" dir=in action=allow protocol=TCP localport=5000

# Linux
sudo ufw allow 5000/tcp

问题 2：401 Unauthorized

# 症状
连接成功但返回 401 错误

# 可能原因
API Key 错误或过期

# 解决方案
# 1. 检查 API Key
cat ~/.codex/config.json | grep api_key

# 2. 更新 API Key
codex config set api_key "new-api-key"

# 3. 在 IDEA 中更新配置
Settings → Tools → AI Assistant → Agents
编辑对应 Agent，更新 API Key

6.2 ACP 配置问题

问题 3：Agent 列表为空或灰色

# 症状
AI Assistant → Agents 列表为空或全部灰色

# 可能原因
1. AI Assistant 插件未启用
2. IDEA 版本过低
3. 配置文件损坏

# 解决方案
# 1. 检查插件状态
Settings → Plugins → Installed
搜索 "AI Assistant"
确认状态为 "Enabled"

# 2. 检查 IDEA 版本
Help → About
确认版本 >= 2026.1

# 3. 重置配置
# 备份后删除配置文件
mv ~/.idea/ai-assistant.json ~/.idea/ai-assistant.json.bak
# 重启 IDEA

问题 4：自定义 ACP 服务无法添加

# 症状
点击 "Add ACP Agent" 无反应或报错

# 可能原因
IDEA Bug 或权限问题

# 解决方案
# 1. 升级到最新版本
Help → Check for Updates
升级到 2026.1.1 或更高版本

# 2. 手动创建配置文件
# 创建 ~/.idea/ai-assistant-agents.json
# 内容参考第 4.4 节

# 3. 重启 IDEA
File → Invalidate Caches → Invalidate and Restart

6.3 MCP 服务器问题

问题 5：MCP 服务器无法启动

# 症状
Settings → Tools → MCP Server 选项灰色或无法启用

# 可能原因
MCP Server 插件未安装或损坏

# 解决方案
# 1. 重新安装插件
Settings → Plugins → Installed
找到 "MCP Server"
点击 "Uninstall"
重启 IDEA
重新安装 "MCP Server"

# 2. 检查插件兼容性
Settings → Plugins → Installed
右键 "MCP Server" → "Show Details"
确认兼容版本包含当前 IDEA 版本

问题 6：外部工具无法连接 MCP

# 症状
Codex/VS Code 无法连接到 IDEA MCP Server

# 可能原因
1. 端口被防火墙阻止
2. Token 不匹配
3. 网络配置错误

# 解决方案
# 1. 检查端口监听
netstat -tuln | grep 3000

# 2. 验证 Token
cat ~/.idea/mcp-server.json | grep token

# 3. 配置防火墙
# Windows
netsh advfirewall firewall add rule name="MCP" dir=in action=allow protocol=TCP localport=3000

# Linux
sudo ufw allow 3000/tcp

# 4. 检查网络配置
# 如果使用远程连接，确保使用正确的 IP 地址
# 不要使用 localhost/127.0.0.1

6.4 性能问题

问题 7：响应慢或超时

# 症状
AI 响应非常慢或经常超时

# 可能原因
1. 网络延迟
2. 服务器资源不足
3. 配置超时时间过短

# 解决方案
# 1. 增加超时时间
Settings → Tools → AI Assistant → Agents
编辑对应 Agent
Timeout: 改为 60000 (60秒)

# 2. 优化网络
# 如果使用远程服务，考虑使用更近的服务器
# 或使用代理加速

# 3. 检查服务器资源
# 监控 CPU 和内存使用
# 必要时升级服务器配置

七、高级功能与最佳实践

7.1 多 Agent 管理

// 配置多个 Codex 实例
{
"agents": [
{
"id": "codex-dev",
"name": "Codex (Development)",
"type": "custom_acp",
"config": {
"host": "localhost",
"port": 5000,
"model": "codex-dev"
},
"tags": ["development", "testing"]
},
{
"id": "codex-prod",
"name": "Codex (Production)",
"type": "custom_acp",
"config": {
"host": "prod-server.com",
"port": 5000,
"model": "codex-prod"
},
"tags": ["production"]
}
]
}

7.2 环境变量管理

# 创建环境变量配置文件
# ~/.idea/ai-assistant.env

CODex_API_KEY=your-api-key
CODex_MODEL=codex-2026
CODex_TIMEOUT=30000
CODex_TEMPERATURE=0.7

# 在配置中引用
{
"config": {
"api_key": "${CODex_API_KEY}",
"model": "${CODex_MODEL}"
}
}

7.3 Git 工作树集成

# 利用 Git Worktree 功能
# 将不同分支交给不同的 AI Agent 处理

# 步骤 1：创建工作树
git worktree add ../feature-branch feature-branch

# 步骤 2：在不同工作树中使用不同 Agent
# 主分支：使用 Codex (Development)
# feature-branch：使用 Codex (Testing)

# 步骤 3：并行处理
# 主分支继续开发
# feature-branch 交给 AI 完成重构

7.4 自定义提示模板

// ~/.idea/ai-assistant-templates.json
{
"templates": [
{
"id": "code_review",
"name": "Code Review",
"prompt": "Please review the following code and provide suggestions for improvement:\\n\\n{code}",
"context": "current_file"
},
{
"id": "generate_tests",
"name": "Generate Tests",
"prompt": "Generate comprehensive unit tests for the following code:\\n\\n{code}",
"context": "current_file"
},
{
"id": "explain_code",
"name": "Explain Code",
"prompt": "Explain the following code in detail, including its purpose and how it works:\\n\\n{code}",
"context": "selection"
}
]
}

7.5 性能优化

# 1. 调整 IDEA 内存
Help → Change Memory Settings
Set to: 4096 MB (4GB) or higher

# 2. 禁用不必要的插件
Settings → Plugins
禁用不常用的插件

# 3. 优化索引
File → Invalidate Caches → Clear File System Cache and Local History

# 4. 使用 SSD
确保项目存储在 SSD 上

八、参考资料

8.1 官方文档

• IntelliJ IDEA 2026.1 官方文档
• AI Assistant 插件文档
• MCP Server 文档
• ACP 协议规范

8.2 社区资源

• JetBrains 官方博客
• IntelliJ IDEA 论坛
• GitHub ACP 项目
• Codex 官方文档

8.3 视频教程

• IDEA 2026.1 AI 功能详解
• ACP 协议配置教程
• MCP 服务器实战

九、总结

9.1 核心要点

✅ IDEA 2026.1 引入了革命性的 AI 集成

• 通过 ACP 协议，可以轻松接入 Codex 等多种 AI 智能体
• MCP 服务器允许外部工具访问 IDEA 功能
• 新增 ACP 注册表，简化安装流程

✅ 三种接入方式

✅ 常见问题解决

• 连接失败：检查服务状态、端口、防火墙
• 配置问题：重置配置文件、升级版本
• 性能问题：优化网络、调整超时时间

9.2 最佳实践建议

# 1. 版本选择
✅ 使用 IDEA 2026.1.1 或更高版本
✅ 保持插件更新到最新版本

# 2. 配置管理
✅ 使用环境变量管理敏感信息
✅ 定期备份配置文件
✅ 为不同环境创建不同 Agent

# 3. 安全考虑
✅ 不要将 API Key 提交到版本控制
✅ 使用防火墙限制访问
✅ 定期更新 Token

# 4. 性能优化
✅ 分配足够的内存给 IDEA
✅ 使用 SSD 存储项目
✅ 禁用不必要的插件

9.3 未来展望

随着 IDEA 不断进化，AI 集成将更加深入：

• 🚀 更多 AI 模型支持
• 🚀 更智能的代码生成
• 🚀 更强大的协作功能
• 🚀 更完善的调试支持

十、附录

10.1 快捷键大全

10.2 配置文件位置

# Windows
C:\\Users\\<username>\\.idea\\ai-assistant.json
C:\\Users\\<username>\\.idea\\mcp-server.json

# macOS
~/.idea/ai-assistant.json
~/.idea/mcp-server.json

# Linux
~/.idea/ai-assistant.json
~/.idea/mcp-server.json

10.3 命令行工具

# Codex CLI 常用命令
codex serve –port 5000 # 启动服务
codex config set api_key "xxx" # 设置 API Key
codex config get api_key # 获取 API Key
codex mcp test idea # 测试 MCP 连接
codex –version # 查看版本

# IDEA 命令行
idea . # 打开当前目录项目
idea –help # 帮助信息

10.4 故障排查清单

□ 检查 IDEA 版本是否 >= 2026.1
□ 确认 AI Assistant 插件已启用
□ 验证 Codex 服务是否正常运行
□ 检查端口是否被占用
□ 确认防火墙配置正确
□ 验证 API Key 是否有效
□ 检查网络连接是否正常
□ 查看 IDEA 日志获取详细错误信息

10.5 日志文件位置

# Windows
C:\\Users\\<username>\\AppData\\Local\\JetBrains\\IntelliJIdea2026.1\\log\\idea.log

# macOS
~/Library/Logs/JetBrains/IntelliJIdea2026.1/idea.log

# Linux
~/.cache/JetBrains/IntelliJIdea2026.1/log/idea.log

🎉 结语

通过本指南，您应该能够成功在 IntelliJ IDEA 2026.1 中接入 Codex，并充分利用其强大的 AI 编程能力。记住，AI 是工具，真正的创造力来自于您！

祝您编码愉快！ 🚀