⌕
Beginner Guide · 2026 · Codex Desktop

Codex 桌面端
小白使用路线图

从第一次打开，到跑通第一个项目。给刚安装 Codex、但不知道能拿来干什么的人。

适合：零基础 / AI 工具新手 版本：2026 小白探索版 建议：先练习文件夹，再处理真实项目
入口 01 →
刚装好，不知道从哪开始
安全开始 + 第一条指令
入口 02 →
装好了但连不上模型
API 配置 + 报错排查
入口 03 →
想知道 Codex 能干什么
小白探索地图（8 个方向）
入口 04 →
直接复制提示词
常用提示词速查库
💡 小白第一原则：先让 Codex 解释，再让 Codex 修改；先在练习文件夹里试，不要直接处理重要文件。
01Codex 是什么，不是什么认知
📌 一句话理解

Codex 是 OpenAI 推出的 AI 编程代理（AI Agent）。你可以把它理解成一个围绕「项目文件夹」工作的 AI 助手。

它不只是聊天——它可以帮你阅读项目文件、修改文件、运行命令、检查结果，还能生成说明文档、管理多个并行任务线程，甚至在 macOS 上直接操控屏幕上的应用。

2026 年 4 月更新后，Codex 新增了电脑控制（Computer Use）、内置浏览器、90+ 插件和记忆功能，已经从纯编程工具扩展为更通用的桌面 AI 助手。

⚠️ 不要这样理解它

Codex 不是万能电脑管家，不要把它理解成可以随便操控你电脑所有内容的工具。

它更适合围绕一个明确的项目文件夹工作。在安全默认设置下，它只能访问被授权的目录。

如果你只是刚开始，不要一上来追求复杂自动化，先让它读懂一个简单项目，跑通一个小工具，再逐步探索更多能力。

🎯
新手路径：认识 Codex → 连通模型 → 读项目 → 做小工具 → 再探索自动化
📊 Codex 桌面端 vs 网页版 ChatGPT 对比
维度网页版 ChatGPTCodex 桌面端
主要交互方式你问，它答；对话框形式你给项目文件夹，它帮你看、改、跑、查
是否能访问本地文件❌ 不能✅ 可以（需要授权目录）
是否能修改本地文件❌ 不能✅ 可以（有沙箱权限控制）
是否能执行命令/脚本❌ 不能✅ 可以（可配置审批策略）
是否适合做本地项目❌ 不适合✅ 专门为此设计
会话持久性关闭标签即丢失上下文项目历史本地保存，可续接
是否能并行执行任务❌ 一次一个✅ 多个 Agent 并行工作
操控屏幕应用（macOS）❌✅（Computer Use，2026 年 4 月起）
小白应该怎么用问问题、头脑风暴、写内容做项目、整理文件、自动化、学编程
02安装与登录安装
🖥️ Codex 桌面端（推荐新手）

适合：小白、喜欢图形界面的人

前往 OpenAI 官方 Quickstart 下载安装。官方说明 Codex App 支持 macOS 和 Windows；Intel Mac 需要选择 Intel 版本。

安装后选择项目文件夹，可视化管理任务和项目线程，适合管理多个并行任务。

官方 Quickstart macOS Apple Silicon macOS Intel Windows
💡
这份指南以桌面端为主。如果你下载的是命令行 CLI，部分界面描述会有所不同，但提示词和配置逻辑相同。
💻 Codex CLI（命令行版）

适合：已经会一点终端操作的人

CLI 官方安装说明
bash
# npm 安装（需 Node.js 18+）
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

codex --version

CLI 在终端里运行，围绕当前目录工作。配置文件路径与桌面端相同。

🔑 登录方式选哪个？

ChatGPT 账号登录（推荐新手）：配置最简单，适合大多数小白，少改配置。

API Key 登录：适合走 API 计费、接第三方 API 或自定义模型源的人。

⚡
小白建议：如果能正常用 ChatGPT 账号登录，就先不要折腾第三方 API。模型连接失败才跳到下一节。
📋
套餐说明：ChatGPT Free 和 Go 用户可免费体验 Codex（限时）；Plus 及以上可解锁完整桌面端功能；Pro 用户有更高使用配额。需要多 Agent 并行、Goal Mode 等高级功能需要 Plus 及以上套餐。
02P系统可安装插件中文对照表插件
🔌
先说明：Codex 插件目录会随版本变化。官方文档说明，插件可以把 Skills、App 集成和 MCP servers 打包成可复用工作流；在 Codex App 中打开 Plugins 浏览安装，CLI 中可运行 /plugins 打开插件列表。下面是小白优先认识的一批常见插件/插件类型，不建议一次性全装。
⚠️
安装原则：用到哪个装哪个。凡是涉及邮箱、云盘、Slack、浏览器、GitHub、数据库、部署平台的插件，都可能要求你登录外部服务或授权数据访问。安装前先让 Codex 解释权限和用途。
📋 插件安装通用流程

桌面端：打开左侧 Plugins，搜索插件，进入详情，点击添加/安装；如果需要外部服务授权，按提示登录。

CLI：进入 Codex 后运行 /plugins，在插件列表中搜索、查看详情、安装或启用。

