# CLI 配置 > 默认 AI CLI 路线：假设你拿到的是一台全新电脑，从 0 安装系统依赖、Node.js、Codex CLI，然后用浏览器完成 Codex 登录。 ### 定位 Codex CLI 是本教程默认推荐的 AI CLI。它适合承担从需求拆解、代码修改、命令执行、测试验证到 Git 提交的主流程。 OpenCode CLI 只作为备选方案保留在本文底部：当你暂时无法使用 OpenAI / Codex CLI，或只想接入免费、本地、多模型实验入口时，再使用 OpenCode。 Codex CLI 跑通后，不要再把所有环境配置都当成人工步骤。优先让 Codex Agent 读取本文档和当前系统信息，主动完成后续开发环境配置。 ### 不会操作？先让网页 AI 生成逐步执行版 如果你不确定该执行哪一段安装命令，打开 ChatGPT / Claude / Gemini 网页版，把下面提示词和本文档全文一起粘贴进去，让 AI 根据你的电脑情况生成专属安装步骤。 ```text 我正在按下面这份 Codex CLI 安装文档配置一台新电脑。请你根据我的系统情况，生成一步一步执行流程。 我的系统是：____ 我是否已经安装过 WSL / Node.js / npm / Git：____ 我想使用的登录方式是：网页登录 codex login 要求： 1. 每一步只做一件事。 2. 明确告诉我在哪个终端执行：PowerShell、Ubuntu 终端、Linux shell 或 macOS Terminal。 3. 每条命令都必须单独放在代码块里，方便我直接复制。 4. 每一步执行后都给一个验证命令或验证方法。 5. 不要假设我已经安装任何前置依赖；按新电脑处理。 6. 如果我后续贴完整报错，请根据当前步骤给出最小修复命令。 下面是完整文档： [把本文档全文粘贴到这里] ``` 如果安装过程中已经报错，不要只复制最后一行错误。请把“你执行的命令 + 完整报错 + 本文档全文”一起发给 AI。 ```text 我正在按下面这份 Codex CLI 安装文档配置一台新电脑，但遇到了报错。 我的系统是：____ 我执行的命令是：____ 完整报错如下： ____ 请判断我卡在哪一步，给出最小修复命令，并说明修复后如何验证。 [把本文档全文粘贴到这里] ``` ### Codex CLI 跑通后：交给 Agent 配置剩余环境 当 `codex --version` 正常输出，并且 `codex login` 已完成网页登录后，直接在项目目录里启动 Codex，把下面提示词交给本地 Agent： ```text 你现在是我的本地开发环境配置 Agent。 前提： - 我已经能运行 Codex CLI。 - 我已经完成 Codex 登录。 - 当前仓库是 vibe-coding-cn。 - 请尽量主动完成配置，除非遇到必须由我授权、输入密码、网页登录、购买订阅、处理敏感凭证或执行不可逆操作的步骤。 目标： 请读取 docs/getting-started/README.md，根据我的系统环境，自动检查并配置 Git、Node.js、Python、包管理器、编辑器建议、项目依赖、测试命令和 Git 工作流。 要求： 1. 先检查当前系统，不要猜。 2. 能自动执行的就自动执行。 3. 需要我操作的，只输出最小步骤。 4. 每完成一步都运行验证命令。 5. 最后输出已完成项、未完成项、风险和下一步。 ``` ### 总流程 ```text 新电脑 -> 安装系统基础工具 -> 安装 Node.js 22+ -> npm 安装 Codex CLI -> codex --version 验证 -> codex login 浏览器登录 -> 安全安装本仓库 Codex 配置基线 -> 进入项目运行 codex ``` 推荐优先级： 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 login status ``` ### 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 ``` ### 使用仓库配置基线 本仓库已经提供可回滚的 Codex CLI 配置基线： - `tools/config/.codex/config.toml` - `tools/config/.codex/config.power.toml` - `tools/config/.codex/AGENTS.safe.md` - `tools/config/.codex/AGENTS.md` - `tools/config/.codex/install.sh` 推荐使用安全默认版。脚本会先备份你已有的 `~/.codex/config.toml` 和 `~/.codex/AGENTS.md`，再安装新配置： ```bash curl -fsSL https://raw.githubusercontent.com/tukuaiai/vibe-coding-cn/develop/tools/config/.codex/install.sh | bash ``` 如果已经 clone 本仓库，也可以在仓库根目录执行： ```bash bash tools/config/.codex/install.sh ``` 需要完全可信本地环境下的高权限配置时，显式安装 `power` profile： ```bash curl -fsSL https://raw.githubusercontent.com/tukuaiai/vibe-coding-cn/develop/tools/config/.codex/install.sh | bash -s -- --profile power ``` 恢复最近一次安装前的配置： ```bash bash ~/.codex/backups/vibe-coding-cn/LATEST/restore.sh ``` 详细说明见：[Codex 配置基线](../../tools/config/.codex/README.md)。 ### 推荐启动方式 日常使用： ```bash codex --search -m gpt-5.5 -c model_reasoning_effort="xhigh" ``` 在完全可信的本地仓库中，需要减少确认弹窗时使用： ```bash codex --search -m gpt-5.5 -c model_reasoning_effort="xhigh" --dangerously-bypass-approvals-and-sandbox ``` 高权限模式会放开确认与沙箱限制，只能在你确认可信的目录中使用。 ### 推荐别名 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 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 ``` ### 第一次使用 进入你的项目目录： ```bash cd /path/to/project codex ``` 然后让 Codex 先建立项目上下文： ```text 请阅读当前仓库结构，说明这个项目是什么、关键入口在哪里、下一步最小可执行任务是什么。先给计划，不要直接改文件。 ``` 确认计划后，再让 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 ``` 如果你是在无桌面的远程服务器上登录，按终端输出的设备码或链接，在本机浏览器完成授权。 ### Codex 不可用时：OpenCode 备选方案 OpenCode 是开源 AI 编程代理，支持终端、桌面应用和 IDE 扩展。本文仍然以 Codex CLI 为默认路线；只有当 Codex CLI 暂时不可用、账号不可用，或你明确需要接入免费/本地模型时，才切到 OpenCode。 官网：[opencode.ai](https://opencode.ai/) #### 不会操作？先让网页 AI 生成逐步执行版 如果你要用 OpenCode 作为备选路线，先打开网页版 AI，把下面提示词和本节内容一起复制进去，让 AI 按你的系统和模型来源生成逐步执行方案： ```text 你是一个面向零基础用户的 OpenCode CLI 配置助手。 请根据我的电脑环境、可用模型和目标，生成适合我的逐步安装与配置流程。 我的当前情况是： - 操作系统：[填写 Windows 11 / WSL2 / macOS / Linux] - 是否已经安装 Node.js / npm / Homebrew / Scoop / Chocolatey：[填写没有 / 已安装 / 不确定] - 想使用的模型来源：[填写 Z.AI / MiniMax / Hugging Face / Ollama / 不确定] - 是否已经有 API Key：[填写有 / 没有 / 不确定] - 卡住的位置：[如果已经卡住，填写具体问题；如果没有，写“还没开始”] 要求： 1. 每一步只做一件事。 2. 每一步都说明我要在哪个终端执行、输入什么、观察什么、如何判断成功。 3. 每条命令都必须单独放在代码块里。 4. 不要跳步；默认我是第一次配置新电脑。 5. 如果我后续贴报错，请根据当前步骤给出最小修复方案。 ``` #### 何时选择 OpenCode - 没有可用的 OpenAI / Codex CLI 账号或环境。 - 需要接入 Z.AI、MiniMax、Hugging Face、本地 Ollama 等模型。 - 想保留一条不依赖单一模型提供商的备份路线。 #### 安装 ```bash # 一键安装（推荐） curl -fsSL https://opencode.ai/install | bash # 或使用 npm npm install -g opencode-ai # 或使用 Homebrew（macOS/Linux） brew install anomalyco/tap/opencode ``` Windows 可用 Scoop 或 Chocolatey： ```powershell scoop bucket add extras scoop install extras/opencode choco install opencode ``` #### 模型配置 OpenCode 支持多个模型提供商。进入 OpenCode 后，用 `/connect` 添加模型提供商，用 `/models` 切换模型。 常见备选： 1. Z.AI：注册 API Key 后，`/connect` 搜索 Z.AI，再用 `/models` 选择 GLM 模型。 2. MiniMax：注册 API Key 后，`/connect` 搜索 MiniMax，再用 `/models` 选择可用模型。 3. Hugging Face：创建 Token 后，`/connect` 搜索 Hugging Face，再用 `/models` 选择可用模型。 4. Ollama：本地安装 Ollama 后，在 `opencode.json` 中配置 OpenAI-compatible base URL。 Ollama 最小安装示例： ```bash curl -fsSL https://ollama.com/install.sh | sh ollama pull llama2 ``` #### 核心命令 | 命令 | 功能 | |:---|:---| | `/models` | 切换模型 | | `/connect` | 添加 API Key | | `/init` | 初始化项目，生成 AGENTS.md | | `/undo` | 撤销上次修改 | | `/redo` | 重做 | | `/share` | 分享对话链接 | | `Tab` | 切换 Plan 模式 | #### 推荐工作流 ```bash cd /path/to/project opencode ``` 进入后先初始化项目，再切换模型： ```text /init /models ``` 建议先用 Plan 模式让 AI 规划，确认方案后再执行。 #### 配置文件位置 - 全局配置：`~/.config/opencode/opencode.json` - 项目配置：`./opencode.json` - 认证信息：`~/.local/share/opencode/auth.json` #### 相关资源 - [OpenCode 官方文档](https://opencode.ai/docs/) - [OpenCode GitHub 仓库](https://github.com/opencode-ai/opencode) - [Models.dev 模型目录](https://models.dev) ### 下一步 → [开发环境搭建](development-environment.md) - 回看基础环境