🍏 macOS 平台

💡 快速说明

这篇是 Codex 在 macOS 下的手动安装教程，适合想自己掌握安装、配置和排错过程的用户。
如果你想少折腾、尽快跑通，建议先看 《一键配置版》。

🍏 macOS 命令行教程

先装 Node.js 和 Codex
再配置 API 并完成首次启动

如果你是第一次接触 Codex，按“准备环境 → 安装 Codex → 写入 API 配置 → 启动测试”的顺序走就行。 整篇只保留真正会用到的步骤，尽量让新手能照着做，熟手也能快速翻到关键命令。

手动安装新手可跟做熟手可速查含排错

先记住主流程

安装 Node.js → 安装 Codex CLI → 写入 API 地址和密钥 → 启动并发一条测试消息

先把这条主流程跑通，再回来看细节和 FAQ，会更轻松。

0. 开始前先确认

🖥️ 你能打开终端

macOS 自带“终端”就可以，iTerm2 也可以，不需要额外准备复杂工具。

🔑 你已经准备好 API Key

没有的话，先去看 创建／修改令牌，把密钥准备好再回来。

🧭 本页是手动配置

本页命令统一使用 https://api.aicy.pro/v1。如果你走的是一键配置向导，就按向导文档填写，不要混着抄。

🐚 默认按 zsh 说明

macOS 现在大多数情况默认是 zsh。如果你用的是 bash，下方也给了对应写法。

1. 安装 Node.js

方法一：Homebrew（推荐）

如果你已经装了 Homebrew，直接执行：

brew update
brew install node

方法二：官网下载

1. 打开 Node.js 官网
2. 下载适合 macOS 的 LTS 版本
3. 打开下载好的 .pkg 文件
4. 按安装向导完成安装

验证是否安装成功

node -v
npm -v

能看到版本号就说明可以继续下一步。

小提示

用 Homebrew 安装 Node.js 时，一般不要给 brew 命令额外加 sudo。

2. 安装 Codex CLI

在终端执行：

npm install -g @openai/codex

如果当前环境提示权限不足，再尝试：

sudo npm install -g @openai/codex

验证 Codex 是否已安装到命令行

command -v codex

如果能看到类似 /usr/local/bin/codex、/opt/homebrew/bin/codex 这样的路径，说明命令已经可用。

小提示

如果你只关心“现在能不能用”，也可以继续做完下面的 API 配置，然后直接运行 codex 进行首次测试。

3. 配置 API 地址和密钥

本页走的是手动配置，命令里统一使用：

https://api.aicy.pro/v1

先在当前终端临时设置

export OPENAI_BASE_URL="https://api.aicy.pro/v1"
export OPENAI_API_KEY="你的API密钥"

⚠️ 注意

OPENAI_API_KEY 填的是你在爱次元控制台创建的令牌。
如果你还没有，可以先看 《创建／修改令牌》。

想让以后每次打开终端都自动生效

macOS 默认大多是 zsh，可以执行：

echo 'export OPENAI_BASE_URL="https://api.aicy.pro/v1"' >> ~/.zshrc
echo 'export OPENAI_API_KEY="你的API密钥"' >> ~/.zshrc
source ~/.zshrc

如果你用的是 bash

把上面的 ~/.zshrc 改成 ~/.bash_profile 即可：

echo 'export OPENAI_BASE_URL="https://api.aicy.pro/v1"' >> ~/.bash_profile
echo 'export OPENAI_API_KEY="你的API密钥"' >> ~/.bash_profile
source ~/.bash_profile

检查变量是否生效

echo "$OPENAI_BASE_URL"
[ -n "$OPENAI_API_KEY" ] && echo "OPENAI_API_KEY 已设置"

如果第一行输出 https://api.aicy.pro/v1，第二行显示 OPENAI_API_KEY 已设置，说明配置已经生效。

4. 启动 Codex 并做第一次测试

新开一个终端窗口，或者继续在当前终端执行：

codex

进入后，先发一条最简单的测试消息，例如：

你好，简单介绍一下你自己。

怎么判断已经成功

只要 Codex 能正常启动，并且你能 发出一条消息并收到返回，通常就说明安装、API 配置和基础使用都已经跑通了。

❓ 常见问题

1. 提示 command not found

通常是 codex 没有进入 PATH，或者当前终端还没刷新。

可以按这个顺序检查：

command -v codex
npm config get prefix
echo "$PATH"

如果刚安装完，最简单的处理方式通常是：关闭终端，重新打开，再执行 codex。

2. 安装时提示权限不足

先确认是不是 npm install -g @openai/codex 这一步报错。

如果是，再尝试：

sudo npm install -g @openai/codex

如果你不想长期依赖 sudo，也可以后续再整理 npm 全局安装目录；但对大多数新手来说，先把流程跑通更重要。

3. API 连接失败或启动后不能用

先检查这 3 项最容易出错的地方：

1. OPENAI_BASE_URL 是否写成了 https://api.aicy.pro/v1
2. OPENAI_API_KEY 是否复制完整
3. 你是不是把“一键配置版”的地址写法和本页的手动配置写法混用了

可以重新执行：

echo "$OPENAI_BASE_URL"
[ -n "$OPENAI_API_KEY" ] && echo "OPENAI_API_KEY 已设置"

如果还是不行，建议带上报错截图联系人工支持。

4. Node.js 版本太低怎么办

先看当前版本：

node -v

如果版本太低，最省事的做法通常是重新安装最新的 LTS 版本，或者用 Homebrew 更新：

brew update
brew upgrade node

🔗 下一步看什么

你已经装好 Codex，接下来建议补这几篇

如果你还没准备 Key，就先去创建令牌；如果你想快速完成配置或想核对最新地址，也可以直接跳到下面几篇继续看。

一键配置版创建／修改令牌API 基础地址联系客服