mirror of
https://github.com/tradecatlabs/vibe-coding-cn.git
synced 2026-08-04 06:37:44 +00:00
docs: expand codex cli zero-to-one install guide
This commit is contained in:
tukuaiai
@@ -1,6 +1,6 @@
|
||||
# Codex CLI 配置
|
||||
|
||||
> 默认 AI CLI 路线：用 Codex CLI 作为主要编程代理，把本仓库的配置基线复制到本机 Codex Home。
|
||||
> 默认 AI CLI 路线：假设你拿到的是一台全新电脑，从 0 安装系统依赖、Node.js、Codex CLI，然后用浏览器完成 Codex 登录。
|
||||
|
||||
## 定位
|
||||
|
||||
@@ -8,35 +8,191 @@ Codex CLI 是本教程默认推荐的 AI CLI。它适合承担从需求拆解、
|
||||
|
||||
OpenCode CLI 保留为备选方案：当你暂时无法使用 OpenAI / Codex CLI，或只想接入免费模型时，再使用 [OpenCode-CLI配置](./OpenCode-CLI配置.md)。
|
||||
|
||||
## 前置条件
|
||||
## 总流程
|
||||
|
||||
请先完成：
|
||||
|
||||
1. [网络环境配置](./网络环境配置.md)
|
||||
2. [开发环境搭建](./开发环境搭建.md)
|
||||
3. [IDE 配置](./IDE配置.md)
|
||||
|
||||
在终端验证 Codex CLI 是否可用：
|
||||
|
||||
```bash
|
||||
codex --help
|
||||
```text
|
||||
新电脑
|
||||
-> 安装系统基础工具
|
||||
-> 安装 Node.js 22+
|
||||
-> npm 安装 Codex CLI
|
||||
-> codex --version 验证
|
||||
-> codex login 浏览器登录
|
||||
-> 复制本仓库 Codex 配置基线
|
||||
-> 进入项目运行 codex
|
||||
```
|
||||
|
||||
如果命令不存在，先按你当前系统的 Codex CLI 安装方式完成安装，再回到本页继续。
|
||||
推荐优先级：
|
||||
|
||||
## 登录
|
||||
1. Windows 11 用户优先使用 WSL2 + Ubuntu。
|
||||
2. Linux 用户按 Ubuntu / Debian 路线安装。
|
||||
3. macOS 用户使用 Homebrew 安装 Node.js。
|
||||
4. Windows 原生 PowerShell 可用，但长期工程体验不如 WSL2 稳定。
|
||||
|
||||
## Windows 11：推荐 WSL2 + Ubuntu
|
||||
|
||||
### 第一步：安装 WSL2
|
||||
|
||||
在 Windows 开始菜单搜索 **PowerShell**，右键“以管理员身份运行”：
|
||||
|
||||
```powershell
|
||||
wsl --install -d Ubuntu
|
||||
```
|
||||
|
||||
安装完成后重启电脑，打开 Ubuntu，按提示创建 Linux 用户名和密码。
|
||||
|
||||
如果已经安装过 WSL，可执行：
|
||||
|
||||
```powershell
|
||||
wsl --update
|
||||
wsl --set-default-version 2
|
||||
```
|
||||
|
||||
### 第二步：在 Ubuntu 中安装 Codex CLI
|
||||
|
||||
打开 Ubuntu 终端，执行：
|
||||
|
||||
```bash
|
||||
sudo apt update && sudo apt install -y curl ca-certificates gnupg git build-essential
|
||||
sudo install -d -m 0755 /etc/apt/keyrings
|
||||
sudo rm -f /etc/apt/keyrings/nodesource.gpg
|
||||
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
|
||||
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list
|
||||
sudo apt update && sudo apt install -y nodejs
|
||||
sudo npm i -g @openai/codex@latest
|
||||
node -v
|
||||
npm -v
|
||||
codex --version
|
||||
```
|
||||
|
||||
### 第三步：网页登录
|
||||
|
||||
```bash
|
||||
codex login
|
||||
```
|
||||
|
||||
登录完成后，再次运行：
|
||||
按终端提示打开浏览器完成登录。登录后检查状态：
|
||||
|
||||
```bash
|
||||
codex --help
|
||||
codex login status
|
||||
```
|
||||
|
||||
能看到命令说明，就说明 CLI 已可用。
|
||||
## Ubuntu / Debian Linux
|
||||
|
||||
全新 Ubuntu / Debian 机器直接执行：
|
||||
|
||||
```bash
|
||||
sudo apt update && sudo apt install -y curl ca-certificates gnupg git build-essential
|
||||
sudo install -d -m 0755 /etc/apt/keyrings
|
||||
sudo rm -f /etc/apt/keyrings/nodesource.gpg
|
||||
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
|
||||
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list
|
||||
sudo apt update && sudo apt install -y nodejs
|
||||
sudo npm i -g @openai/codex@latest
|
||||
node -v
|
||||
npm -v
|
||||
codex --version
|
||||
codex login
|
||||
```
|
||||
|
||||
如果你是在 root 用户下配置新服务器，可以去掉 `sudo`：
|
||||
|
||||
```bash
|
||||
apt update && apt install -y curl ca-certificates gnupg git build-essential && install -d -m 0755 /etc/apt/keyrings && rm -f /etc/apt/keyrings/nodesource.gpg && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" > /etc/apt/sources.list.d/nodesource.list && apt update && apt install -y nodejs && npm i -g @openai/codex@latest && node -v && npm -v && codex --version
|
||||
```
|
||||
|
||||
然后执行：
|
||||
|
||||
```bash
|
||||
codex login
|
||||
```
|
||||
|
||||
## macOS
|
||||
|
||||
### 第一步：安装命令行工具
|
||||
|
||||
```bash
|
||||
xcode-select --install
|
||||
```
|
||||
|
||||
如果系统提示已经安装，可继续下一步。
|
||||
|
||||
### 第二步：安装 Homebrew
|
||||
|
||||
```bash
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||||
```
|
||||
|
||||
安装结束后，按 Homebrew 终端输出把 `brew` 加入 shell 环境。
|
||||
|
||||
Apple Silicon 常见配置：
|
||||
|
||||
```bash
|
||||
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
|
||||
eval "$(/opt/homebrew/bin/brew shellenv)"
|
||||
```
|
||||
|
||||
Intel Mac 常见配置：
|
||||
|
||||
```bash
|
||||
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
|
||||
eval "$(/usr/local/bin/brew shellenv)"
|
||||
```
|
||||
|
||||
### 第三步：安装 Node.js 和 Codex CLI
|
||||
|
||||
```bash
|
||||
brew install git node
|
||||
npm i -g @openai/codex@latest
|
||||
node -v
|
||||
npm -v
|
||||
codex --version
|
||||
codex login
|
||||
```
|
||||
|
||||
## Windows 11：原生 PowerShell 备选
|
||||
|
||||
如果你暂时不想使用 WSL2，可以在 Windows 原生 PowerShell 中安装。
|
||||
|
||||
打开 PowerShell：
|
||||
|
||||
```powershell
|
||||
winget source update
|
||||
winget install --id Git.Git -e --source winget
|
||||
winget install --id OpenJS.NodeJS.LTS -e --source winget
|
||||
```
|
||||
|
||||
关闭并重新打开 PowerShell，然后执行：
|
||||
|
||||
```powershell
|
||||
node -v
|
||||
npm -v
|
||||
npm i -g @openai/codex@latest
|
||||
codex --version
|
||||
codex login
|
||||
```
|
||||
|
||||
如果 `winget` 不存在，先在 Microsoft Store 更新或安装 **App Installer**。
|
||||
|
||||
## API Key 模式（可选）
|
||||
|
||||
默认推荐 `codex login` 浏览器登录。不要把占位 API Key 写进环境变量，否则可能干扰认证排查。
|
||||
|
||||
如果你明确要使用 API Key 模式，再执行：
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config
|
||||
grep -q "OPENAI_API_KEY" ~/.bashrc || echo 'export OPENAI_API_KEY="sk-替换成你的OpenAI_API_KEY"' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
printenv OPENAI_API_KEY | codex login --with-api-key
|
||||
```
|
||||
|
||||
Windows PowerShell 的 API Key 配置：
|
||||
|
||||
```powershell
|
||||
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-替换成你的OpenAI_API_KEY", "User")
|
||||
$env:OPENAI_API_KEY="sk-替换成你的OpenAI_API_KEY"
|
||||
$env:OPENAI_API_KEY | codex login --with-api-key
|
||||
```
|
||||
|
||||
## 使用仓库配置基线
|
||||
|
||||
@@ -73,17 +229,24 @@ codex --search -m gpt-5.5 -c model_reasoning_effort="xhigh" --dangerously-bypass
|
||||
|
||||
## 推荐别名
|
||||
|
||||
在 `~/.bashrc` 中添加：
|
||||
Linux / WSL / macOS：
|
||||
|
||||
```bash
|
||||
cat >> ~/.bashrc <<'EOF'
|
||||
alias c='codex --search -m gpt-5.5 -c model_reasoning_effort="xhigh"'
|
||||
alias cy='codex --search -m gpt-5.5 -c model_reasoning_effort="xhigh" --dangerously-bypass-approvals-and-sandbox'
|
||||
EOF
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
生效：
|
||||
如果你使用的是 macOS 默认 zsh，把 `~/.bashrc` 换成 `~/.zshrc`：
|
||||
|
||||
```bash
|
||||
source ~/.bashrc
|
||||
cat >> ~/.zshrc <<'EOF'
|
||||
alias c='codex --search -m gpt-5.5 -c model_reasoning_effort="xhigh"'
|
||||
alias cy='codex --search -m gpt-5.5 -c model_reasoning_effort="xhigh" --dangerously-bypass-approvals-and-sandbox'
|
||||
EOF
|
||||
source ~/.zshrc
|
||||
```
|
||||
|
||||
## 第一次使用
|
||||
@@ -103,6 +266,37 @@ codex
|
||||
|
||||
确认计划后，再让 Codex 执行。
|
||||
|
||||
## 常见问题
|
||||
|
||||
### `codex: command not found`
|
||||
|
||||
检查 npm 全局安装目录是否在 `PATH` 中：
|
||||
|
||||
```bash
|
||||
npm config get prefix
|
||||
echo "$(npm config get prefix)/bin"
|
||||
```
|
||||
|
||||
重新打开终端后再执行：
|
||||
|
||||
```bash
|
||||
codex --version
|
||||
```
|
||||
|
||||
### `sudo npm i -g` 权限问题
|
||||
|
||||
Linux / WSL 用 NodeSource 安装的 Node.js 通常需要 `sudo npm i -g`。如果你使用 nvm 管理 Node.js，则不要使用 `sudo`。
|
||||
|
||||
### 浏览器登录失败
|
||||
|
||||
先确认网络环境可访问 OpenAI 登录页面，再执行：
|
||||
|
||||
```bash
|
||||
codex login
|
||||
```
|
||||
|
||||
如果你是在无桌面的远程服务器上登录，按终端输出的设备码或链接，在本机浏览器完成授权。
|
||||
|
||||
## 下一步
|
||||
|
||||
→ [开发环境搭建](./开发环境搭建.md) - 回看基础环境
|
||||
|
||||
Reference in New Issue
Block a user