更新日期:2026 年 11 月 19 日。本文面向通过 Aekor API 使用模型的 Codex 本地客户端和 CLI 用户。
想在 Codex 中使用 GPT-6.2,除了填入接口地址和 API Key,还可以把官方推荐的工作要求保存成一份 AGENTS.md:让模型在后续任务中知道如何组织回答、持续推进任务、编写可读代码,以及处理前端设计。
这篇教程从接入开始,带你配置好两个文件:
| 文件 | 用途 |
|---|---|
config.toml | 设置 Aekor 接口、调用模型、推理强度和认证方式 |
AGENTS.md | 保存长期使用的工作要求,供 Codex 启动时读取 |
Windows 和 Mac 使用同一份基础配置,区别主要是文件所在的路径。已经用过旧版教程的用户,也可以按本文更新模型和指令文件。
开始之前:Astra 和 Sol 怎么选?
GPT-6.2 系列包含 Astra 和 Sol。按照 OpenAI 的官方定位,可以这样选择:
| 模型 | 官方模型 ID | 适合的任务 |
|---|---|---|
| GPT-6.2 Astra | gpt-6.2-astra | 复杂问题、跨模块排错、需要深入分析的任务 |
| GPT-6.2 Sol | gpt-6.2-sol | 日常编码、代码审查、写作和多步骤工作,兼顾成本 |
本文使用 gpt-6.2-astra 演示。想用 Sol,修改配置中的一行模型名称即可。
开始前,请准备好能够正常启动的 Codex 客户端,以及 Aekor 后台生成的 API Key。尚未安装客户端,可以先查看 Codex 官方客户端说明。
请先在 Aekor 后台确认:你的密钥所属分组已经开放目标模型,并支持 Responses 接口。 模型名称、可用额度与实际价格以 Aekor 后台为准;如果后台使用了模型别名,应填写后台提供的名称。
第一步:准备 Aekor API Key
登录 Aekor 后台,创建或复制自己的 API Key,并确认余额、额度和模型权限。
本教程使用的 API 基础地址为:
https://api.aekor.com/v1
GPT-6.2 的工具调用需要使用 Responses API。这对需要读取文件、执行命令和修改代码的 Codex 很重要:只有 Chat Completions 兼容接口,并不足以完成这类接入。
后面配置中的 base_url 填到 /v1 即可,不要再手动加上 /responses,Codex 会按协议请求对应的接口。
API Key 相当于账号凭证。保存在自己的电脑上即可,分享配置或截图时应先移除密钥。
第二步:找到 Codex 的全局配置目录
先完全退出正在运行的 Codex 客户端,然后找到用户级 .codex 目录。
| 系统 | 默认目录 |
|---|---|
| Windows | %USERPROFILE%\.codex |
| macOS | ~/.codex |
如果你自行设置过 CODEX_HOME,应使用它指向的目录。
Windows
- 按
Win + R。 - 输入
%USERPROFILE%\.codex并回车。 - 如果目录不存在,先在自己的用户目录下创建
.codex文件夹。 - 在该目录中找到或创建
config.toml。
建议打开资源管理器中的“文件扩展名”显示,确认文件没有被保存为 config.toml.txt。
Mac
- 打开访达,按
Command + Shift + G。 - 输入
~/.codex并前往。 - 在该目录中找到或创建
config.toml。
目录不存在时,也可以在终端执行:
mkdir -p ~/.codex
随后使用 VS Code 等纯文本编辑器创建文件。如果使用系统“文本编辑”,请先切换为纯文本,避免保存成富文本或自动添加 .txt 后缀。
已有配置的用户,请先备份 config.toml 和已有的指令文件。 更新模型接入时,保留自己正在使用的 MCP、插件及其他配置。
第三步:写入 GPT-6.2 接入配置
1. Windows / Mac 通用模板
如果是第一次配置,将下面内容保存到 config.toml,并把密钥占位文字替换为自己的 Aekor API Key:
# 默认模型:如需使用 Sol,将这一行改为 gpt-6.2-sol
model = "gpt-6.2-astra"
model_provider = "aekor"
model_reasoning_effort = "medium"
approval_policy = "on-request"
[model_providers.aekor]
name = "Aekor"
base_url = "https://api.aekor.com/v1"
wire_api = "responses"
experimental_bearer_token = "sk-请替换为你的Aekor_API_Key"
requires_openai_auth = false
supports_websockets = false
如果原来已经有配置,请按下面的方式合并:
model、model_provider、model_reasoning_effort和approval_policy属于顶层设置,应放在第一个[表名]之前;已有同名设置就直接修改。[model_providers.aekor]是 Aekor 的提供商配置。已有这个表时,更新原表里的字段,不要重复创建。- 原来的 MCP 和插件配置继续保留。
不要把整份模板直接追加到已有文件末尾。 TOML 中,表名之后的字段会归入该表;顶层设置放错位置,可能导致配置没有按预期生效。
2. 这几个设置分别做什么?
| 设置 | 作用 |
|---|---|
model | 本次要调用的模型,示例为 GPT-6.2 Astra |
model_provider | 选择下面定义的 aekor 提供商 |
model_reasoning_effort | 推理强度;官方建议新接入从 medium 开始 |
approval_policy | 工具执行的审批策略;示例保留按需确认 |
base_url | Aekor API 基础地址 |
wire_api | 使用 responses 协议 |
experimental_bearer_token | 直接提供 Bearer Token,此处填写 Aekor API Key |
requires_openai_auth | 此提供商不使用 OpenAI 登录认证 |
supports_websockets | 示例关闭 Responses WebSocket 传输,使用 HTTP 连接 |
这份模板使用 Codex 当前支持的直接 Bearer Token 字段,便于 Windows 和 Mac 桌面用户直接配置;密钥会以明文保存在本机文件中。
官方更推荐使用环境变量 env_key。 如果已经为 Codex 的启动环境设置好 AEKOR_API_KEY,可以删除 experimental_bearer_token,在同一个 [model_providers.aekor] 表中改用:
env_key = "AEKOR_API_KEY"
这两种认证方式选一种即可。使用环境变量时,要确认实际启动 Codex 的进程能够读取它;仅在某个终端中临时设置变量,不代表从桌面图标启动的客户端也能读到。
3. 想换成 GPT-6.2 Sol?
把顶层的 model 修改为:
model = "gpt-6.2-sol"
其他接入设置可以保持一致,前提是你的 Aekor 密钥也有 Sol 的调用权限。
推理强度建议先使用 medium,再根据任务难度、响应时间和实际消耗调整。更高的强度可能改善复杂任务的结果,也会增加耗时和 Token 使用量;可选档位以模型和客户端实际支持的范围为准。
第四步:把官方提示词一次写入 AGENTS.md
接入配置完成后,在同一个 .codex 目录中新建 AGENTS.md:
| 系统 | 全局指令文件的默认路径 |
|---|---|
| Windows | %USERPROFILE%\.codex\AGENTS.md |
| macOS | ~/.codex/AGENTS.md |
全局文件适合保存跨项目使用的默认要求。以后启动新的 Codex 会话时,就不用再逐次粘贴这套提示词。
下面的内容来自 OpenAI GPT-6.2 官方指南,包含全部 8 段示例提示词,分为四组:
- Writing style:表达清楚,为读者补足背景,最终回答能够独立理解。
- Task completion:在已授权范围内持续推进,合理处理假设,完成后检查结果。
- Coding style:复用正确的现有逻辑,保持代码可读,按需要补充测试。
- Frontend design:选择合适的视觉素材,减少没有实际用途的界面文字。
以下英文提示词保留官方原文,只增加 Markdown 标题来组织文件。 复制代码块内的全部内容,保存为 UTF-8 编码的 AGENTS.md,不要把外层代码块标记一起写入文件。
如果已有 AGENTS.md,请合并规则,保留原来仍然需要的内容。如果全局目录中存在非空的 AGENTS.override.md,Codex 会优先读取它,而不会同时加载同目录的 AGENTS.md;此时应更新你正在使用的全局指令文件。
# Codex instructions
## Writing style
Write using terminology the user and sources use. Keep technical details and use domain-specific language when they make the explanation more precise. Use the active voice and keep closely related details together. Cover the key points up front, and avoid references that the reader can only make sense of later in the response. Give the user enough context to follow your reasoning.
When drafting a message or any other material on behalf of the user to be sent to an external audience, consider who will read it and tailor the content to that intended audience. The intended audience likely does not have the same context as the user, so ensure that you provide the background information or reasoning required for the audience to understand the content. When reviewing or editing existing content, preserve the author’s content and wording, and follow the user's instruction carefully for what edits they want.
Treat your final answer as the user's first look at your work, and not as a continuation of intermediate commentary. The final answer must always be fully self-contained: users should never need to read earlier commentary updates for context, since they are collapsed when the final answer is shown to the user.
Write the final answer and all other human-facing material anew for the intended reader. Do not copy or closely paraphrase your reasoning or adopt its writing style. Do not carry over working shorthand, jargon, or abbreviations from your reasoning, tool calls, or instructions to subagents and automations.
## Task completion
Avoid stopping to end the turn while the task is incomplete or if there is an authorized next step you can take, and instead take the next steps within task scope to progress the user's request. If your final response before ending the turn is a suggested next step, a plan, a request to the user for a routine decision, instructions for a task to execute, or similar handoff to the user, take these steps yourself to make progress towards what the user asked for. Make sure that you have authorization to do so, and flag any assumptions or decisions you maketo the user.
Only stop to clarify with the user if there is significant change in task scope, you are concretely blocked, have a decision that the user needs to resolve, or before irreversible or destructive actions.
Bias towards action, and persist until you've completed the task the user asked for. Avoid stopping to end the turn while the task is incomplete or if there is an authorized next step you can take, and instead take the next steps within task scope to progress the user's request. Make sure that you have accounted for every part of the user's request, and persist until you've delivered a result that fully satisfies the user's goal. If a task requires sustained work, do all the necessary work until the intended outcome is completely fulfilled.
Progress autonomously towards the user's goal (e.g. creating isolated worktrees / checkouts if needed, resolving merge conflicts, creating draft PRs etc) unless they are clearly destructive or irreversible. Before ending a turn or calling your work complete, check that your work fully satisfies what the user asked for. If any steps remain or any part of the result still needs verification, follow through on this work before finishing.
Make reasonable, reversible assumptions to carry work forward and state them if it progresses the task within scope. Do not second guess yourself, stop after describing what you could do, offer to do the work, or provide a partial answer unless there is no way you can proceed.
## Coding style
Above all, be thorough in producing high-quality, correct code that completely fulfills the user's task. Keep the code easy to read and verify that the user-requested outcome works as they intend. Follow these instructions when coding:
(a) Reuse existing logic in the user's repo when you can. You should reuse existing classes, methods, representations, and APIs in the codebase as long as they preserve correctness. Before consolidating or removing code, preserve the behavior its callers rely on unless the task requires changing it.
(b) Skip new tests unless requested, required by the repo, or needed to catch a specific regression existing tests would miss.
(c) Make sure that code is human readable. Do not use fewer lines, shorter variable names, minified formatting, or dense one-liners as substitutes for simplicity. Ensure that comments and variable names are readable and understandable to a human. Code-golfed expressions count as overly complex when they encode many branches, conditions, or hidden assumptions.
(d) Avoid unnecessary indirection and abstraction. Helper functions, utility functions, and class abstractions can add cognitive complexity even when they do not add branches.
## Frontend design
When generating webpages or apps with a frontend user interface, follow these instructions:
- When choosing visuals, generally prefer realistic images from ImageGen or image search that suit the project's style and purpose. Use SVGs when the user specifically asks for them.
- Include a text element only when it provides information the user needs, helps them navigate or act, or fulfills an explicit content request. Remove decorative numbering, filler badges, redundant headings, and explanatory copy that merely restates what the surrounding interface already makes clear, while preserving necessary labels, instructions, and status feedback.
全局规则和项目规则可以一起使用
全局 AGENTS.md 用来保存自己的常用要求;项目根目录的 AGENTS.md 可以补充该项目的开发约定,例如包管理器、测试命令和目录规范。
Codex 会按目录层级组合适用的文件。项目中更具体的规则与全局要求冲突时,会覆盖相应的全局要求。组合后的指令文档默认有 32 KiB 的大小上限,因此建议保持规则精简,避免重复堆叠。
本节提供的全局文件约 5.5 KB。它不需要在 config.toml 中添加一个启用开关。
第五步:重启 Codex,验证模型和指令
保存两个文件后,重新启动 Codex,并新建一个对话。如果使用 CLI,则退出原会话后重新运行 codex。
1. 验证模型接入
在客户端模型选择处确认当前模型;CLI 用户可以使用 /model 检查。不同版本的显示名称可能不同,应同时确认提供商和模型设置。
先发送一个简单请求:
连接测试:请只回复“连接测试通过”。
收到正常回复后,去 Aekor 后台查看对应调用记录,核对请求是否使用了预期的模型、是否产生了相应的使用记录。
模型在回答中声称“我是 GPT-6.2”不能单独作为验证依据;客户端配置和平台调用记录更适合用来核对实际请求。
2. 验证 AGENTS.md 已加载
在新对话中发送:
请列出当前已加载的 AGENTS.md 或 AGENTS.override.md 的来源路径,并概括其中关于写作风格、任务完成、代码风格和前端设计的要求。先不要修改任何文件。
检查结果是否包含刚才保存的全局文件,以及四组对应的工作要求。
如果文件路径或规则不符合预期,先检查 .txt 后缀、CODEX_HOME 和全局 AGENTS.override.md,然后重新启动会话验证。仅修改文件后继续使用旧会话,不能用来确认新规则已经加载。
3. 验证实际工作流程
打开准备让 Codex 处理的项目目录,先让它执行一个范围清楚的小任务,例如:
请阅读这个项目,告诉我它的技术栈、主要目录和启动方法。先不要修改文件;如果文档缺失,请明确指出哪些信息还需要确认。
确认能正常读取项目,再开始修改代码。命令执行、文件写入等权限按客户端当前设置处理;AGENTS.md 中的提示词不会替代这些权限设置。
第六步:日常任务怎么提问?
全局指令负责保存重复使用的要求。每次对话里,仍然需要说明这次的目标、相关背景和完成标准。
修复问题:给出复现方式和期望结果
这个项目在登录成功后偶尔会跳回登录页。
复现方式:登录后刷新页面,再进入用户中心。
期望结果:登录状态仍然有效,能够正常进入用户中心。
请定位原因、完成修复,并验证相关流程。优先沿用项目已有的认证逻辑,最后说明修改了什么、如何验证,以及还有哪些未解决的问题。
开发前端:说明视觉风格和交互
请在当前项目中制作一个产品介绍页面。
视觉方向:浅色背景、清晰的大标题、简洁的排版;沿用项目已有字体和组件。
页面内容:产品介绍、主要功能、价格和常见问题。
交互要求:手机和桌面都能正常使用,按钮有明确去向。
请先检查现有页面和组件,再完成实现。最后检查布局与交互;如果有无法验证的部分,请明确说明。
如果对视觉效果有具体要求,可以再提供参考页面或图片。官方建议用参考帮助模型理解风格,再根据实际渲染结果继续调整。
写作和资料整理:说明读者与用途
请根据我提供的资料,写一篇面向第一次使用这个产品的用户的教程。
需要包含准备条件、操作步骤、成功标志和常见问题。
保留资料中的准确名称与参数;资料没有说明的地方,不要自行编造。
输出为一篇能够独立阅读的 Markdown 文章。
GPT-6.2 默认表达较简洁。如果任务需要完整解释,可以直接说明“不要省略必要步骤”“给出足够背景和验证方法”,不必在全局规则里反复要求极短回答。
怎样兼顾效果、速度和消耗?
- 按任务选模型。 日常工作可以先评估 Sol,复杂问题再考虑 Astra,实际费用查看 Aekor 后台。
- 按难度调推理强度。 从
medium开始,根据结果决定是否调整,不必所有任务都使用最高档位。 - 给出有用背景。 错误信息、复现步骤、相关文件和验收要求,通常比反复说“认真一点”更能帮助模型完成任务。
- 同一任务保持上下文连贯。 GPT-6.2 官方指南说明,中途改写较早的对话内容或进行某些模型切换,可能丢失已有推理状态。独立的新任务可以另开对话。
AGENTS.md 的作用是保存工作要求,减少重复输入;它本身仍会占用上下文,不应被理解成固定比例的 Token 节省开关。
常见问题
1. 提示 401、403,或者无效密钥
先检查 API Key 是否完整、有无多余空格,以及密钥是否仍有效。再查看 Aekor 后台中的分组权限、模型权限和具体错误信息。
2. 提示模型不存在,或者没有可用渠道
核对 model 是否与 Aekor 后台提供的模型名称一致,确认当前密钥所属分组已经开放该模型。如果平台使用了别名,按后台的别名填写。
3. 提示 404,或者 Responses 接口不可用
检查 base_url 是否为 https://api.aekor.com/v1,不要重复写入 /v1,也不要在基础地址后添加 /responses。同时确认所选渠道支持 Responses API,而不只是 Chat Completions。
4. 提示不支持某些采样参数
GPT-6.2 有参数兼容变化。如果沿用了旧请求设置,或中间层自动注入参数,应检查并移除不支持的字段。
官方说明:Responses 请求应省略 temperature、top_p 和 top_logprobs,并从 include 中移除 message.output_text.logprobs。本文的基础模板没有添加这些字段。
5. 改完配置,仍然使用旧模型
先新建会话,再检查客户端当前选择、CLI 启动参数、选中的 profile,以及项目中的模型覆盖设置。它们可能覆盖用户级默认值。
Aekor 的提供商和认证配置应保存在用户级 config.toml 中;不要只把这部分写入项目里的 .codex/config.toml。
6. AGENTS.md 没有生效
检查文件名、存放目录,以及是否存在 AGENTS.override.md。如果设置过 CODEX_HOME,确认编辑的是它指向的目录。修改后重新启动 Codex,并在新会话中验证。
7. 旧版教程中的实验性上下文模式还要保留吗?
当前官方配置参考将 features.context_management.experimental_mode 标记为“目前不可用”。本文不再加入这项配置,也不把它作为省 Token 或防遗忘的依据。
从旧教程升级时,可以移除仅用于启用该功能的 [features.context_management] 配置段,保留其他仍在使用的功能设置。
8. 为什么配置后不能联网搜索、生成图片或控制浏览器?
这些能力还取决于客户端实际提供的工具、Aekor 渠道兼容性、已安装的插件和授权情况。模型接入成功不代表所有工具都自动可用;提示词中提到某个工具,也不会自动安装它。
9. 提示限流或额度不足
按 Aekor 返回的错误说明,检查余额、密钥额度、并发限制和渠道状态。不要把所有 429 错误都当作配置文件写错。
文章评论