npm install -g @openai/codex

brew install --cask codex

# 验证安装
codex --version
codex --help

codex
#首次运行自动引导 OAuth 登录
#选择 "Sign in with ChatGPT"
浏览器自动打开完成授权

printenv OPENAI_API_KEY | codex login --with-api-key

#或设置环境变量后直接用
export OPENAI_API_KEY="sk-你的key"
codex

# 检查登录状态
codex login status

cd ~/my-project
codex "解释当前项目的目录结构，每行一句话"

# 方式一：npm（推荐）
npm install -g @openai/codex

#方式二：Homebrew
brew install --cask codex

#方式三：二进制 Apple Silicon
curl -L -o codex.tar.gz https://github.com/openai/codex/releases/latest/download/codex-aarch64-apple-darwin.tar.gz
tar xzf codex.tar.gz
sudo mv codex-aarch64-apple-darwin /usr/local/bin/codex

#方式四：二进制 Intel Mac
curl -L -o codex.tar.gz https://github.com/openai/codex/releases/latest/download/codex-x86_64-apple-darwin.tar.gz
tar xzf codex.tar.gz
sudo mv codex-x86_64-apple-darwin /usr/local/bin/codex

# npm
npm install -g @openai/codex

#二进制 x86_64
curl -L -o codex.tar.gz https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz
tar xzf codex.tar.gz
sudo mv codex-x86_64-unknown-linux-musl /usr/local/bin/codex

#二进制 arm64（树莓派/ARM云服务器）
curl -L -o codex.tar.gz https://github.com/openai/codex/releases/latest/download/codex-aarch64-unknown-linux-musl.tar.gz
tar xzf codex.tar.gz
sudo mv codex-aarch64-unknown-linux-musl /usr/local/bin/codex

# 1. 安装 WSL2（如果还没有）
wsl --install -d Ubuntu

#2. 进入 WSL2，按 Linux 方式安装
wsl
npm install -g @openai/codex

git clone https://github.com/openai/codex.git
cd codex/codex-rs

#安装 Rust 工具链
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

#编译运行
cargo build --release
cargo run --bin codex -- "解释这个代码库"

# 查看当前登录状态
codex login status

#登出
codex logout

# 查看配置文件
cat ~/.codex/config.toml

#日志位置（排查问题时有用）
tail -F ~/.codex/log/codex-tui.log

# CLI 参数指定模型
codex --model gpt-4o "优化这段代码"

#TUI 内切换模型
/model

#指定推理强度
codex --model o3-mini "分析这个复杂算法"

#非交互模式指定模型
codex exec --model gpt-4o-mini "检查代码风格"

# 启用沙箱（默认）
codex --sandbox

#macOS：使用 Seatbelt 沙箱
codex sandbox macos -- "npm install"

#Linux：使用 bubblewrap 沙箱
codex sandbox linux -- "pip install requests"

#限制工作目录
codex --cd ./my-project

# 列出所有功能开关
codex features list

#启用/禁用功能
codex features enable web_search
codex features disable experimental_voice

#CLI 临时开关
codex --enable web_search "搜索这个 bug 的解决方案"

# 方式一：HTTP 代理
export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"
codex

#方式二：API Base 中转
export OPENAI_API_BASE="https://你的中转地址/v1"
codex

#方式三：写入 shell 配置永久生效
echo 'export HTTPS_PROXY="http://127.0.0.1:7890"' >> ~/.zshrc
source ~/.zshrc

# 进入项目目录
cd ~/my-project

#启动交互模式
codex

#输入你的需求
> 帮我创建一个 Express + TypeScript 项目脚手架
> 给 src/services/user.ts 添加邮箱验证功能

# 单次执行
codex exec "检查 src/ 下所有 TypeScript 文件的类型错误"

#指定模型 + 非交互（自动确认）
codex exec --model gpt-4o-mini --yes "运行 npm install 并报告结果"

#CI/CD 中使用
codex exec --ephemeral --json "运行测试并按 JSON 格式输出结果"

#输出最后一条消息到文件
codex exec -o result.md "分析性能瓶颈并输出报告"

# 恢复上次会话
codex resume --last

#从历史中选择
codex resume

#恢复指定会话
codex resume SESSION_ID

#分叉当前会话（试验性改动不影响原会话）
/fork

#在交互模式中重命名当前会话
/rename

#继续上次会话（命令行参数）
codex resume --last

# 分析错误日志
cat error.log | codex exec "分析这些错误并给出修复建议"

#审查代码 diff
git diff HEAD~3 | codex exec "审查这 3 个 commit 的改动"

#处理大量文本
cat README.md | codex exec "翻译成中文"

# 附加图片分析
codex -i screenshot.png "这个 UI 有什么问题？"

