> ## Content Index
> Fetch the complete content index at: https://orbiorbi.com/news/llms.txt
> Use this file to discover other available public pages before exploring further.

# Codex 新手入门：安装、第一次任务与进阶使用
- URL: https://orbiorbi.com/news/codex-xinshou-rumen-zhinan/
- Published: 2026-10-21T20:54:20.000Z
- Updated: 2026-10-21T20:54:20.000Z
- Description: 用一份阅读记录学习 Codex：从官方安装、Orbis API 独立配置到第一次文件任务，再练习会话恢复、上下文整理、合并计划和结果审阅。每步给出操作与成功标志。
- Author: Orbis News
- Tags: API 接入与排障, #model:gpt-6.1-sol

## 先看目标：把三条记录整理成一份计划

Codex 是能读取文件、修改内容并执行命令的 AI 助手。本文使用**终端版（CLI）**，在文字窗口中完成第一次任务。

**学完要做到：** 生成 `阅读计划.md`，检查没有编造、原文没有被改，再做一次局部修改。

> 准备：可用网络，先介绍 ChatGPT 账号登录，再介绍可选的 Orbis API 接入。安装不赠送 API 额度。

## 一、下载与安装

### 1\. 打开终端，安装 Codex

- **Windows**：开始菜单搜索“PowerShell”，打开普通窗口。
- **Mac**：按 Command＋空格，搜索“终端”。
- 复制对应系统的命令，粘贴后回车。

Windows PowerShell：

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

```

macOS / Linux：

```bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh

```

这些是[官方独立安装器](https://learn.chatgpt.com/docs/codex/cli?ref=orbiorbi.com)，无需为此先装 Node.js。脚本会联网执行安装；Windows 参数仅用于本次进程，不要永久关闭系统策略。

### 2\. 检查安装是否成功

新开一个终端，输入：

```text
codex --version

```

![在终端运行 codex --version 后显示版本号](https://orbiorbi.com/news/content/images/2026/10/05-------------.webp)

*图源：*[*CodexOne*](https://codexone.cn/start/10-cli-installation?ref=orbiorbi.com)*。看命令下方的 codex-cli 和数字；0.130.0 是示例版本，不必一致。*

**成功标志：** 出现版本号，而不是“找不到命令”。

### 3\. 或者，交给已有 agent 安装

发给能执行本机命令的 agent：

> 阅读 https://learn.chatgpt.com/docs/codex/cli ，检查系统与已有安装，用适合本机的官方方式安装 Codex；保留配置、不重复安装、不永久修改系统安全策略，登录和系统授权由我处理，最后运行 codex --version 验证。

**成功标志：** 它报告版本与启动方法。普通网页聊天没有本机执行权限时，只能指导。

## 二、准备文件并接入 Orbis API

### 4\. 建一个练习目录

1. 在“文档”新建 `codex-first` 文件夹。
2. 用记事本新建 `阅读记录.txt`，复制以下内容并保存在里面。
3. 确认文件没有多出 `.txt` 后缀；Mac 使用纯文本编辑器。

```text
A：一本学习方法的书。读完第一章，想了解怎样安排复习。
B：一篇AI工具文章。还没读，准备周末阅读。
C：个人网站。想了解零基础要准备哪些内容，暂时没有资料。

