📌 写在前面

之前分享过使用CC GUI插件用本地codex帮助编码了，今天分享的是配置第三方供应商到AI Assistant，让看起来更是idea高级AI用户！

JetBrains AI Assistant 内置了强大的代码生成能力，但官方订阅需要付费，且国内访问有时不稳定。而 Codex CLI 是 OpenAI 开源的本地智能体（Agent），可以接入任意兼容 OpenAI 接口的 API。如果我们能把 Codex CLI “伪装”成 AI Assistant 的官方智能体，就能在 IDE 里享受流畅的 AI 编码体验，同时数据不出本地，成本可控。

本文将手把手教你：

通过 Homebrew 安装 Node.js 与 Codex CLI（以及 ACP 适配器）

在 IntelliJ IDEA 中通过 ACP 协议接入 Codex

使用第三方中转 API（解决网络与密钥问题）

实践：让 Codex 读懂项目并生成完整业务代码

环境：macOS + IntelliJ IDEA 2026.1.4（支持 AI Assistant 插件）

🧩 第一步：通过 Homebrew 安装 Node.js 与 Codex CLI

Codex CLI 依赖 Node.js（版本 ≥ 22）。macOS 用户推荐使用 Homebrew 安装。

1.1 更新 Homebrew 并安装 Node.js

brew update
brew install node@22
# 如果 node@22 不可用，也可以直接安装最新版
brew install node

安装完成后，确保 Node 版本符合要求：

node -v   # 应显示 v22.x 或更高
npm -v    # 检查 npm 是否可用

1.2 通过 Homebrew 安装 Codex CLI（官方推荐）

Codex CLI 官方提供了 Homebrew 安装方式，这是 macOS 上最便捷的途径：

brew install codex

安装完成后，验证 CLI 是否可用：

codex --version
# 应显示版本号，例如 0.1.0 或类似

1.3 通过 npm 安装 ACP 适配器（关键桥接组件）

Codex CLI 本身不直接支持 IDEA 的 ACP 协议，我们需要安装由 Zed Industries 维护的
codex-acp
适配器，它负责将 ACP 协议转换为 Codex 能理解的命令。

npm install -g @zed-industries/codex-acp

验证安装：

codex-acp --help   # 应显示帮助信息

1.4 获取

codex-acp
的绝对路径
后续在 IDEA 配置中需要用到绝对路径，先记录下来：

which codex-acp
# 通常输出 /usr/local/bin/codex-acp 或 /opt/homebrew/bin/codex-acp

小贴士：如果 codex-acp命令找不到，可能是因为 npm 全局 bin 目录未加入 PATH。可以执行 npm root -g找到全局安装目录，然后将 bin子目录加入 ~/.zshrc或 ~/.bash_profile。

🔑 第二步：配置第三方中转 API

由于国内调用 OpenAI 官方接口受限，我们使用第三方中转（如
http://new.zhushouzl.cloud/v1
）。Codex 支持通过 -c参数动态指定模型提供商的配置。

为了避免每次启动都输入长串参数，我们可以在
~/.codex/config.toml中预设（可选），但更方便的是直接在 IDEA 的配置文件中传递参数。

codex-acp -c model_providers.custom.base_url=http://你的中转地址/v1 \
          -c model_providers.custom.wire_api=responses \
          -c model_providers.custom.env_key=OPENAI_API_KEY

🛠️ 第三步：在 IDEA 中配置 ACP 智能体（Agent）

关键点：IDEA 不是通过普通的 mcp.json来识别本地 Agent，而是通过专用的 acp.json文件。而且根键必须是 agent_servers，而不是 mcpServers。

3.1 安装辅助插件（推荐）

为了让配置更简单，建议先在 IDEA 中安装
AI Assistant Providers / Sessions
插件（在 Marketplace 搜索）。这个插件增加了对第三方 Provider 的 UI 支持，但即使不装，我们也能通过 ACP 方式接入。

安装步骤：

打开
Settings → Plugins → Marketplace

搜索
AI Assistant Providers

安装并重启 IDEA

3.2 创建/编辑