🧭 安装插件前先让 Codex 判断
插件安装▾
我想安装一个 Codex 插件。 请先不要安装，先帮我判断： 1. 当前任务是否真的需要这个插件？ 2. 这个插件会访问哪些数据或外部服务？ 3. 它需要登录或授权吗？ 4. 有没有不用插件也能完成的替代方案？ 5. 如果要安装，请告诉我在桌面端和 CLI 中分别怎么操作。 确认后再让我决定是否安装。
🌐内置浏览器Browser
预览本地网页、打开公开页面、让 Codex 对页面做检查或评论。适合网页、小工具、UI 调整。
网页预览 / 本地开发通常不需要外部账号
📋 让 Codex 安装/启用这个插件
内置浏览器▾
我想安装/启用 Browser 插件。请先说明它能帮我做什么、会访问哪些网页、如何管理允许和阻止的网站。然后指导我在 Codex 插件目录里安装或启用它，并给我一个测试任务：打开当前项目的本地网页预览并指出 3 个可改进点。
🧩Chrome 扩展Chrome Extension
让 Codex 使用你已登录的 Chrome 状态处理网页任务，例如需要登录态的网站。适合 Gmail、内部后台、CRM 等。
登录态网页 / 浏览器任务需要浏览器扩展和网站授权
📋 让 Codex 安装/启用这个插件
Chrome 扩展▾
我想让 Codex 使用 Chrome 扩展处理需要登录态的网页。请先说明权限风险、会访问哪些网站、如何限制授权范围。然后指导我安装扩展，并先用一个低风险公开网页做测试，不要访问隐私页面。
📧邮箱Gmail
总结未读邮件、整理待办、草拟回复、做收件箱 triage。适合信息管理和自动化。
邮件管理 / 草拟回复需要 Gmail 授权
📋 让 Codex 安装/启用这个插件
邮箱▾
请帮我安装/启用 Gmail 插件。安装前先说明它能读取和操作哪些邮件数据、会不会直接发送邮件、如何只生成草稿。安装后先做一个安全测试：只总结今天未读邮件，不发送、不删除、不归档。
📁谷歌云盘/Docs/Sheets/SlidesGoogle Drive
在 Drive、Docs、Sheets、Slides 中查找资料、整理文档、汇总表格、生成报告。
云盘文档 / 办公资料需要 Google 账号授权
📋 让 Codex 安装/启用这个插件
谷歌云盘/Docs/Sheets/Slides▾
请帮我安装/启用 Google Drive 插件。先说明它会访问哪些 Drive 文件、是否可以限制范围。安装后先做安全测试：只列出我指定文件夹里的文件类型和数量，不修改文件。
💬团队沟通Slack
总结频道、整理讨论、草拟回复、提取待办。适合团队消息过载。
频道总结 / 消息待办需要 Slack 工作区授权
📋 让 Codex 安装/启用这个插件
团队沟通▾
请帮我安装/启用 Slack 插件。先说明需要哪些权限，以及是否会发送消息。安装后先做安全测试：只总结我指定频道最近一天的公开讨论，不发送任何消息。
🐙代码仓库/Issue/PRGitHub
读取仓库、分析 issue、生成 PR 说明、辅助代码审查。适合项目协作。
代码仓库 / Issue / PR需要 GitHub 授权
📋 让 Codex 安装/启用这个插件
代码仓库/Issue/PR▾
请帮我安装/启用 GitHub 插件。先说明它能访问哪些仓库和权限范围。安装后先做安全测试：只读取我指定仓库的 README 和 issue 列表，生成摘要，不创建 PR，不修改代码。
🦊GitLab 问题管理GitLab Issues
读取 GitLab issue、整理任务、生成修复计划或周报。
GitLab 项目 / Issue需要 GitLab 授权
📋 让 Codex 安装/启用这个插件
GitLab 问题管理▾
请帮我安装/启用 GitLab Issues 插件。先说明权限和数据范围。安装后先做安全测试：读取我指定项目的 open issues，按优先级生成整理报告，不修改任何 issue。
📌产品需求/任务Linear
整理需求、生成任务拆解、同步项目进度。适合产品和开发任务管理。
需求管理 / 项目任务需要 Linear 授权
📋 让 Codex 安装/启用这个插件
产品需求/任务▾
请帮我安装/启用 Linear 插件。先说明它能读取和修改哪些任务。安装后先做安全测试：只读取我指定团队的待办任务，生成摘要和下一步建议，不修改状态。
🧱Jira/Atlassian 项目管理Atlassian Rovo / Jira
查询需求、整理缺陷、生成迭代计划。适合使用 Jira 的团队。
Jira 任务 / 迭代需要 Atlassian 授权
📋 让 Codex 安装/启用这个插件
Jira/Atlassian 项目管理▾
请帮我安装/启用 Atlassian Rovo 或 Jira 相关插件。先说明权限和数据范围。安装后先做安全测试：读取我指定项目的 issue 摘要，不改状态、不评论、不分配人员。
📄微软办公套件Microsoft Suite
处理 Word、Excel、PowerPoint、Outlook、OneDrive 等办公内容。适合职场资料整理。
办公文档 / 表格 / 邮件需要 Microsoft 账号授权
📋 让 Codex 安装/启用这个插件
微软办公套件▾
请帮我安装/启用 Microsoft Suite 插件。先说明它能访问哪些 Microsoft 资料。安装后先做安全测试：只读取我指定的一个测试文档或测试表格，生成摘要，不修改原文件。
🎨设计文件Figma
读取设计稿上下文、辅助前端实现、生成组件说明。适合 UI 到代码。
UI 设计 / 前端实现需要 Figma 授权
📋 让 Codex 安装/启用这个插件
设计文件▾
请帮我安装/启用 Figma 插件。先说明它能读取哪些设计文件。安装后先做安全测试：读取我指定的 Figma 文件或页面，输出页面结构和前端实现建议，不修改设计稿。
🚀部署平台Render
查看部署状态、辅助配置 Web 服务、排查部署失败。适合小项目上线。
部署 / 服务状态需要 Render 授权
📋 让 Codex 安装/启用这个插件
部署平台▾
请帮我安装/启用 Render 插件。先说明它能访问哪些服务和部署信息。安装后先做安全测试：只读取我指定服务的状态和最近一次部署日志，不触发重新部署。
🗄️Postgres 数据库Neon by Databricks
查看数据库结构、辅助生成 SQL、排查连接问题。适合数据库项目。
数据库 / SQL需要数据库服务授权
📋 让 Codex 安装/启用这个插件
Postgres 数据库▾
请帮我安装/启用 Neon 插件。先说明数据库访问风险和权限范围。安装后先做安全测试：只读取数据库 schema，不修改数据、不执行删除或更新语句。
🔁持续集成CircleCI
查看 CI 构建失败、分析日志、生成修复建议。适合项目测试和部署流程。
CI / 构建日志需要 CircleCI 授权
📋 让 Codex 安装/启用这个插件
持续集成▾
请帮我安装/启用 CircleCI 插件。先说明它能读取哪些构建日志和项目。安装后先做安全测试：只读取最近一次失败构建日志，生成排查建议，不重新触发构建。
🐇代码审查CodeRabbit
读取代码审查反馈、整理建议、辅助修复。适合 PR review。
代码审查 / PR 反馈需要相关平台授权
📋 让 Codex 安装/启用这个插件
代码审查▾
请帮我安装/启用 CodeRabbit 插件。先说明它能访问哪些审查信息。安装后先做安全测试：只读取我指定 PR 的审查摘要，生成修改建议，不提交代码。
🎬代码生成视频Remotion
用代码生成视频/动效页面，适合前端可视化和内容创作。
视频生成 / 前端动效可能需要 Node.js/项目依赖
📋 让 Codex 安装/启用这个插件
代码生成视频▾
请帮我判断是否需要安装 Remotion 插件或相关依赖。先说明它适合做什么、会安装哪些包、如何验证。确认后再帮我创建一个最小 Remotion 示例，不要改动其他项目文件。
⚡能力增强插件Superpowers
用于增强 Codex 工作流，具体能力以插件目录说明为准。适合想探索进阶能力的人。
进阶探索 / 工作流增强按插件说明授权
📋 让 Codex 安装/启用这个插件
能力增强插件▾
请帮我查看 Superpowers 插件详情。不要直接安装。请先总结它的能力、需要的权限、适合哪些任务、是否适合新手。确认后再指导安装和做一个低风险测试。
🧠
小白建议：第一轮只装 Browser 或一个你真正需要的插件。邮箱、云盘、Slack、GitHub、数据库、部署平台这类插件都涉及授权，先做低风险测试，再做真实任务。
03模型连接方式 & 第三方 API 配置API配置
A · ChatGPT 账号登录