```

**成功标志：** 打开文件能看到 A、B、C 三条记录。

### 5\. 先用 ChatGPT 账号登录

1. 在终端用 `cd "codex-first 的完整路径"` 进入刚才创建的文件夹，运行 `codex`。
2. 首次启动选择 **Sign in with ChatGPT**，在打开的官方网页完成账号登录与授权。
3. 回到终端，输入 `/status` 查看当前账号、模型与工作目录；使用权限和额度以账号显示为准。
4. 发送“只回复：连接成功”，确认能够收到回答。

**成功标志：** Codex 能正常回答，工作目录是 `codex-first`。[官方认证说明](https://learn.chatgpt.com/docs/auth?ref=orbiorbi.com)

接下来可以直接跳到“第一次使用：读取、生成、检查”。如果希望使用 Orbis 的模型服务，再按下一节配置；Orbis Key 不用于 ChatGPT 登录。

## 三、可选：结合 Orbis API 使用

### 6\. 从 Orbis 获取对应线路的 Key

1. 打开 [Orbis 的 GPT 6.1 Sol 模型页](https://orbiorbi.com/pricing/gpt-6.1-sol?catalogKey=model%2F91&ref=orbiorbi.com)。
2. 选择 **GPT · HA** 线路，通过页面的“获取 Key”流程取得密钥。
3. 在 Orbis“快速接入”选择这个 Key，查看 Codex 配置；线路页面的模型列表为准。

| 配置项      | 本文示例                        |
| -------- | --------------------------- |
| Base URL | https://api.orbiorbi.com/v1 |
| model    | gpt-6.1-sol                 |
| API 协议   | responses                   |
| Key 对应线路 | GPT · HA                    |

Orbis Key 绑定线路，改 `model` 不会自动换线路。API 额度在 Orbis 查看，与 ChatGPT 订阅分开；这个 Key 不是 ChatGPT 登录密码。

模型

[GPT 6.1 Sol](https://orbiorbi.com/pricing/gpt-6.1-sol?catalogKey=model%2F91&ref=news-codex-xinshou-rumen-zhinan)`gpt-6.1-sol`

查看模型信息与可用线路，获取本文 Codex API 接入所需配置。

- API 接入
- Codex

体验

**成功标志：** 你已拿到 HA 线路 Key，模型 ID 与配置匹配。不要把密钥发给 Codex 或写进练习材料。

### 7\. 建一份独立的 Orbis 配置

本文使用 Codex **0.134.0 及以上**的独立 profile（命名配置）；先用 `codex --version` 检查，旧版先按官方安装方式更新。新版不再读取旧教程里的 `[profiles.orbis]`。[官方配置说明](https://learn.chatgpt.com/docs/config-file/config-advanced?ref=orbiorbi.com#profiles)

- **Windows**：文件资源管理器地址栏输入 `%USERPROFILE%`，进入或新建 `.codex`，用记事本创建 `orbis.config.toml`；另存时选“所有文件”。
- **Mac**：Finder 按 Command＋Shift＋G，输入 `~/.codex`；没有则在个人目录新建 `.codex`，用纯文本编辑器保存 `orbis.config.toml`。
- 先复制已有 `config.toml` 为 `config-before-orbis.toml`；已有 `orbis.config.toml` 也另存副本。不要改原来的默认配置，不要把下面内容塞进项目文件夹。

将以下内容填入新建的 `orbis.config.toml`：

```toml
model = "gpt-6.1-sol"
model_provider = "orbis"
web_search = "disabled"

[model_providers.orbis]
name = "Orbis"
base_url = "https://api.orbiorbi.com/v1"
wire_api = "responses"
env_key = "ORBIS_API_KEY"

```

**成功标志：** 文件不是 `.toml.txt`。`model` 等前三行在方括号表头前；`env_key` 填变量名，不填真实 Key。先关闭内置网页搜索，接通文件任务后再确认线路支持哪些附加能力。

### 8\. 输入密钥，从练习目录启动

1. 复制 `codex-first` 完整路径，在终端用 `cd "文件夹完整路径"` 进入它。
2. 运行对应命令，出现提示后粘贴自己的 Key 并回车；输入不会显示。
3. 保留这个终端，后续恢复会话也从这里启动。

Windows PowerShell：

```powershell
$env:ORBIS_API_KEY = [System.Net.NetworkCredential]::new('', (Read-Host '粘贴 Orbis Key' -AsSecureString)).Password
codex --profile orbis

```

Mac 默认终端（Zsh）：

```bash
printf '粘贴 Orbis Key：'
read -rs ORBIS_API_KEY
printf '\n'
export ORBIS_API_KEY
codex --profile orbis