#附加多张图片
codex -i design.png,error.png "对比设计稿和实际页面"

codex "帮我实现一个 RESTful API，包含用户注册、登录、JWT 认证"
codex "在 src/services/user.ts 中实现邮箱验证功能"
codex exec "根据 api-spec.yaml 生成 TypeScript 类型定义"

# 审查整个目录
codex "审查 src/api/ 目录的所有文件，找出安全问题和性能瓶颈"

#审查 diff
git diff main...feature | codex exec "审查这些改动，写一份 Code Review 报告"

#使用 review 子命令
codex review --uncommitted
codex review --base main

codex "将 src/old/ 下所有 Class 组件重构为函数组件 + Hooks，保持功能不变"
codex "提取 src/utils/ 中的公共逻辑到独立的 npm 包"
codex exec "扫描项目，找出循环依赖并修复"

# 生成 commit message
codex "根据当前改动生成规范的中文 commit message"

#分析 commit 历史
codex "解释最近 5 个 commit 做了什么，用中文总结"

#解决冲突
codex "帮我解决当前的 merge conflict"

#生成 PR 描述（Codex 特色功能）
codex exec "根据当前分支相对于 main 的改动，生成 PR 描述"

npm test 2>&1 | codex exec "分析测试失败原因并修复"
cat /var/log/nginx/error.log | codex exec "分析错误日志，找出高频错误和修复建议"

codex "给 src/ 下所有 .ts 文件添加 JSDoc 注释"
codex exec "扫描项目，找出所有 TODO 和 FIXME，分类整理成表格"

# .github/workflows/codex-review.yml
name: Codex Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @openai/codex
      - run: codex exec "审查这个 PR 的改动并输出报告"
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

# 在编辑器中安装 Codex 插件后
#终端和 IDE 共享会话状态

#终端里启动的任务可以在 IDE 中查看结果
codex "创建一个 React 组件"  # 生成的文件自动在 IDE 中打开

#在 TUI 中引用 IDE 上下文
/ide  # 包含当前打开的文件和选区

# 列出已配置的 MCP 服务器
codex mcp list

#添加 MCP 服务器（通过 URL）
codex mcp add my-server --url https://example.com/mcp

#添加 MCP 服务器（通过命令启动）
codex mcp add local-tools -- node server.js

#OAuth 登录 MCP 服务器
codex mcp login my-server

#查看服务器详情
codex mcp get my-server --json

#移除服务器
codex mcp remove my-server

#在 TUI 中查看可用 MCP 工具
/mcp

# 添加插件市场
codex plugin marketplace add owner/repo

#添加本地插件
codex plugin marketplace add ./my-local-plugin

#升级插件市场
codex plugin marketplace upgrade

#移除插件市场
codex plugin marketplace remove owner/repo

#在 TUI 中浏览插件
/plugins

# 在启用沙箱的交互模式
codex --sandbox

#添加沙箱可读目录
/sandbox-add-read-dir /path/to/data

#设置默认沙箱
/setup-default-sandbox

# AGENTS.md 示例
#项目：电商后端 API
#技术栈：Go + PostgreSQL + Redis
#编码规范：遵循 Google Go Style Guide
测试框架：使用 testify

# 在 TUI 中自动创建
/init

# 查看和管理钩子
/hooks

#支持的钩子类型：
#- 会话开始/结束
#- 工具使用前后
- 对话压缩前后

# 连接远程 app-server
codex --remote ws://192.168.1.100:8080

#带认证令牌连接
codex --remote wss://server.com --remote-auth-token-env CODEX_TOKEN

#在服务器上启动 app-server
codex app-server

# 好：明确具体
codex "在 src/api/users.ts 中实现分页查询，每页 20 条，按创建时间倒序"

#差：太模糊
codex "帮我写个 API"

#好：提供上下文
codex "参照 src/services/auth.ts 的风格，实现 refresh token 的逻辑"

#好：指定约束
codex "重构这个函数，要求：不改变接口、时间复杂度 O(n)、加单元测试"

#!/bin/bash
#daily-review.sh - 每日代码审查

cd ~/my-project
codex exec "审查今天的所有 git diff，生成审查报告" > daily-review.md

# cron 定时任务
#每天 9:00 自动检查依赖更新
0 9 * * * cd ~/my-project && codex exec "检查 package.json 中过时的依赖并输出报告"

# 切换到 Plan 模式
/plan

#AI 会先给出计划而非直接执行
> 我要把项目从 JavaScript 迁移到 TypeScript
#AI：这是一个大型任务。这是我的分步计划：
#1. 安装 TypeScript 依赖
#2. 创建 tsconfig.json
#3. 逐文件转换...

批准后按计划执行