适合：有 ChatGPT 账号、能正常访问 OpenAI、想少折腾配置的人

✅ 配置简单，小白友好，不容易写错配置

⚠️ 依赖账号权限；部分地区或网络环境连接可能不稳定

B · OpenAI API Key

适合：有 OpenAI Platform API Key、接受按用量计费的人

✅ 按量付费，灵活；可在 CLI 中精确控制模型

⚠️ Key 不要泄露；需检查余额；env_key 必须指向环境变量，不能直接写 Key 字符串

C · 第三方 / OpenAI 兼容 API

适合：官方接口连接不稳定、想用其他模型服务商的人

✅ 可接入国内外兼容服务商；支持本地模型（Ollama 等）

⚠️ 需修改配置文件；容易出现 401/404；wire_api 选错是最常见错误

🚫
重要：不要同时乱混多个 Key、多个 provider、多个模型名。先保证一个模型源能跑通，再考虑多 provider 配置。
📁 配置文件位置
路径
# macOS / Linux（用户级，影响所有项目）
~/.codex/config.toml

# Windows（用户级）
C:\Users\你的用户名\.codex\config.toml

# 项目级（只影响当前项目）
你的项目目录/.codex/config.toml
⚠️
重要限制：根据官方文档，model_provider、model_providers、base_url 等关键字段只在用户级配置（~/.codex/config.toml）中生效，项目级配置会忽略这些字段。小白优先修改用户级配置，修改前先备份。
📝
不同版本 Codex 配置字段可能略有差异，请以当前版本和官方文档（developers.openai.com/codex）为准。
🔌 wire_api 选什么？（最容易搞错的一项）

wire_api 决定 Codex 用哪种 API 协议与模型通信：

wire_api 值协议适用场景
responsesOpenAI Responses API官方 OpenAI / 兼容 Responses API 的服务商
chatChat Completions API第三方服务商、国内 API、本地模型（最常用）
❗
如果第三方 API 报 404，先检查 wire_api 是否应该改为 "chat"。这是最常见的配置错误。
🔎
Codex 原生使用 Responses API（wire_api = "responses"）。大多数第三方和开源服务商使用 Chat Completions API（wire_api = "chat"）。如果不确定，查服务商文档里支持的接口类型。
⚙️ 通用第三方 API 配置模板
~/.codex/config.toml
# 顶层：指定使用的模型和 provider 名称
model = "your-model-name"         # 服务商支持的模型名，不能自己乱编
model_provider = "my_api"       # 你给这个 provider 起的名字（随意，但要和下面一致）