acp.json
打开 AI Chat 窗口（
Tools → AI Assistant → Open AI Chat
）。

点击右上角的 …或齿轮图标，选择 配置ACP智能体（或 Add Custom Agent）。

IDEA 会自动打开一个位于用户配置目录（如
~/Library/Application Support/JetBrains/IntelliJIdea2026.1.4/options/acp.json
）的文件。

将以下内容粘贴进去，务必根据你的实际情况修改。

{
  "default_mcp_settings": {},
  "agent_servers": {
    "Codex (Local)": {
      "command": "/Users/zwmac/.nvm/versions/node/v22.2.0/bin/codex-acp",
      "args": [
        "-c",
        "model_providers.custom.base_url=你的中转地址url/v1",
        "-c",
        "model_providers.custom.wire_api=responses",
        "-c",
        "model_providers.custom.env_key=OPENAI_API_KEY"
      ],
      "env": {
        "ACP_PERMISSION_MODE": "bypassPermissions",
        "OPENAI_API_KEY": "你的中转供应商给的key"
      },
      "use_idea_mcp": true,
      "use_custom_mcp": true
    }
  }
}

⚠️ 配置要点说明：

字段	说明	示例
command	codex-acp的绝对路径，用 which codex-acp获取	/Users/xxx/.nvm/versions/node/v22.2.0/bin/codex-acp
base_url	你的第三方中转 API 地址（以 /v1结尾）	http://your-proxy.com/v1
wire_api	API 协议类型，responses是 OpenAI 最新统一接口，如中转不支持可改chat	responses/chat
env_key	指定从环境变量读取 API Key 的变量名	OPENAI_API_KEY
OPENAI_API_KEY	中转供应商提供的真实密钥	sk-xxxxx
use_idea_mcp	启用 IDEA 的 MCP 集成，让 Codex 能读取项目文件	true
default_mcp_settings	保留空对象即可	{}

3.4 重启 IDEA

保存 acp.json，完全退出 IDEA 再重新打开。

重新打开后，打开 AI Chat 窗口，在顶部的 Agent 下拉菜单中应该能看到
Codex (Local)，选择它即可。

🚀 第四步：验证与常见问题

4.1 终端测试

在终端直接运行你的完整命令，检查是否能正常启动：

bash

/Users/zwmac/.nvm/versions/node/v22.2.0/bin/codex-acp -cmodel_providers.custom.base_url=http://你的中转地址/v1 -cmodel_providers.custom.wire_api=responses -cmodel_providers.custom.env_key=OPENAI_API_KEY

如果输出类似
{“jsonrpc”:“2.0”,“error”:{…}}
说明进程可正常启动（这是正常的 ACP 协议响应）。

4.2 常见报错与解决

报错	原因	解决
Agent 下拉没有 Codex (Local)	未安装 AI Assistant Providers插件	在 Marketplace 安装该插件
command not found	IDEA 找不到 codex-acp	使用绝对路径，并确认 nvm 路径正确
LazyStandaloneCoroutine was cancelled	进程启动后崩溃	检查中转地址是否可达、API Key 是否正确
Model metadata for xxx not found	模型未在 Codex 元数据中	添加 model_aliases映射
Parse error终端输出	直接运行 ACP 服务器未收到请求	正常现象，说明进程可启动

💻 第五步：实战 —— 让 Codex 为“复读学校”项目生成新增接口

现在，我们来验证真正的编码能力。假设项目中有
RepeatSchoolController
和
RepeatSchoolVo
，我们需要实现一个新增方法。

5.1 编写提示词（Prompt）

在 AI Chat 中输入：

“实现一个新增，入参使用 RepeatSchoolVo”

Codex 会通过 MCP 自动读取项目文件（Controller、Vo、Service、Mapper），并分析同模块的其他新增方法。

5.2 Codex 自动定位与生成

从截图可以看到，Codex 自动找到了
RepeatSchoolController
的位置，并读取了相关文件。然后生成了如下 Service 实现（核心代码）：

