Codex在Mac上运行的从零教程

这篇只写 Mac。

之前写 Windows 的时候我发现，教程一旦把 Windows、Mac、Linux 都塞在一起，读起来就很累。尤其是刚接触 Codex 的朋友，本来就不熟终端，再看到一堆系统命令混在一起，很容易直接关掉。

所以这一篇就单独写 macOS。

我会按自己实际折腾的顺序来，不讲太多大概念。能复制的命令直接贴出来，哪里容易卡也顺手写上。

Codex 是干嘛的

Codex 可以理解成一个放在本地项目里的 AI 编程助手。

它不是只能聊天。你在某个项目目录里启动 Codex 后，它可以看项目文件，帮你分析目录结构、解释代码、定位报错，也可以在你确认后修改文件。

刚开始可以先把它当成这几种工具：

• 帮你读项目目录
• 帮你看项目用了什么技术
• 帮你分析报错
• 帮你改一点小功能
• 帮你写一点测试

不要一上来就让它“帮我重构整个项目”。这个范围太大，新手也不好判断它改得对不对。

我自己的习惯是：先让它看，再让它分析，最后才让它改。

安装前准备一下

Mac 上这篇只走 npm 安装。

你需要准备两个东西：

1. 终端
   Mac 自带，不用额外安装。

2. Node.js
   npm 是跟着 Node.js 一起安装的。后面安装 Codex 要用 npm。

如果你不知道自己有没有 Node.js，也没关系，下面会检查。

第一步：打开终端

按 Command + 空格，搜索：

Terminal

或者直接打开端口

打开以后，后面的命令都在这个窗口里输入。

第二步：检查 Node.js 和 npm

先输入：

node -v 回车
npm -v 回车

如果都能看到版本号，比如：v22.x.x、10.x.x
说明 Node.js 和 npm 已经有了，可以直接看下一步。

如果提示：

command not found: node
或者
command not found: npm

说明还没装 Node.js。

这时候打开 Node.js 官网：

https://nodejs.org

下载 LTS 版本安装就行。安装过程基本一路继续，不用改太多设置。

安装完之后，关闭终端，重新打开一次，再输入：

node -v
npm -v

能看到版本号，就说明这一步好了。

第三步：用 npm 安装 Codex

在终端输入：

npm install -g @openai/codex

然后等它安装。

如果这里长时间不动，大概率是 npm 包源访问不顺。可以换个网络环境，或者晚点再试。

安装完成后，输入：

codex --version

如果能看到版本号，比如：

codex 0.x.x

说明 Codex 已经装好了。

如果提示：

command not found: codex

先关闭终端，重新打开一次，再试：

codex --version

如果还不行，重新执行：

npm install -g @openai/codex

第四步：建一个测试文件夹

第一次别直接拿重要项目试。
我们先建一个测试文件夹,我习惯了命令创建,你也可以随意位置新建或者访达进入文件夹直接新建文件夹

mkdir -p ~/code/codex-test
cd ~/code/codex-test

现在你已经进入 codex-test 这个目录了。

可以先放一个简单文件进去：

vim README.md

复制一句话进去：

这是我第一次在 Mac 上测试 Codex。

保存方式：

1. 按 i 进入编辑模式
2. 粘贴文字
3. 按 Esc
4. 输入 :wq
5. 按回车

第五步：先启动一次 Codex

在 codex-test 目录里输入：

codex

第一次启动可能会让你登录。

如果你能正常登录官方账号，可以先按提示登录。

如果你准备用 API Key 接入，也可以继续往下看配置。

因为我电脑已经使用了.所以这步就无法截图了。

国内用户怎么接 API

国内用户用 Codex 时，最常见的问题其实不是安装，而是接口访问和模型管理。

如果你有自己的 API 网关，就可以把 Codex 接到自己的接口上。我自己使用的站点是：云AiCode，各位看官按需处理。

后面的配置里我会用 https://cdn.yunaicode.com/v1 做占位，你实际填写时换成自己的接口地址就行。

第六步：创建 Codex 配置文件

Codex 的配置文件一般放在这里：

这里要特别说明，.开头的文件夹默认都是隐藏文件夹，mac本身是不会显示的，所以如果你要通过访达进入文件夹去手动新建配置文件，你需要进入任意文件夹，然后同时按住:shift+command+句号按钮(问号旁边那个) 然后隐藏文件夹就会显示了。

~/.codex/config.toml

新手不用手动去 Finder 里找，直接用命令创建就行。

在终端输入：

mkdir -p ~/.codex
vim ~/.codex/config.toml

会进入 vim 编辑界面。

先按 i 进入编辑模式，再把下面这段复制进去：

model = "这里填你能用的模型名"
model_provider = "custom"
[model_providers.custom]
name = "Custom API"
base_url = "https://cdn.yunaicode.com/v1"
env_key = "API_KEY"
wire_api = "responses"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