# Provider 定义块（必须在顶层，不能放在 profiles 里）
[model_providers.my_api]
name = "My Custom API"            # 展示名，随意
base_url = "https://api.example.com/v1"  # 服务商提供，通常以 /v1 结尾
env_key = "MY_API_KEY"            # 环境变量名，不是 Key 本身
wire_api = "chat"                 # 第三方通常用 "chat"；官方 OpenAI 用 "responses"
🔒
安全红线：不要把 API Key 明文写进 config.toml。env_key 只能写环境变量的名称（如 MY_API_KEY），Codex 运行时会从环境变量里读取真正的 Key。
🌍 设置环境变量（存放真正的 API Key）
macOS / Linux (zsh/bash)
# 当前终端会话临时生效
export MY_API_KEY="你的 API Key"

# 长期生效（写入 shell 配置）
echo 'export MY_API_KEY="你的 API Key"' >> ~/.zshrc
source ~/.zshrc
Windows PowerShell
# 永久写入用户环境变量
setx MY_API_KEY "你的 API Key"

# 设置后需重启终端/重启 Codex 才生效
⚠️
设置环境变量后，需要重新打开终端或重启 Codex 才能生效。
🔍 让 Codex 检查当前配置（不修改）
检查配置▾
请帮我检查当前 Codex 配置，但不要修改文件。 请告诉我： 1. 当前使用的是哪个 model 2. 当前使用的是哪个 model_provider 3. 配置文件路径在哪里 4. base_url 是否看起来像 OpenAI 兼容接口（通常以 /v1 结尾） 5. wire_api 是 chat 还是 responses，是否适合当前服务商 6. env_key 对应的环境变量是否已经设置 7. 如果配置有问题，请先解释原因，不要直接修改
✏️ 配置前先确认 5 个问题
配置前▾
请先不要修改配置文件。 在帮我配置第三方 API 之前，请先确认： 1. 我使用的是 Codex 桌面端、CLI 还是 IDE 扩展？ 2. 我的系统是 Windows、macOS 还是 Linux？ 3. 服务商提供的 base_url 是什么？（请从服务商官方文档复制） 4. 服务商支持的模型名是什么？ 5. 服务商使用的接口类型是 Chat Completions（wire_api = "chat"）还是 Responses API？ 确认完以上 5 点，再给我配置方案。
🛠️ 安全修改配置文件
修改配置▾
请帮我修改 Codex 的 config.toml，用于连接一个第三方 OpenAI 兼容 API。 要求： 1. 不要覆盖原配置，先备份为 config.toml.bak 2. 使用我下方提供的 base_url、model、env_key、wire_api 3. 不要把 API Key 明文写入配置文件 4. model_providers 块必须写在顶层，不要放在 profiles 内部 5. 修改完成后告诉我改了哪些内容，并给我一条验证连接的测试命令 我的配置信息： - base_url: （填写服务商提供的接口地址） - model: （填写服务商支持的模型名） - env_key: （填写你准备用的环境变量名） - wire_api: （填 chat 或 responses，不确定就填 chat）
04常见报错排查报错
📌
点击报错卡片展开详细排查步骤和可复制的提示词。遇到报错时，先看报错类型，再对号入座，不要慌乱乱点。
401 Unauthorized — 身份验证失败
401 ▾
可能原因：
  • API Key 写错或已过期
  • 环境变量没有生效（重启终端了吗？）
  • env_key 的名称与实际环境变量名不一致
  • Key 余额不足或账号被限制
  • OpenAI 官方 Key 和第三方 API Key 混用了
📋 401 排查提示词
▾
Codex 报错 401 Unauthorized。 请帮我排查，不要修改文件。 请重点检查： 1. config.toml 中 env_key 写的是什么名称 2. 对应的环境变量是否已经设置（如何验证？） 3. model_provider 是否指向了正确的 provider 定义 4. 是否可能把 OpenAI 官方 Key 和第三方 API Key 混用了 5. 有没有可能 Key 本身余额耗尽 请按步骤告诉我怎么排查，先不要改文件。
404 Not Found / model not found — 找不到模型或接口
404 ▾
可能原因：
  • 模型名写错（最常见！要从服务商文档复制）
  • base_url 写错，或者少了结尾的 /v1
  • wire_api 应该是 "chat" 但写成了 "responses"
  • 服务商不支持这个模型名
📋 404 排查提示词
▾
Codex 报错 404 或 model not found。 请帮我检查 config.toml，不要直接修改。 请判断： 1. model 名称是否可能写错（要严格匹配服务商文档） 2. base_url 是否可能少了 /v1 3. wire_api 当前是什么，第三方 API 通常应该是 "chat" 4. 当前 provider 配置是否指向了正确的接口地址 请给我一个最小修改方案，先解释原因。
network error / timeout — 网络连接失败
网络 ▾
可能原因：
  • 网络无法访问目标 API（需要代理？）
  • base_url 地址写错
  • 服务商接口临时不可用
  • 沙箱网络权限限制
📋 网络错误排查提示词
▾
Codex 连接模型时出现 network error 或 timeout。 请帮我排查，先不要修改配置： 1. base_url 格式是否正确（是否以 /v1 结尾） 2. 当前网络是否可能访问不到该 API 3. 是否需要代理才能访问 4. 是否是 Codex 沙箱的网络权限限制 5. 给我一条最小化的命令行测试，验证 API 是否连通（curl 即可，不要涉及 Key）
invalid_request_error — 请求格式不支持
格式 ▾
可能原因：
  • wire_api 选错（Responses API 字段和 Chat Completions 字段不同）
  • 模型不支持 Codex 发送的某些参数
  • 服务商不完全兼容，过滤了某些字段
  • 上下文长度超限
