Codex 使用指南（技术向）：App、CLI 与工作流接入

稳定优质性价比中转站：中转站链接

如果只保留一个结论：

Codex App 用来理解范式，Codex CLI 用来接入工程。

Codex 不是聊天工具，而是一个以项目为边界的执行代理（agent）：读取代码上下文 → 规划 → 修改 → 运行 → 验证 → 返回结果。

这决定了它的使用方式与传统 LLM 有本质差异。

一、两种入口的定位

当前主流入口：

Codex App（Desktop）
Codex CLI（命令行）

工程上可以这样理解：

入口	角色
App	可视化 agent sandbox
CLI	可嵌入 dev workflow 的执行器

建议顺序：

用 App 建立"agent 如何工作"的直觉
用 CLI 接入真实项目

直接从 CLI 开始，大概率会卡在环境和心智模型上。

二、Codex App：本质是一个本地 Agent Sandbox

App 的核心不是 UI，而是三个能力：

任务编排（Task orchestration）
上下文绑定（Project-aware context）
执行可视化（Execution trace）

它更像：

一个带 UI 的、本地运行的 agent runtime

而不是"增强版聊天窗口"。

三个关键能力（技术视角）

1. In-app Browser = 可标注的 DOM 观察层

能力拆解：

页面加载（本地 / 远程）
DOM 节点选择
上下文注入（选区 → prompt）

本质上解决的是：

"描述 UI 问题" → "直接指向具体节点"

适用于：

前端调试
样式修复
内容结构调整

2. Computer Use = GUI 自动化代理（受控）

机制上可以理解为：

屏幕感知（视觉）
输入控制（鼠标 / 键盘）
权限 gating（人工确认）

适用场景：

E2E 测试（无脚本）
GUI-only bug 复现
非 API 可达流程

但要注意边界：

它不是 deterministic automation，而是带不确定性的 agent 行为

因此：

任务必须收敛
权限必须控制

3. Artifact Preview = 非代码输出通道

Codex 的输出不局限于代码：

文档（PDF / Markdown）
表格
演示文件

工程意义在于：

Agent 输出 ≠ Git diff，而是多模态 artifact

这对"非纯研发任务"非常关键。

三、Codex CLI：如何接入工程环境

1. 安装

bash 复制代码

npm install -g @openai/codex

本质依赖：

Node.js runtime
npm global install

2. 启动

bash 复制代码

codex

首次启动：

OAuth（ChatGPT）
或 API Key

建议：

场景	方式
本地交互	ChatGPT
自动化 / CI / 中转	API Key

四、CLI 的最小工作流

不要一开始就做复杂任务。

先验证三个能力：

上下文理解

text 复制代码

分析这个项目结构，标出入口和核心模块

定位能力

text 复制代码

找出这个页面对应的组件和样式文件

只读推理

text 复制代码

不要修改代码，说明这个模块的调用链

目的不是完成任务，而是验证：

它是否正确理解你的 repo

五、任务建模（比 prompt 更重要）

Codex 的稳定性，取决于任务定义是否完整。

推荐最小 schema：

text 复制代码

Goal:
Context:
Constraints:
Done:

示例（工程化表达）：

text 复制代码

Goal:
优化首页 CTA 逻辑

Context:
src/pages/home.tsx
src/styles/home.css

Constraints:
- 不修改接口
- 不影响移动端布局

Done:
- 首屏转化路径更清晰
- build 通过

这本质是在降低：

agent → 任务理解的不确定性

六、复杂任务：强制两阶段执行

不要：

直接执行复杂修改

而是：

Plan
Execute

示例：

text 复制代码

先不要改代码，输出执行计划：
- 步骤拆解
- 风险点
- 验证方式

这一步的价值是：

提前暴露理解偏差，而不是事后返工

七、AGENTS.md：长期稳定性的关键

可以理解为：

面向 agent 的系统提示（persistent prompt）

建议写入：

项目启动方式
代码规范
测试流程
禁止行为

一个实用策略：

同一错误出现两次 → 更新 AGENTS.md，而不是重复提醒

八、让 Codex 不只是"写代码"

很多人只用到：

generate code

但更完整的用法是：

text 复制代码

修改 → 测试 → 验证 → review

示例：

text 复制代码

修复这个 bug
- 修改代码
- 跑相关测试
- 确认不再复现
- review diff 风险

这会显著降低：

人工回归成本

九、配置体系（不要忽略）

核心文件：

~/.codex/config.toml
~/.codex/auth.json

常见问题来源：

model 不匹配
base_url 错误
权限未配置
工具链未接入

很多"效果不好"的问题，本质是：

runtime 配置问题，而不是模型问题

十、中转接入（以 Unity2.ai 为例）

Codex 对中转的要求：

OpenAI-compatible API
支持 Responses API（而非仅 Chat API）

示例配置

auth.json

json 复制代码

{
  "OPENAI_API_KEY": "sk-xxx"
}

config.toml

toml 复制代码

model_provider = "unityai"
model = "gpt-5.4"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.unityai]
name = "unityai"
base_url = "https://unity2.ai"
wire_api = "responses"

十一、一个更工程化的使用顺序

错误顺序（常见）：

配接口 → 调参数 → 折腾中转 → 放弃

更合理的路径：

App：理解 agent 行为
CLI：接入项目
AGENTS.md：沉淀规则
config：稳定运行
中转：优化接入

结语

Codex 的关键不在"模型能力"，而在：

它把 LLM 从"回答问题"升级成"执行任务"。

如果你只是把它当聊天工具用，很容易得出错误结论。

但一旦把它放进工程上下文里，它的上限会完全不同。

稳定优质性价比中转站：中转站链接