这里要改两个地方。

第一个是模型名：

model = "这里填你能用的模型名"

不要自己猜，去你的中转站模型广场复制你想用的模型名。

第二个是接口地址：

base_url = "https://cdn.yunaicode.com/v1"

注意最后的 /v1。少了这个，很容易报错。

保存方式：

1. 按 Esc
2. 输入 :wq
3. 按回车

注意:我的截图里面用的我是常用的云AiCode的网关

第七步：设置 API Key

上面的配置里有一行：

env_key = "API_KEY"

意思是 Codex 会去系统环境变量里找一个叫 API_KEY 的值。

所以我们要把自己的 Key 放进去。

先看一下你用的是 zsh 还是 bash：

echo $SHELL

现在大部分 Mac 默认是 zsh。如果输出里有 zsh，执行：

echo 'export API_KEY="你的 API Key"' >> ~/.zshrc
source ~/.zshrc

这一步是设置你机器的中一个叫:API_KEY 的环境变量,提供给codex的配置文件使用
比如你的 Key 是 sk-xxxx，就写成：

echo 'export API_KEY="sk-xxxx"' >> ~/.zshrc
source ~/.zshrc

如果你输出里是 bash，就执行：

echo 'export API_KEY="你的 API Key"' >> ~/.bashrc
source ~/.bashrc

设置完检查一下：

echo $API_KEY

如果能看到你的 Key，就说明设置成功了。

截图里面的api_key是我自己的,我已经删除了…就不要想白嫖我的token了…哈哈哈哈

第八步：让 Codex 用中文回复

我刚开始用的时候，Codex 经常中英文混着来。

比较简单的办法是在项目目录里放一个 AGENTS.md。

先进入刚才的测试目录：

cd ~/code/codex-test

然后创建文件：

vim AGENTS.md

先按 i 进入编辑模式，再复制下面这段进去：

# AGENTS.md

## 回复习惯

- 默认使用简体中文回复。
- 命令、文件名、函数名保持原文。
- 解释代码时尽量说人话，不要写成官方文档。

## 操作规则

- 修改文件前先说明计划。
- 不确定的地方先问我。
- 不要改 .env、密钥文件和生产配置。
- 新增依赖前先说明原因。
- 修改完成后告诉我改了哪些文件，以及怎么验证。

保存方式还是：

1. 按 Esc
2. 输入 :wq
3. 按回车

然后启动 Codex：

codex

第一次可以这样问它：

请先阅读 AGENTS.md，后面默认用简体中文回复。

这样后面沟通会自然很多。

第九步：第一次怎么问 Codex

不要一上来就说：

帮我把项目改好

它不知道你说的“改好”是什么意思。

我建议按这个顺序来。

先让它看项目：

先不要修改文件，请帮我看一下当前项目结构，告诉我这个项目大概是做什么的。

再让它判断怎么启动：

这个项目应该怎么启动？先给我步骤，不要直接执行命令。

如果你有报错，就这样问：

我遇到了下面这个报错，请先帮我分析原因，不要直接改代码。

这里粘贴报错内容

确认之后再让它改：

请只修改和这个报错相关的文件，改动尽量小。修改前先告诉我计划。

这个节奏比较稳。

常见问题

1. npm install 卡住

大概率是网络问题。

换个网络环境，或者稍后再试。

2. command not found: codex

先关闭终端，重新打开。

然后再试：

codex --version

如果还不行，重新执行：

npm install -g @openai/codex

3. API Key 设置后没反应

先检查：

echo $API_KEY

如果没有输出，说明 Key 没设置成功。

再看你写的是不是正确的 shell 配置文件。一般 Mac 默认是 ~/.zshrc。

4. model not found

一般是模型名写错。

回到 config.toml，检查：

model = "这里填你能用的模型名"

把它改成你后台真实可用的模型名。

5. 接口 404

检查：

base_url = "https://cdn.yunaicode.com/v1"

重点看最后有没有 /v1。

6. Codex 一直用英文

确认项目目录里有没有 AGENTS.md。

启动后再说一句：

请先阅读 AGENTS.md，后续默认用简体中文回复。

最后说一句

新手第一次用 Codex，不要急着拿公司项目或者正式项目试。

先建一个测试文件夹，跑通安装、配置、中文回复，再慢慢拿真实项目试。

我自己的感觉是，Codex 好用的地方不是“让它一次性替你写完整项目”，而是它能在项目上下文里帮你看代码、查问题、改小功能。

Mac 这篇先写到这里。

后面如果继续写，我会再整理一篇 Codex 的常用提问模板。

到此这篇关于Codex在Mac上运行的从零到开始教程的文章就介绍到这了,更多相关Codex Mac教程内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！

最新评论