📋 invalid_request 排查提示词
▾
Codex 报 invalid_request_error。 请帮我判断： 1. 当前 wire_api 是什么，是否和服务商接口类型匹配 2. 服务商是否支持 Codex 发送的所有请求参数 3. 是否有 OpenAI 专属字段需要过滤（有些 LiteLLM 网关需要 drop_params: true） 4. 是否是上下文长度超限 请给我一个保守的修复方案，先解释可能原因。
rate limit / quota exceeded — 超出限额
限流 ▾
可能原因：
  • 账号余额不足
  • 请求太频繁被限流
  • 套餐使用配额用完
  • 一次性读入文件太多，消耗太快
📋 限流排查提示词
▾
Codex 报 rate limit 或 quota exceeded。 请帮我判断可能原因，并给我一个降低消耗的使用方案： 1. 是否要切换到更便宜/更快的模型 2. 是否要减少每次请求的文件数量 3. 是否要把大任务拆成多步执行 4. 是否要避免一次性让 Codex 读太多文件 请按优先级给我建议。
TOML parse error / config parse error — 配置文件格式错误
TOML ▾
可能原因：
  • 引号漏了或多了
  • 表头写错（如 [model_providers] 写成 [model-providers]）
  • 中英文标点混用（中文引号"" vs 英文引号""）
  • model_providers 块放错位置（必须在顶层）
📋 TOML 格式检查提示词
▾
Codex 提示 config.toml 解析失败。 请检查下面这份配置的 TOML 格式问题。 要求： 1. 不要输出我的 API Key 2. 找出所有语法错误 3. 检查 model_providers 是否在顶层（不在 profiles 内部） 4. 给出修正后的安全版本（用占位符替代 Key） 5. 解释每一项配置的作用 【把 config.toml 内容粘贴到这里，先删除 API Key 再粘贴】
command not found: codex — 找不到命令
CLI ▾
可能原因：
  • 只装了桌面端，没有安装 CLI
  • CLI 安装路径没有加入 PATH
  • 终端没有重启
💡
桌面端和 CLI 是两个不同的程序。桌面端装好不代表终端里有 codex 命令。如果只用桌面端，不需要在意这个报错。
📋 command not found 排查提示词
▾
我的终端提示 command not found: codex。 请帮我判断： 1. 桌面端和 CLI 的区别是什么，我现在需要哪个 2. 如果需要 CLI，如何验证是否已安装 3. 如果没安装，安装步骤是什么（npm install -g @openai/codex） 4. 安装后如果还报这个错，PATH 可能怎么配置 请一步步说，不要直接执行危险命令。
permission denied / sandbox blocked — 权限被拒绝
权限 ▾
可能原因：
  • Codex 想访问授权目录之外的路径
  • 沙箱安全限制（这是正常的保护机制）
  • 尝试操作系统目录或受保护文件
📋 权限问题排查提示词
▾
Codex 提示 permission denied 或 sandbox blocked。 请帮我判断： 1. 它想访问哪个路径 2. 这个路径是否属于当前项目目录 3. 是否需要换到练习文件夹操作 4. 有没有更安全的替代方案，不需要跨越权限边界 注意：不要建议我直接关闭所有安全限制。
05第一次打开：界面地图界面
🗺️
第一次打开不需要把每个按钮都学会。先学会三件事：选项目文件夹、输入需求、看改动预览。
区域 01
项目 / 文件夹区域
显示当前 Codex 正在处理哪个项目文件夹。小白第一步：先在这里选一个练习文件夹，不要直接绑定重要项目。
区域 02
线程 / 对话区域
每个任务可以理解成一个独立线程。可以同时跑多个线程（Pro 功能），互不干扰，类似多个聊天窗口。
区域 03
输入框
写需求的地方。可以是一句话，也可以是详细描述。按 Enter 提交，Shift+Enter 换行。
区域 04
执行过程 / 日志区域
看 Codex 正在做什么——读了哪些文件、执行了什么命令、思考过程。遇到问题先看这里。
区域 05
Diff / 改动预览
显示它改了哪些文件、改了哪些行。每次修改后都要看这里！绿色是新增，红色是删除。
区域 06
Preview / 浏览器预览
如果是网页项目，可以直接在这里查看效果，无需手动打开浏览器。
区域 07
Goal Mode（目标模式）
2026 年 5 月正式上线。设定一个长期目标，Codex 可以持续推进数小时乃至数天，适合复杂多步任务。新手先了解即可。
区域 08
Appshots（macOS）
同时按下两个 Command 键，可以把当前最前面的应用截图发给 Codex，让它直接从截图里理解上下文，无需手动复制粘贴。
06安全开始：练习文件夹安全
🚫 不要直接绑定这些目录

桌面、下载、Documents、系统目录、正在进行的工作项目。这些地方出错代价高，新手不要一开始就在这里练习。

✅ 推荐：创建专用练习文件夹
bash — 创建练习目录
# 在合适的地方创建一个隔离的练习文件夹
mkdir ~/codex-demo
cd ~/codex-demo

# 然后在 Codex 桌面端里选这个文件夹作为项目

里面可以放：index.html、style.css、notes.md 等简单文件。