```

**成功标志：** 进入 Codex。密钥只用于当前终端及它启动的程序；新开终端需要重新输入，不要将真实 Key 写入 TOML。

### 9\. 核对状态，再做一次小请求

- 输入 `/status`，检查使用 Orbis provider、`gpt-6.1-sol` 和 `codex-first` 目录。
- 发送“只回复：连接成功”，在 Orbis 调用记录核对本次 Key、模型与线路；这次会使用 API 额度。
- 接着做下节“只读文件”练习，并再追问一句，检查文件工具与续聊是否正常。

![Codex 登录后的终端主界面与输入区](https://orbiorbi.com/news/content/images/2026/10/06--------------1.webp)

*图源：*[*CodexOne*](https://codexone.cn/start/10-cli-installation?ref=orbiorbi.com)*。只看 directory 与灰色输入区；*

**成功标志：** 正常回答、记录对应，读取文件及续聊也能完成。一次文字回复不能证明所有工具都兼容。若模型显示通用能力或无法识别，向线路方核对当前 Codex 版本与模型目录，不自行编造别名。

### 10\. 保留官方登录路线与恢复方法

- 使用 Orbis 时用 `codex --profile orbis`；不必把 Orbis Key 送进 ChatGPT 浏览器登录页。
- 想回原路线：退出并关闭终端，新开终端运行不带 profile 的 `codex`。原来没有登录时，选择 **Sign in with ChatGPT** 并完成浏览器授权。
- 如果你曾修改默认 `config.toml`，先恢复备份；每次切换后用 `/status` 核对，profile 仍会继承基础配置和受托管规则约束。

**成功标志：** 能清楚区分“通过 Orbis Key 调用”和“通过 ChatGPT 账号使用”。[官方认证](https://learn.chatgpt.com/docs/auth?ref=orbiorbi.com)与[网关设置](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway?ref=orbiorbi.com)说明了两种路径。

## 四、第一次使用：读取、生成、检查

### 11\. 先让它只读文件

输入：

> 报告当前工作目录完整路径，读取阅读记录.txt，复述 A、B、C 三条内容。不要修改文件，不补充原文没有的信息。

![社区实例中先进入项目，再发送只读分析任务](https://orbiorbi.com/news/content/images/2026/10/07--------------1.webp)

*图源：*[*CodexOne*](https://codexone.cn/start/10-cli-installation?ref=orbiorbi.com)*。看中文任务中的“不要修改文件”。上方保留了作者输错目录后的修正过程，路径和命令无需照输。*

**成功标志：** 路径对应 `codex-first`，三条信息与原文相符。否则先修正位置或文件名。

### 12\. 生成一份新文件

继续输入：

> 根据阅读记录.txt，新建阅读计划.md，分为“已经开始”“准备阅读”“待研究”。每条保留原文信息，增加一个明确标为“建议”的下一步行动。不要编造书名、作者、网址或日期，原文件不改。完成后给出输出文件的完整路径。

Markdown 是纯文本格式，`.md` 文件用记事本也能看。

![Codex 官方终端示例展示计划列表与执行进度](https://orbiorbi.com/news/content/images/2026/10/04-CLI------------.webp)

*官方仓库示例。看下方的计划和执行记录；这些记录帮助跟进过程，但最终仍要打开文件验收。图中项目和历史模型不属于本文练习。*

**成功标志：** 文件夹出现 `阅读计划.md`。若弹出写入授权，核对路径和动作后允许。

### 13\. 打开结果，再改一次

1. 打开 `阅读计划.md`，检查三个分类、A/B/C 归属和“建议”标识。
2. 打开原来的 `阅读记录.txt`，确认没有变化。
3. 发出下面的局部修改，再重新打开计划核对。

> 把 B 的建议改成“先读文章开头，记下一个最想弄懂的问题”，其他内容不变。

**成功标志：** 目标句子改变，其他内容保留。原文没有的事实应删除，不能因为表达顺畅就留下。

## 五、基本使用：查看状态与续接

### 14\. 记住命令的输入位置

| 输入位置    | 命令           | 用途       |
| ------- | ------------ | -------- |
| 普通终端    | codex --help | 查看帮助     |
| 普通终端    | codex resume | 选择历史对话   |
| Codex 内 | /status      | 查看当前状态   |
| Codex 内 | /permissions | 查看任务权限   |
| Codex 内 | /model       | 选择账户可用模型 |
| Codex 内 | /exit        | 退出       |

先 `/exit`，再在相同目录运行 `codex resume`；Orbis 路线用 `codex --profile orbis resume`，选择刚才的对话。

**成功标志：** 可以继续处理同一份计划。[官方命令参考](https://learn.chatgpt.com/docs/developer-commands?surface=cli&ref=orbiorbi.com)

### 15\. 指定文件，不让任务范围越写越大

在 Codex 内输入 `/mention 阅读计划.md`，选中匹配文件，再发送：

> 只检查这份计划中的建议是否都有“建议”标识，逐条指出缺漏，不修改、不读其他目录。

随后可以补一句：“只修复刚才列出的标识问题，其他句子不动。”

**成功标志：** 它引用正确文件，改动限于指出的问题。文件提及用于定位，不会替你检查所有内容是否正确。

### 16\. 练习退出、恢复与新建对话

- 先用 `/rename 阅读计划练习` 给当前对话命名。
- `/exit` 退出，再在原目录运行 `codex resume` 选择对话；Orbis 用户用 `codex --profile orbis resume` 并保持密钥变量可用。
- 另一个无关任务用 `/new` 开新对话；这不会替你备份当前文件。

**成功标志：** 能从名称找到旧任务，继续修改原计划。切换后用 `/status` 再看模型、权限与目录。

### 17\. 管理长对话的上下文

上下文就是它当前参考的对话和材料。对话长了，先让它把“目标、文件、约束、待办”整理成摘要，再输入 `/compact`，之后要求复述下一步。

**成功标志：** 历史缩短后仍记得原文不可改、建议需标注。若复述遗漏，补充要求再执行；摘要不是文件备份。

## 六、进阶使用：计划、规则与审阅

### 18\. 先做合并计划，再批量处理

1. 复制 `阅读记录.txt` 为 `阅读记录-2.txt`，手动增加一条 D：“一篇时间管理文章，待研究”。
2. 输入 `/plan`，发送下面的需求。
3. 核对去重规则和输出位置，再明确要求执行。

> 设计合并两份阅读记录的方案。A/B/C 重复时只保留一份，D 归入待研究；不改原文件，结果放到 output/合并计划.md。先说明如何判断重复、如何检查遗漏，不执行。

**成功标志：** 执行后 A、B、C、D 各出现一次，两个来源文件都没变。出现含糊条目就保留并标待确认，不自行猜测。

### 19\. 用 AGENTS.md 固定重复要求

在练习目录输入 `/init`，打开生成的 `AGENTS.md` 检查内容，加入：

```markdown
# 项目规则
- 用中文解释结果。
- 阅读记录*.txt 是来源文件，不修改。
- 额外想法必须标注“建议”，不补造事实。
- 输出到 output/；写入前确认同名文件是否存在。
- 完成后列出输出路径与检查结果。