@Override
@Transactional(rollbackFor = Exception.class)
public boolean add(RepeatSchoolVo repeatSchoolVo) {
    Assert.notNull(repeatSchoolVo, "复读学校信息不能为空");
    RepeatSchool repeatSchool = new RepeatSchool();
    BeanUtil.copyProperties(repeatSchoolVo, repeatSchool);
    repeatSchool.setId(null);
    checkExist(repeatSchool);
    checkInsert(baseMapper, repeatSchool);
    Long schoolId = repeatSchool.getId();
    insertRelation(repeatSchoolVo.getSchoolFacility(), schoolId, repeatSchoolFacilityMapper);
    insertRelation(repeatSchoolVo.getSchoolTeach(), schoolId, repeatSchoolTeachMapper);
    insertRelation(repeatSchoolVo.getSchoolClass(), schoolId, repeatSchoolClassMapper);
    insertRelation(repeatSchoolVo.getSchoolEdu(), schoolId, repeatSchoolEduMapper);
    insertRelation(repeatSchoolVo.getSchoolCharg(), schoolId, repeatSchoolChargMapper);
    insertRelation(repeatSchoolVo.getSchoolAdmiss(), schoolId, repeatSchoolAdmissMapper);
    return true;
}
private void checkExist(RepeatSchool repeatSchool) {
        LambdaQueryWrapper<RepeatSchool> queryWrapper = Wrappers.lambdaQuery();
        queryWrapper.eq(RepeatSchool::getSchoolName, repeatSchool.getSchoolName());
        queryWrapper.ne(repeatSchool.getId() != null, RepeatSchool::getId, repeatSchool.getId());
        long count = baseMapper.selectCount(queryWrapper);
        Assert.state(count == 0, "复读学校已存在");
    }


    private <T> void checkInsert(BaseMapper<T> mapper, T entity) {
        Assert.state(mapper.insert(entity) == 1, "复读学校数据保存失败");
    }
private <T extends BusinessEntity> void insertRelation(T relation, Long schoolId, BaseMapper<T> mapper) {
        if (relation == null) {
            return;
        }
        relation.setId(null);
        setSchoolId(relation, schoolId);
        checkInsert(mapper, relation);
    }

5.3 效果评价

完全贴合项目规范：使用了项目特有的 checkExist、checkInsert、insertRelation等方法。

事务正确：添加了 @Transactional。

关联表处理：自动识别了六个关联表的插入逻辑。

只读提示：代码生成后，Codex 还会给出“只读”提示，提醒你是生成的，方便审核。

5.4 优化建议

我们在配置中加入的
max_input_tokens
和
model_aliases
有效避免了模型能力限制，生成过程流畅无截断。如果后续需要实现“更新”、“分页查询”或“导出 Excel”，可以继续用类似提示词，Codex 会模仿其他 Controller 的写法。

补充内容

数据库表设计

数据表对应的实体

提示词示例

🎯 总结与心得

通过本文的配置，你将拥有一个 完全离线、无订阅、可自定义模型 的 AI 编程助手。Codex 的上下文感知能力远超普通问答，它真正理解了你的项目结构、代码风格和业务逻辑。

几点体会：

• ACP 协议是桥梁：IDEA 通过 ACP 与本地 Codex 通信，本质上就是标准 JSON-RPC，稳定可靠。

• 中转 API 选择：尽量选择支持 chat接口的中转，兼容性好；如果中转支持 responses也可用。

• 元数据警告不必害怕：通过 model_aliases可以消除，但即使不处理，多数情况下不影响生成质量。

• MCP 开启后更强大：启用 use_idea_mcp后，Codex 可以读取项目文件、运行命令，甚至执行测试，大大提升生成准确性。

最后，建议将 acp.json备份，后续升级 IDEA 或 Node 版本时，只需检查路径是否变化即可。

写在最后：技术探索的意义在于打破限制，让工具真正为开发者所用。希望这篇博文能帮你走出“AI 编程助手成本高、不可控”的困境，让你的编码效率再上一个台阶！

如果你在配置过程中遇到其他问题，欢迎在评论区留言，我会尽力解答。祝编码愉快！🎉