🏗️ 让 Codex 初始化练习文件夹
安全开始▾
请在当前目录创建一个适合新手练习的小项目。 要求： 1. 创建 index.html、style.css、notes.md 2. index.html 页面内容简单，不依赖外部网络和框架 3. notes.md 里写清楚这是练习项目，不含真实数据 4. 不要操作当前目录之外的任何文件 完成后告诉我每个文件的作用。
⚠️
安全三原则：重要文件先备份；第一次练习只用空文件夹；不要让 Codex 操作系统目录或你不了解的目录。
07三步指令法：先读 → 计划 → 修改指令
❌
新手最常犯的错：打开 Codex，第一条指令就让它"帮我优化这个项目"或"把这个功能加进去"——然后发现它改了一堆不该改的地方。正确做法是先读、再计划、最后小步修改。
1
先读项目
让 Codex 理解项目，不动任何文件
2
制定计划
让它说清楚准备改什么，你确认
3
小步修改
一次只改一个小目标，随时可回退
📖 第一步：先读项目
Step 1▾
请先阅读当前项目结构，不要修改任何文件。 用小白能懂的话告诉我： 1. 这个项目里有哪些文件，每个文件大概是做什么的 2. 这个项目整体是用来做什么的 3. 给我 3 个适合新手接下来操作的建议
📋 第二步：先做计划
Step 2▾
请基于当前项目，帮我制定一个修改计划。 先不要改文件，只告诉我： 1. 你准备修改哪些文件 2. 每个文件为什么要改 3. 改完会得到什么效果 4. 有没有需要我确认的地方 等我确认后再执行。
✏️ 第三步：小步修改
Step 3▾
按刚才确认的计划，只修改第一个小目标。 要求： 1. 每次修改尽量小步进行 2. 只改必要的文件，不要顺带修改其他内容 3. 完成后告诉我你改了哪些地方 4. 如果遇到问题，先停下来解释，不要自作主张大范围修改
🐛 遇到报错时的处理方式

遇到报错时，不要连续乱试。先让 Codex 解释错误，再给出排查方案。

🔍 报错时的标准提示词
报错处理▾
请先解释这个报错是什么意思，不要立刻修改文件。 请给我： 1. 这个报错可能的原因（按可能性排序） 2. 建议的排查顺序 3. 最小修改方案（改动越小越好） 4. 修改前需要备份哪些文件
08小白探索地图：装好以后能干什么探索
🗺️
每张卡片点击展开详细说明和配套提示词。建议从难度 ★ 的方向开始，先跑通一个，再探索其他。
🌐 网页与小工具★ 最推荐入门
做个人介绍页、计算器、工具导航、简单 HTML 小工具
HTMLCSSJS
适合谁完全零基础；想有个可以展示的作品
能做什么静态网页、计算器、颜色选择器、简单工具页
难度★ 无需任何基础
需要依赖第一步不需要，纯 HTML/CSS/JS 即可
📋 判断是否需要依赖
▾
请检查当前任务是否真的需要前端工程化（Node.js、Vite、React 等）。 如果只是做一个简单网页或小工具，请优先使用纯 HTML、CSS、JavaScript，不要安装额外依赖。 如果确实需要框架，请先解释原因，再等我确认后安装。
🚀 第一次探索提示词
▾
请在当前文件夹里创建一个简单的静态网页小工具。 要求： 1. 只使用 HTML、CSS、JavaScript，不要安装任何依赖 2. 生成 index.html、style.css、script.js 三个文件 3. 页面适合手机端打开，布局清晰 4. 完成后告诉我每个文件的作用，以及如何在浏览器里打开
📁 本地文件整理
文件分类、批量重命名、生成目录清单
文件管理Python
适合谁文件夹乱糟糟、想整理素材/下载的人
能做什么扫描分析、生成整理计划、批量重命名
难度★★ 需要先生成报告再确认
需要依赖一般不需要；Python 标准库即可
🚀 第一次探索提示词
▾
请先扫描当前文件夹，不要修改任何文件。 帮我生成一份 files-report.md，列出： 1. 文件总数和类型分类 2. 每类文件数量 3. 可能需要整理的文件（重复名、命名混乱等） 4. 下一步整理建议 注意：只读取文件名，不要打开或修改文件内容。
⚠️
正式改名前先生成 rename-plan.md，确认后再执行，不要直接重命名。
📝 文档整理与知识库
整理 Markdown、生成摘要、README、小型知识库
Markdown笔记
适合谁有大量笔记/文档、想整理归纳的人
能做什么生成目录、摘要、README、知识索引
难度★ 最简单，纯文本处理
需要依赖md/txt 不需要；docx/pdf 可能需要额外工具
🚀 第一次探索提示词
▾
请阅读当前文件夹中的 Markdown 或文本文件，不要修改原文件。 生成 knowledge-index.md，内容包括： 1. 每个文件的主题和主要知识点 2. 可以合并或关联的内容 3. 建议的目录结构 4. 各文件之间的关系
📊 表格与数据清洗
CSV/Excel 去重、排序、格式统一、统计汇总
pandasopenpyxlPython
适合谁有 Excel/CSV 数据要整理的人
能做什么去重、筛选、统计、格式转换、合并表格
难度★★ 需要安装 Python 依赖
需要依赖pandas、openpyxl（需提前确认）
🚀 第一次探索提示词
▾
请先读取当前文件夹中的表格文件，不要覆盖原文件。 帮我生成 data-check-report.md，内容包括： 1. 发现的表格文件列表 2. 每个表格的列名 3. 是否有空值或重复数据 4. 建议的清洗步骤 所有操作结果保存为新文件，不要覆盖原始表格。
⚙️ 自动化脚本
批量生成文件、备份、日报模板、定时整理
Python脚本
适合谁有重复性手动操作、想解放双手的人
能做什么批量处理、定时任务、文件监控、自动备份
难度★★★ 先只读，再逐步开放权限
需要依赖优先 Python 标准库；定时任务用系统工具
🚀 第一次探索提示词
▾
请帮我写一个安全的 Python 自动化脚本。 目标：扫描当前文件夹，把文件列表输出为 file-list.md。 要求： 1. 不删除文件 2. 不重命名文件 3. 不移动文件 4. 只读取文件名和大小，生成报告 5. 完成后告诉我如何运行这个脚本
🔗 网页信息收集
整理公开网页链接、标题、学习资料、信息汇总
MCPrequests
适合谁想整理学习资料、竞品信息的人
能做什么整理链接清单、生成摘要、信息分类
难度★★ 手动提供内容最简单
需要依赖手动提供网页内容不需要；自动抓取需 MCP 或 requests
🚀 第一次探索提示词
▾
我会提供几个网页链接（我自己手动粘贴内容给你）。 请先不要自动访问任何网址。 帮我设计一个信息收集表格模板，包含： 1. 标题 2. 链接 3. 主要内容（我手动填写） 4. 适合谁 5. 可行动建议 生成为 info-collection-template.md
🖼️ 图片 / 素材批处理
批量重命名、生成清单、压缩、格式转换
PillowPython
适合谁设计师、有大量图片素材需要整理的人
能做什么清单、重命名、压缩、格式转换、尺寸分类
难度★★ 先备份原图再操作
需要依赖扫描清单不需要；压缩/转换需要 Pillow
🚀 第一次探索提示词
▾
请扫描当前文件夹里的图片文件，不要修改任何原图。 生成 image-assets-report.md，列出： 1. 图片数量和格式分布 2. 文件大小统计 3. 可能适合压缩的图片（大于 1MB 的） 4. 下一步处理建议 如果需要安装 Pillow，请先告诉我用途和安装命令，等我确认。
📚 项目学习与代码解释
看懂项目、解释代码、生成学习路线、README
学习文档
适合谁拿到别人项目不知道从哪看起的人
能做什么解释项目结构、代码注释、学习路线、README
难度★ 只读不改，最安全
需要依赖通常不需要
🚀 第一次探索提示词
▾
请阅读当前项目结构，不要修改文件。 用小白能懂的话生成 project-guide.md，内容包括： 1. 这个项目是做什么的 2. 每个主要文件的作用 3. 运行这个项目需要什么环境或依赖 4. 作为新手应该从哪里开始阅读 5. 下一步学习建议
09依赖安装助手依赖
🔑 核心原则