```

用 `/new` 开新对话，要求“读取项目规则并复述，暂不执行任务”。已有同名文件先备份、再合并，API Key 不写在这里。

**成功标志：** 新对话能说明来源、输出和事实边界，不必每次粘贴同一段要求。

### 20\. 让它检查结果，你再核对证据

- 发出：“对照两个来源文件审阅 output/合并计划.md，检查遗漏、重复与编造；每个问题写明来源条目。只报告，不修改。”
- 自己打开三个文件对照，确认它指出的问题存在，再让它局部修正。
- 若项目已使用 Git，可以 `/diff` 看改动，再 `/review` 检查代码问题。当前普通文本练习不要求先学 Git。

![Codex 扩展左侧显示文件变化，右侧显示任务结果](https://orbiorbi.com/news/content/images/2026/10/01----------------.webp)

*可选的*[*官方编辑器扩展*](https://learn.chatgpt.com/docs/codex/ide?ref=orbiorbi.com)*：左边看删除和新增，右边看任务结论。本文 Orbis profile 是 CLI 启动方式，不代表图形扩展会自动使用它。*

**成功标志：** 报告中的每条问题都有可核对的依据；修正后 A/B/C/D 仍各一条。基础与进阶命令见[官方参考](https://learn.chatgpt.com/docs/developer-commands?surface=cli&ref=orbiorbi.com)。

## 出错时，先按现象检查

| 现象          | 先检查                                     |
| ----------- | --------------------------------------- |
| 找不到 codex   | 新开终端；确认安装输出没有报错                         |
| 401 / 认证失败  | 当前终端的 ORBIS\_API\_KEY、Key 所属 HA 线路及有效状态 |
| 404 / 模型不存在 | Base URL 要含 /v1，model 必须是精确 ID          |
| 配置未生效       | 是否带 --profile orbis，版本是否支持独立配置文件        |
| 429 / 无额度   | Orbis 额度、线路限制与调用记录                      |
| 能聊天但工具或续聊失败 | 线路的 Responses 流式/工具兼容性；保留脱敏报错查证         |
| 找不到阅读记录     | 当前目录、完整文件名、保存位置                         |
| 可以读但不能写     | /permissions 与可写目录范围                    |
| 只回复文字，没有文件  | 明确要求保存并报告完整路径                           |

第一次只放练习材料，不放密钥或隐私文件。功能以官方文档为准；教学结构参考 [DataCamp](https://www.datacamp.com/tutorial/open-ai-codex-cli-tutorial?ref=orbiorbi.com) 与 CodexOne，未沿用旧版安装条件和权限名称。