在 JetBrains IDEA 中接入本机 Codex 和 Claude Code

本文介绍如何通过 ACP 适配器，将电脑上已安装的 Codex CLI 和 Claude Code 接入 IDEA 的 AI Chat 面板。

本文面向 macOS 上的 IntelliJ IDEA，示例使用 macOS 路径。请按下文步骤在自己的环境中验证；其他系统需要调整路径，并确认对应 IDE 和插件支持 ACP。

1. 工作原理与准备条件

调用关系如下：

IDEA AI Chat -> ACP 适配器 -> 本机 Codex / Claude Code -> 模型服务

普通的 codex 和 claude 命令不能直接作为本示例的 ACP 启动入口，需要先安装适配器。

准备条件：

• IDEA 已启用 AI Assistant，AI Chat 右上角菜单中有 Add Custom Agent。
• 本机已安装 Codex CLI 和 Claude Code，并且能够正常使用。
• 已安装 Node.js 和 npm，Node.js 版本满足所安装适配器的要求。可先通过 npm view @agentclientprotocol/claude-agent-acp@latest engines --registry=https://registry.npmjs.org/ 查看 Claude 适配器声明的版本要求。
• 能访问 npm registry，下载适配器及其依赖。

使用 ACP Agent 不要求 JetBrains AI 服务订阅，但仍需具备对应模型服务的账号或 API 访问权限。“本机”指工具在电脑上运行，模型请求通常仍发送到云端服务。

2. 确认本机路径和登录状态

在 IDEA 的 Terminal 中执行：

command -v codex
command -v claude
command -v node
command -v npm
node --version

记录前三条输出。例如：

/usr/local/bin/codex
/Users/YOUR_USERNAME/.local/bin/claude
/usr/local/bin/node

如果通过 Apple Silicon Mac 的 Homebrew 安装，相关路径也可能在 /opt/homebrew/bin；通过 nvm 安装的 Node.js 则可能位于用户目录。

分别启动两个 CLI，发送简单消息，确认能正常回复后退出：

codex

claude

若尚未登录，先按 CLI 的提示完成认证，再配置 IDEA。

3. 安装 ACP 适配器

执行下面的命令，将两个适配器安装到用户目录，不需要 sudo：

npm install --prefix "$HOME/.local/share/jetbrains-acp" \
  @agentclientprotocol/codex-acp@latest \
  @agentclientprotocol/claude-agent-acp@latest \
  --registry=https://registry.npmjs.org/ \
  --cache "$HOME/.cache/jetbrains-acp-npm"

这里使用独立安装目录和 npm 缓存，便于管理，也能减少已有缓存对安装的影响。@latest 会安装执行时的发布版本，不同时间安装的版本可能不同。

如果仍出现 express-5.3.0.tgz 的 404，先停在这里。 这是依赖下载问题，后续 JSON 配置无法解决它，请先参考本文的故障处理部分。

检查安装结果：

"$HOME/.local/share/jetbrains-acp/node_modules/.bin/codex-acp" --version
"$HOME/.local/share/jetbrains-acp/node_modules/.bin/claude-agent-acp" --version

两条命令均应输出版本号。如果安装或版本检查失败，先参考本文的故障处理部分。

还可以检查 Claude 适配器是否能调用本机 Claude Code。将下面的路径改为 command -v claude 的实际输出后执行：

CLAUDE_CODE_EXECUTABLE=/Users/YOUR_USERNAME/.local/bin/claude \
  "$HOME/.local/share/jetbrains-acp/node_modules/.bin/claude-agent-acp" \
  --cli --version

这条命令检查本机 CLI 的版本输出；登录和模型连接仍需通过实际聊天验证。

4. 配置 IDEA 的 acp.json

在 AI Chat 右上角菜单 -> Add Custom Agent 中打开配置文件：

~/.jetbrains/acp.json

如果文件中已有其他 Agent，将下面的两个条目合并到已有的 agent_servers 中，保留原有配置。如果文件尚无 Agent，可使用完整示例：

{
  "default_mcp_settings": {
    "use_custom_mcp": true,
    "use_idea_mcp": false
  },
  "agent_servers": {
    "Local Codex": {
      "command": "/Users/YOUR_USERNAME/.local/share/jetbrains-acp/node_modules/.bin/codex-acp",
      "args": [],
      "env": {
        "PATH": "/Users/YOUR_USERNAME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
        "CODEX_PATH": "/usr/local/bin/codex"
      }
    },
    "Local Claude Code": {
      "command": "/Users/YOUR_USERNAME/.local/share/jetbrains-acp/node_modules/.bin/claude-agent-acp",
      "args": [],
      "env": {
        "PATH": "/Users/YOUR_USERNAME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
        "CLAUDE_CODE_EXECUTABLE": "/Users/YOUR_USERNAME/.local/bin/claude"
      }
    }
  }
}

