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

一、环境准备与安装
1、系统前置依赖检查
- Windows
打开 PowerShell,依次执行:node -vnpm -vgit --version1 - macOS
打开终端,执行相同命令。若未安装 Homebrew,先运行:/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"4 - Linux (Ubuntu/Debian)
执行:node -vnpm -vgit --version
若缺失 Node.js,运行:curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs5
2、Codex核心工具安装

二、核心配置文件详解
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 最小可用配置字段说明
2、AGENTS.md规则设定

三、MCP服务连接配置
1、本地文件系统接入
在 VS Code 中,只需通过侧边栏打开目标项目文件夹,Codex 即自动绑定该目录。CLI 用户启动时需先进入项目目录再运行
codex。152、常用外部工具集成
| MCP 服务 | 用途 | 新手是否必备 | 配置要点 |
|---|---|---|---|
| Filesystem | 读写本地文件 | ✅ 必备 | 默认启用,无需额外配置 |
| Brave Search / Web Search | 实时联网检索 | ✅ 推荐 | 在设置中开启浏览器插件权限 |
| GitHub | 读取仓库代码 | ❌ 可选 | 需授权 GitHub 账号,仅限自有仓库 |
| SQLite / Postgres | 数据库查询 | ❌ 进阶 | 需提供连接字符串,谨慎授权 |
高频 MCP 服务对比

四、首个项目实战演练
1、初始化智能体会话
打开 VS Code,加载一个空文件夹作为测试项目。点击左侧 Codex 图标,在聊天框输入:15
“请先读取当前项目目录结构,不要修改任何文件。告诉我这是一个什么类型的项目,并等待我的下一步指令。”
这一步确保 Codex 理解上下文,且不会误操作。15
这一步确保 Codex 理解上下文,且不会误操作。15
2、执行具体开发任务
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
当前文章无评论,是时候发表评论了