什么值得买App下载 App ›
连续签到专享现金活动

新手装 Codex 总失败?先确认这三件事

一、环境准备与安装
1、系统前置依赖检查
新手最容易卡在环境不匹配上。别急着装 Codex,先确认三件事:
• Node.js 版本 ≥ 18(推荐 22+ LTS)
• Git 已安装并配置全局用户名/邮箱
• VS Code 或 Cursor 编辑器已更新至最新版
123
  • Windows
    打开 PowerShell,依次执行:
    node -v
    npm -v
    git --version
    1
  • macOS
    打开终端,执行相同命令。若未安装 Homebrew,先运行:
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    4
  • Linux (Ubuntu/Debian)
    执行:
    node -v
    npm -v
    git --version
    若缺失 Node.js,运行:
    curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs
    5
2、Codex核心工具安装
新手强烈推荐从 VS Code 插件入手,无需处理终端权限和环境变量,开箱即用。63
  • VS Code 插件版(推荐)
    1. 打开 VS Code → 扩展商店
    2. 搜索 “OpenAI Codex”
    3. 安装官方插件
    4. 重启编辑器,侧边栏出现 Codex 图标即成功
    67
  • 命令行 CLI 版
    在终端执行:
    npm install -g @openai/codex
    国内用户建议加镜像加速:
    npm install -g @openai/codex --registry=https://registry.npmmirror.com
    验证安装:
    codex --version
    518
二、核心配置文件详解
1、config.toml基础配置
配置项必须修改?示例值说明
model是gpt-5-codex推荐使用生产级代码模型
openai_base_url国内用户必填https://api.sheepai.top/v1中转平台地址,如 sheepai、硅基流动等
OPENAI_API_KEY是sk-xxx替换为实际 API 密钥
timeout否120单位秒,超时可适当调大
log_level否info调试时可设为 debug

config.toml 最小可用配置字段说明

配置文件路径:~/.codex/config.toml(Windows 为 C:\Users\用户名\.codex\config.toml)。首次使用需手动创建该文件夹及文件。49
2、AGENTS.md规则设定
AGENTS.md 是项目级行为说明书,放在项目根目录,Codex 会自动加载。以下为通用模板,只需替换技术栈名称即可使用:1011
## 技术栈
- 前端:React + TypeScript
- 构建工具:Vite
- 测试:Jest + React Testing Library

## 代码规范
- 缩进:2 空格
- 文件命名:kebab-case
- 函数命名:camelCase
- 所有组件必须使用 TypeScript 类型
- 禁止使用 any

## 禁止操作
- 不得删除 src/ 以外的文件
- 不得修改 package.json 中的依赖版本
- 不得自动提交或推送代码

## 输出要求
- 注释使用英文
- 新增功能必须包含单元测试
- 修改后需通过 npm run lint 和 npm test
1012
三、MCP服务连接配置
1、本地文件系统接入
Codex 默认以当前打开的文件夹为工作区沙箱,仅允许读写该目录内文件。这是安全机制,切勿为了方便授权整个磁盘。1314
在 VS Code 中,只需通过侧边栏打开目标项目文件夹,Codex 即自动绑定该目录。CLI 用户启动时需先进入项目目录再运行 codex。15
2、常用外部工具集成
MCP 服务用途新手是否必备配置要点
Filesystem读写本地文件✅ 必备默认启用,无需额外配置
Brave Search / Web Search实时联网检索✅ 推荐在设置中开启浏览器插件权限
GitHub读取仓库代码❌ 可选需授权 GitHub 账号,仅限自有仓库
SQLite / Postgres数据库查询❌ 进阶需提供连接字符串,谨慎授权

高频 MCP 服务对比

四、首个项目实战演练
1、初始化智能体会话
打开 VS Code,加载一个空文件夹作为测试项目。点击左侧 Codex 图标,在聊天框输入:15
“请先读取当前项目目录结构,不要修改任何文件。告诉我这是一个什么类型的项目,并等待我的下一步指令。”
这一步确保 Codex 理解上下文,且不会误操作。
15
2、执行具体开发任务
继续输入:
“请创建一个 React 的 Todo 列表组件,要求:使用函数组件 + useState,支持添加、删除、标记完成,样式简洁。先输出执行计划,确认后再生成代码。”
1116
Codex 会先列出计划:1. 创建 Todo.tsx;2. 编写状态逻辑;3. 添加样式。确认后自动生成完整代码。10
生成后,检查代码是否符合规范,运行 npm run dev 验证功能。若报错,直接告诉 Codex 错误信息,它会自动修复。16
五、常见问题与避坑指南
常见问题避坑指南
  • API Key 配置错误:确认密钥是否复制完整,base_url 是否指向正确的中转平台(如 api.sheepai.top),切勿将密钥提交到公开仓库9
  • 代码无法运行:优先运行 npm install 补全依赖,而非修改逻辑。Codex 生成的代码通常正确,但可能缺少包16
  • 响应超时:检查网络代理是否生效,或在 config.toml 中将 timeout 调至 180 秒17
  • 权限拒绝:Mac/Linux 下对项目目录执行 chmod -R 755 ./project;Windows 下以管理员身份运行 VS Code14
  • 上下文丢失:对话过长时,输入“总结当前进度并重置上下文”,或新建会话线程14

评论

评论区空态插画

当前文章无评论,是时候发表评论了