保存前完成以下替换：

1. 将所有 YOUR_USERNAME 替换为自己的 macOS 用户名。如果主目录不是 /Users/用户名，按实际主目录修改路径。
2. 将 CODEX_PATH 改为 command -v codex 的输出。
3. 将 CLAUDE_CODE_EXECUTABLE 改为 command -v claude 的输出。
4. 确保两个 PATH 都包含 command -v node 输出路径的父目录。例如 Node.js 位于 /Users/用户名/.nvm/versions/node/v24.x.x/bin/node，就在两个 PATH 的开头加入对应的 bin 目录。

JSON 中请使用绝对路径，不要把 ~、$HOME 或 $(command -v codex) 当作会自动展开的路径。

字段说明：

字段	作用
Local Codex / Local Claude Code	AI Chat 中显示的名称，可以修改
command	ACP 适配器的可执行文件路径
args	适配器启动参数，本示例无需额外参数
PATH	让 IDEA 启动的进程能找到 Node.js 及常用命令
CODEX_PATH	指定适配器调用本机的 Codex CLI
CLAUDE_CODE_EXECUTABLE	指定适配器调用本机的 Claude Code
use_custom_mcp	向 Agent 提供 IDEA 中已配置的自定义 MCP 服务
use_idea_mcp	向 Agent 提供 IDEA 内置 MCP 服务，本示例先关闭

若需要 Agent 使用 IDEA 内置 MCP 工具，可将 use_idea_mcp 改为 true。

5. 验证聊天面板

保存配置后：

1. 在 IDEA 中打开一个项目。
2. 新建 AI Chat，在 Agent 下拉菜单选择 Local Codex 或 Local Claude Code。
3. 发送测试消息：查看当前项目目录，并简要介绍项目结构，先不要修改文件。
4. 确认 Agent 能读取项目并正常回复。

两个 Agent 都测试一次。如果下拉菜单中没有出现新增条目，检查 JSON 格式并重启 IDEA。

6. 本地配置、登录和代理

在同一系统用户下运行时，通常可以复用 CLI 保存的配置和登录凭据。Claude ACP 适配器会读取用户、项目和本地层级的 Claude 设置。初次启动仍可能提示认证，按面板提示完成即可。

如果平时仅在 .zshrc 中通过 export 设置代理、API 地址或密钥，从 macOS 图形界面启动的 IDEA 不一定继承这些变量。应将实际需要的环境变量添加到对应 Agent 的 env 中。例如使用本机 HTTP 代理时，可以根据实际代理地址添加：

"HTTPS_PROXY": "http://127.0.0.1:7890",
"HTTP_PROXY": "http://127.0.0.1:7890"

代理端口必须按自己的环境填写。不使用代理时无需添加。分享配置时应移除个人 API 密钥、令牌等凭据。

7. 常见问题

安装时出现 npm 404

例如：

npm error 404 Not Found
https://registry.npmjs.org/express/-/express-5.3.0.tgz

这是依赖下载阶段的错误。即使 JSON 配置正确，适配器也无法启动。

先确认安装命令确实使用了上述独立缓存和官方 registry，再检查 npm 网络与代理。如果相同包地址持续返回 404，需要进一步核对该依赖是否可下载，以及 registry、代理或依赖发布是否异常；反复清理 IDEA 运行时不一定能解决。不要随意覆盖依赖版本绕过问题。

报找不到 node 或可执行文件

• 检查 command 是否为真实存在的绝对路径。
• 检查 CODEX_PATH 和 CLAUDE_CODE_EXECUTABLE 是否与本机命令路径一致。
• 检查 env.PATH 是否包含 Node.js 所在的 bin 目录。
• 如果更新了 nvm 的 Node.js 版本，原来的版本目录可能变化，需要同步更新 PATH。

本机 CLI 可用，但 AI Chat 无法认证或连接

检查终端与 IDEA 的环境变量是否一致，尤其是代理、API 地址和认证相关变量。确认没有通过其他系统用户或不同配置目录启动 CLI。

本机 CLI 与适配器版本不兼容

先考虑更新本机 CLI 和适配器。如果仍无法启动，可暂时删除对应的 CODEX_PATH 或 CLAUDE_CODE_EXECUTABLE，让适配器使用软件包自带的兼容 CLI 进行排查。此时调用的将不再是显式指定的本机 CLI。

需要收集日志

在 AI Chat 右上角菜单 -> Get ACP Logs 中导出日志。分享前检查并移除可能包含的聊天内容和敏感信息。

8. 参考资料

• JetBrains: ACP 与自定义 Agent 配置
• OpenAI: Codex IDE 接入
• Codex ACP: 安装与 CODEX_PATH 参数
• Claude ACP: 项目说明
• Claude ACP: CLAUDE_CODE_EXECUTABLE 参数实现