跳转到内容
全部开发指南

Codex 上手教程：从安装到跑通第一个本地任务

AIGoCode发布于 更新于

Codex 上手教程：从安装到跑通第一个本地任务 封面

第一次接触 Codex，最容易卡在两件事：不知道该装桌面版、命令行、IDE 插件还是云端版；装好之后又不知道怎么发第一条指令、权限弹窗该不该点同意。

这篇按「装好 → 登录 → 选项目 → 发第一条指令 → 看懂它在干嘛」这条主线走通。写完你能独立完成一件小事：让 Codex 读本地项目文件，并在你确认后做一处小改动。文中操作对齐 OpenAI 官方 Codex 文档；产品界面会变，但本地 Agent、沙箱与审批这套逻辑是稳定的。

Codex 界面原文配图 1

先分清：你要装的是哪个 Codex

Codex 不是单一软件，官方常见形态有四种：

  1. Codex App（桌面应用）：本机桌面程序，适合并行跑多个任务，内置 Git、worktree、自动化等能力。本篇以它为主。
  2. Codex CLI（命令行版）：跑在终端，macOS、Linux、Windows 都能装。
  3. IDE 扩展：装在 VS Code、Cursor、Windsurf 等编辑器里。
  4. Codex Cloud（云端版）：入口在 chatgpt.com/codex，可连 GitHub，在云端后台跑任务、提 PR，电脑关机也能继续。

它们通常用同一套 ChatGPT 账号打通。新手可以记一句：

  • 要读本机文件、改本地项目 → 用 Codex App 或 CLI
  • 要长时间挂在云端、关机也不中断 → 用 Codex Cloud

如果你之后要把 Codex CLI 接到 AIGoCode 的模型服务，可以对照这篇核对配置是否生效：Codex CLI 接入 AIGoCode 后，怎样确认配置真的生效。

安装：先看系统支不支持

Codex App 目前有 macOS 与 Windows 版，没有 Linux 原生桌面版。 Linux 用户请直接走 CLI。

Mac：

  1. 从 OpenAI / Codex 官方下载页获取安装包
  2. 选对芯片架构（Apple Silicon 与 Intel 不是同一包）
  3. 把应用拖进「应用程序」后启动

Codex 安装原文配图 2

Windows： 从官方入口或 Microsoft Store 安装。OpenAI 已在 2026 年 3 月宣布 Windows 版 Codex App 可用。

已在用 CLI： 可在终端执行 codex app 拉起桌面版（以本机当前 CLI 版本为准）。

想先试命令行：官方文档提供独立安装脚本与 npm / Homebrew 等安装方式。任选一种装好后，在项目目录启动 Codex 即可。

登录与额度

打开 App，选择 Sign in with ChatGPT，用 ChatGPT 账号登录。

套餐方面，Plus、Pro、Business、Edu、Enterprise 等含 Codex；Free / Go 一类轻量套餐也可能可用，但额度更紧。额度通常按时间窗口累计，本地消息与云端任务会共享窗口——指令越重、模型越大，消耗越快。

也可以用 API Key 登录，但会缺少部分云端能力（如部分代码审查与协作集成）。新手优先用 ChatGPT 账号登录更省事。

选项目：决定它能动哪些文件

登录后选择项目文件夹。这个文件夹就是工作区：Codex 默认只在此范围内读写，不会随便越界。

第一次可以用现有代码仓库，也可以新建空文件夹练手。选完后务必确认模式是 Local——要读本机文件就必须选 Local，而不是 Cloud。

发出第一条指令

准备工作完成后，直接派一个「读 + 小改」的任务，例如：

帮我看一下这个项目的 README，然后在开头加一句话的项目简介。

或：

读一下当前文件夹里的所有文件，告诉我这个项目是干什么的。

发出去后重点观察三点：

  1. 它会真的读文件：结论应来自你仓库里的真实内容，而不是空聊。
  2. 右侧会出现工作现场：读过哪些文件、diff 改了哪里，一般都能看到。
  3. 写文件前可能弹审批：默认不会一声不吭乱改。

权限弹窗：两层控制怎么理解

Codex 的权限大致分两层。

Sandbox（沙箱）——技术上能做什么

  • read-only：只能读
  • workspace-write（常见默认）：可在工作区读写并跑命令，默认往往断网
  • 全权限：无限制，新手不建议一上来就开

Approval（审批）——什么时候问你

  • on-request：该问时问（有 Git 的目录常见默认）
  • untrusted：只自动跑已知安全的读操作
  • never：不弹审批

即便给了写权限，.git、.agents、.codex 一类关键目录通常仍保持只读。新手保留默认即可：弹窗出现时看一眼操作内容，合理再同意。可用 /permissions、/status 查看或调整（以当前版本命令为准）。

两条安全习惯：

  1. 一旦允许联网搜索，注意网页里的提示词注入风险，不要完全放养。
  2. 重要任务前后做一次 Git 提交，方便回滚。

跑通之后：后面这些词分别指什么

第一个任务跑通后，下面这些词会好理解很多：

  • Skills：可复用工作流包；平时只加载名称与简介，真正用到才读全文。
  • Automations：后台定时或重复任务。
  • MCP：连接外部工具与数据的协议。
  • Worktree：同一 Git 仓库里并行、互不干扰的任务隔离。
  • Cloud：把任务丢到云端后台跑，并可与 GitHub 协作。

小结

学 Agent 工具最常见的误区，是先把每个按钮研究明白再动手。更有效的路径是：选对形态、装好、登录、选 Local 项目、发一条能看见 diff 的指令，并在审批弹窗上建立信任节奏。

把第一个本地任务跑通，比背一百个功能名都管用。若你计划在 Codex 里长期使用多模型，也可以先看一眼 AIGoCode 的接入与分组说明：AIGoCode 使用指南。

参考链接

Codex 上手教程：从安装到跑通第一个本地任务