能不装就先不装，能先读就先不改，能先备份就先备份。每次安装前都让 Codex 先解释清楚。

📋 各方向依赖一览
探索方向优先不装也能试可能需要安装安装前提醒
🌐 静态网页HTML/CSS/JSNode.js、Vite、React简单网页不要一上来装框架
📁 文件整理系统能力或 Python 标准库一般无需先生成报告，不要直接改名
📝 文档整理md、txt 直接处理python-docx、PDF 工具不要覆盖原文档
📊 表格清洗CSV 可直接检查pandas、openpyxl不要覆盖原表格
⚙️ 自动化脚本Python 标准库schedule、watchdog先只读，不删除不移动
🔗 网页信息手动提供链接内容MCP 浏览器工具、requests注意网站规则，先手动提供
🖼️ 图片批处理先生成清单不需要Pillow先备份原图再操作
📚 项目解释不需要项目自身依赖先读项目，不要先运行命令
❓ 安装依赖前先问 5 个问题
安装前▾
请先不要安装任何依赖。 回答以下 5 个问题： 1. 当前任务是否真的需要安装依赖？ 2. 如果不安装，能否用系统自带能力完成？ 3. 如果必须安装，要安装哪些？ 4. 每个依赖分别解决什么问题？ 5. 安装后如何验证成功？ 等我确认后再执行安装。
🔍 检查当前环境再安装
环境检查▾
我准备安装本任务需要的依赖。 请先检查当前系统环境，并输出： 1. 当前系统类型（macOS/Windows/Linux） 2. 当前项目使用的语言或工具 3. 建议安装的依赖列表 4. 每个依赖的具体用途 5. 安装命令 6. 验证安装成功的命令 在我确认前不要执行任何安装。
✅ 确认后执行安装
执行安装▾
请按照刚才确认的方案安装依赖。 要求： 1. 只安装本任务必需的依赖 2. 不要全局安装，除非必须（并说明原因） 3. 安装完成后运行验证命令 4. 如果安装失败，不要反复重试，先解释失败原因 5. 最后生成 install-log.md，记录安装了什么、为什么安装、如何验证
🔌 安装 MCP 工具前先问清楚
MCP前▾
我想为 Codex 配置一个 MCP 工具。 请先不要安装，告诉我： 1. 这个 MCP 工具解决什么问题 2. 是否真的需要它，有没有更简单的替代方案 3. 它需要哪些权限（本地文件？浏览器？网络？） 4. 安装和卸载方式是什么 5. 安装风险有哪些 确认后再给我配置步骤。
10三个入门实战案例案例
案例 01 · 生成个人介绍网页
准备空文件夹 codex-demo
预期结果生成网页文件，本地浏览器可打开
📋 复制提示词
▾
请帮我在当前文件夹里创建一个简约个人介绍网页。 要求： 1. 包含：标题、头像占位符、个人简介、技能标签、联系方式 2. 生成 index.html 和 style.css 3. 风格简洁，适合手机端浏览 4. 不使用任何外部框架或 CDN 完成后告诉我如何在浏览器里打开。
⚠️
完成后先用浏览器打开 index.html 验证效果，再进行下一步修改。
案例 02 · 修改已有 HTML 页面
准备案例 01 生成的文件，或任意已有 HTML
预期结果页面变成深色风格，保持内容不变
📋 复制提示词
▾
请阅读当前 index.html 和 style.css。 把页面改成深色风格，适合手机端竖屏展示。 要求： 1. 不要改变原有内容结构，只优化视觉样式 2. 使用深色背景、白色/浅色文字 3. 保持移动端友好的排版 4. 改完后告诉我改了哪些地方，并建议我如何在浏览器里验证效果
💡
改完后检查 Diff 区域，确认只有样式变化，没有内容被删除。
案例 03 · 生成项目 README
准备任意有文件的项目文件夹
预期结果生成一份清晰的 README.md
📋 复制提示词
▾
请阅读当前项目文件夹，不要修改其他文件。 帮我生成一份 README.md，包含： 1. 项目简介（一句话说明这是什么） 2. 文件结构（列出主要文件和各自作用） 3. 如何打开和使用 4. 后续可以优化的方向（3 条建议） 只生成 README.md，不要改动其他文件。
11避坑清单避坑
🔴 安全类：绝对不要做

