🚀 一键配置版

💡 快速说明

这篇是 Codex 的最快接入方式。按顺序操作，一般几分钟内就能完成基础配置并启动 Codex。

⚡ Codex 快速接入教程

先跑一键配置向导
再填入 API 信息并完成首次启动

如果你不想一上来就研究不同平台、配置文件和命令细节，这篇就够用。整篇按“准备 → 运行向导 → 填 API → 启动测试”的顺序写，新手可以照着做，熟手也能快速扫到关键步骤。

一键接入新手可跟做熟手可速查少折腾

✅ 这篇适合谁

👋 第一次接触 Codex 的用户

如果你只想先把 Codex 跑起来，这篇比平台手动安装教程更省事。

🧭 希望照着做就能完成的人

这篇尽量不展开太多背景知识，只保留真正会用到的步骤和检查点。

💻 能打开终端但不想折腾细节的人

你不需要先理解全部配置文件，只要按顺序完成向导即可。

🔧 想手动安装的人

如果你更想自己掌握完整安装和配置过程，可以直接看对应平台的手动教程。

WindowsLinuxmacOS

先记住主流程

确认 Node.js 可用 → 运行 npx zcf → 在向导里选择 Codex → 填写 API 地址和密钥 → 执行 codex 测试

只要这条主线跑通，通常就说明基础接入已经完成。

📦 开始前先准备什么

1. 已安装 Node.js

建议使用 Node.js 的 LTS 稳定版。没有安装的话，先把 Node.js 装好再继续。

2. 能打开终端

Windows 用 PowerShell，macOS / Linux 用系统终端即可。

3. 稍后要准备 API Key

这篇会带你到令牌管理页面获取密钥，不需要你提前把所有配置文件准备好。

4. 先以跑通为目标

这篇只追求“先用起来”。如果你后面还想自己维护配置，再看平台手动教程即可。

小解释

npx 可以理解成“临时运行一个工具”，通常不需要你提前全局安装。

1. 运行一键配置命令

打开终端后，按你的系统执行下面的命令：

Windows

npx zcf

macOS / Linux

sudo npx zcf

小提示

如果你的 macOS / Linux 环境不需要管理员权限，也可以先直接试 npx zcf。只有在权限不足时，再改用 sudo npx zcf。

如果命令没有反应，先检查 Node.js 是否可用：

node -v
npm -v

只要能看到版本号，就可以继续下一步。

2. 在向导里选择 Codex

进入向导后，按下面顺序操作即可：

2.1 输入 s 并回车

2.2 选择 Codex 并回车

2.3 输入 1 并回车

2.4 按向导继续下一步

这里怎么理解最简单？

你可以把这一段理解成：先进入安装入口，再明确告诉向导“我要配置的是 Codex”，后面跟着提示往下走即可。

3. 准备 API 地址和密钥

向导运行到这里时，会要求你填写 API 信息。你重点看两件事就够了：

🌐 API 基础地址

这里填写：

https://api.aicy.pro

🔑 API Key 去哪里拿

到爱次元控制台的“令牌管理”里创建或复制你自己的密钥，然后回到向导里粘贴。

3.1 打开爱次元控制台，进入“令牌管理”

3.2 没有令牌就新建一个，然后复制密钥

注意

密钥只用于你自己的本地配置，不要发到群里、工单、截图公开区或其他公开位置。

4. 回到终端完成配置

把刚复制的密钥粘贴回终端，然后继续按向导完成剩余步骤：

如果这里没有明显报错，通常就说明一键配置已经基本完成。

5. 启动 Codex 并验证是否成功

建议新开一个终端窗口，然后执行：

codex

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

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

怎么判断已经成功

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

如果你想继续深入一点

一键配置适合先跑通。等你确认能正常使用后，再按需要去看 APP 教程或平台手动安装教程就行。

Codex APPWindows 手动安装Linux 手动安装macOS 手动安装

❓ 常见问题

1. 提示权限不足（Permission denied）

在 macOS / Linux 下，优先尝试：

sudo npx zcf

如果你已经用了 sudo 还是失败，先检查当前终端是否有管理员权限，再重新执行。

2. 提示 codex: command not found

这通常表示安装流程没有完整结束，或者当前终端还没刷新。

建议按下面顺序处理：

1. 重新执行一次 npx zcf
2. 关闭当前终端，再重新打开
3. 重新执行 codex

3. 密钥填了还是失败

重点检查这 3 项：

1. API 地址是否填写为 https://api.aicy.pro
2. 密钥是否复制完整，前后有没有多空格
3. 当前令牌是否已经失效；如果不确定，可以回控制台重建一个再试

4. 我想自己掌握完整安装和配置过程

那就不要继续停留在一键配置页了，直接看对应平台的手动教程会更清楚：

• [Windows 平台](/快速开始/开发工具接入/Codex/🖥️ Windows 平台)
• [Linux 平台](/快速开始/开发工具接入/Codex/🐧 Linux 平台)
• [macOS 平台](/快速开始/开发工具接入/Codex/🍏 macOS 平台)