# 切换协作模式
/collab

#/side 启动侧边对话（临时分叉，不影响主会话）
/side "快速测试这个想法是否可行"

# 问题：command not found: codex
which codex
echo $PATH
#解决：确认 npm 全局 bin 目录在 PATH 中
export PATH="$PATH:$(npm config get prefix)/bin"

#问题：npm 全局安装权限不足
npm install -g @openai/codex --prefix ~/.local
#然后把 ~/.local/bin 加入 PATH

#问题：Node.js 版本过低
node --version  # 需要 >= 16
nvm install 20

# 问题：ChatGPT 登录失败
codex logout  # 先登出
codex         # 重新登录

#问题：无法打开登录页面
#复制终端输出的 URL，手动在浏览器中打开完成授权

#问题：API Key 不生效
echo $OPENAI_API_KEY  # 检查是否设置
codex login status    # 检查当前认证方式

# 检查 API 连通性
curl -s -o /dev/null -w "%{http_code}" https://api.openai.com/v1/models

#使用代理
export HTTPS_PROXY="http://127.0.0.1:7890"

#检查 Codex 日志
tail -F ~/.codex/log/codex-tui.log

# 问题：响应慢
codex --model gpt-4o-mini  # 换更快的模型

#问题：对话历史太长
/clear  # 清除历史
/compact  # 压缩历史保留关键信息

#问题：权限不足无法修改文件
ls -la  # 检查文件权限
chmod +w filename  # 添加写权限

# ==========================================
#安装与验证
#==========================================
npm install -g @openai/codex
brew install --cask codex
codex --version
codex --help
codex update

#==========================================
#启动模式
#==========================================
codex                                    # 交互式 TUI
codex "query"                            # 带初始提示的交互
codex exec "query"                       # 非交互执行
codex exec --ephemeral "query"           # 不留会话记录的非交互执行
codex exec --json "query"                # JSON 输出
codex exec -o result.md "query"          # 输出到文件
cat file | codex exec "query"            # 管道模式

#==========================================
#登录
#==========================================
codex                                     # 首次自动引导 OAuth
printenv OPENAI_API_KEY | codex login --with-api-key
codex login --device-auth                 # 设备码登录
codex login status                        # 查看登录状态
codex logout                              # 登出

#==========================================
#模型与配置
#==========================================
codex --model gpt-4o                      # 指定模型
codex --model gpt-4o-mini                 # 快速便宜
codex --model o3-mini                     # 推理优先
codex --profile my-config                 # 使用配置 Profile
codex features list                       # 列出功能开关
codex features enable web_search          # 启用功能

#==========================================
#安全
#==========================================
codex --sandbox                           # 启用沙箱
codex sandbox macos -- command            # macOS Seatbelt
codex sandbox linux -- command            # Linux bubblewrap
/approve                                  # 批准自动审查拒绝的操作
/permissions                              # 配置权限策略

#==========================================
#会话管理
#==========================================
codex resume --last                       # 恢复最近会话
codex resume SESSION_ID                   # 恢复指定会话
codex fork --last                         # 分叉最近会话
/rename                                   # 重命名会话
/new                                      # 开始新对话
/clear                                    # 清除历史
/compact                                  # 压缩历史

#==========================================
#Git 与代码审查
#==========================================
codex review --uncommitted                # 审查未提交改动
codex review --base main                  # 对比 main 分支
/diff                                     # 显示 Git 改动
codex apply                               # 应用最新 diff

#==========================================
#MCP 与插件
#==========================================
codex mcp list                            # 列出 MCP 服务器
codex mcp add NAME --url URL              # 添加服务器
codex mcp login NAME                      # OAuth 登录
codex mcp remove NAME                     # 移除服务器
codex plugin marketplace add owner/repo   # 添加插件市场
codex plugin marketplace upgrade          # 升级插件
/mcp                                      # TUI 中查看 MCP 工具
/plugins                                  # TUI 中浏览插件

#==========================================
#IDE 与远程
#==========================================
codex app                                 # 启动桌面应用
codex --remote ws://ADDR                  # 连接远程
codex app-server                          # 启动 app-server
/ide                                      # 包含 IDE 上下文

#==========================================
#环境变量
#==========================================
export OPENAI_API_KEY="sk-..."
export OPENAI_API_BASE="https://中转地址/v1"
export HTTPS_PROXY="http://127.0.0.1:7890"
export CODEX_HOME="~/.codex"

#==========================================
#调试与信息
#==========================================
tail -F ~/.codex/log/codex-tui.log       # 查看日志
codex debug models                        # 查看可用模型
/status                                   # 查看会话状态和用量
/feedback                                 # 发送反馈
codex debug clear-memories               # 重置本地记忆