① 不要把 Codex 绑定到系统目录（桌面/下载/系统盘根目录）
② 不要直接处理重要文件，先在练习文件夹测试
③ 重要资料先备份再让 Codex 操作
④ 不要让它删除文件，除非非常确认
⑤ 不要把 API Key、密码、隐私信息粘贴进提示词

🟡 操作类：容易踩的坑

① 不要一条指令塞太多需求
② 不要只说"优化一下"，要说清楚优化什么
③ 不要不看 Diff 就继续下一步
④ 出错时不要连续乱点，先让它解释
⑤ 复杂任务要拆成多个小步执行

🟡 配置类：容易出错的地方

① 不要自己猜 model 名，要从服务商文档复制
② 不要猜 base_url，从文档里复制
③ 不要把 API Key 写入截图或共享文件
④ wire_api 默认 "chat"（第三方），不是 "responses"
⑤ model_providers 块必须在 config.toml 顶层

12常用提示词速查提示词

▸ 基础操作

📖 读项目
基础▾
请先阅读当前项目结构，不要修改文件。 用小白能懂的话解释：这个项目是做什么的，主要文件有哪些，每个文件的作用是什么。
📋 制定计划
基础▾
请先制定修改计划，不要立刻改文件。 告诉我你准备修改哪些文件、每个文件为什么要改、改完会得到什么效果。 等我确认后再开始执行。
✏️ 小步修改
基础▾
请只修改必要文件，保持改动尽量小。 完成后列出修改了哪些地方，不要顺带修改其他无关内容。
🐛 查 Bug
调试▾
请根据当前报错信息分析原因。 先给我可能的原因和排查步骤，不要立刻大范围改代码。 最小修改方案是什么？

▸ 创作 & 文档

🌐 做网页
创作▾
请帮我在当前文件夹创建一个简洁网页，包含 HTML 和 CSS。 要求：适合手机端浏览，布局清晰，视觉干净，不使用外部框架。
📄 生成 README
文档▾
请阅读当前项目，生成 README.md。 内容包括：项目简介、文件结构、使用方法、后续优化建议。 先不要修改其他文件。
🔍 检查配置
配置▾
请检查我的 Codex 配置文件，不要修改。 告诉我当前 model、model_provider、base_url、wire_api、env_key 是否配置合理。 如有问题，先解释原因再给修复方案。
🧹 整理文件夹
整理▾
请扫描当前文件夹，不要修改任何文件。 生成 folder-report.md，包括：文件类型统计、重复文件、命名混乱的文件、整理建议。
📊 表格检查
数据▾
请读取当前表格文件（CSV 或 Excel），不要覆盖原文件。 生成数据检查报告：列名、空值情况、重复行、建议的清洗步骤。
13版本更新说明 & 已知问题更新
v3.0 · 2026-05
Codex 路线图 2026 小白探索版
全面覆盖桌面端使用路线。新增 API 配置急救区、wire_api 说明（第三方用 "chat"）、Goal Mode 与 Appshots 说明。完整 8 方向探索地图、依赖安装助手、可复制提示词库。
初始发布全新内容
Codex 官方 · 2026-05-22
Appshots 正式上线 + Goal Mode 转正
macOS 双击 Command 键发送截图给 Codex。Goal Mode 从实验性功能转为正式功能，可在桌面端、IDE 扩展和 CLI 中使用。
官方更新macOS
Codex 官方 · 2026-04-16
Codex for (almost) everything 大更新
新增 Computer Use（macOS）、内置浏览器、90+ 插件市场、记忆功能预览、Goal Mode（实验）、多终端标签页、远程 devbox SSH 访问。
官方更新重大更新
Codex 官方 · 2026-03-04
Windows 版发布
Codex 桌面端支持 Windows，内置 PowerShell 支持和 Windows 原生 Agent 沙箱。
官方更新Windows
⚠️ 当前已知限制
问题状态
Computer Use（电脑控制）仅 macOS；Windows 待定；EU/UK/CH 暂不支持
model_providers 字段项目级 config.toml 不生效，只能在用户级配置
第三方 API 上下文压缩非 OpenAI provider 无法使用快速压缩路径，会降级为本地摘要
Linux 支持CLI 支持；桌面端暂无官方 Linux 版本
Goal Mode已正式上线（2026-05）
📌 待完善内容

以下内容计划在后续版本中补充：

  • Computer Use 使用场景详解与安全边界
  • 90+ 插件市场常用插件推荐
  • Goal Mode 具体使用案例
  • 多 Agent 并行工作流指南
  • Appshots 实际使用场景
📝
内容基于 Codex 官方文档和社区实践整理。部分字段和功能在不同版本间可能有差异，请以当前版本实际表现和官方文档（developers.openai.com/codex）为准。