企业官网建设流程全解析

1. 从"焚决"这个说法聊起：Codex 这次到底更新了什么

第一次看到"焚决"这个词，我愣了一下。后来在几个开发者群里刷了一圈才反应过来，这是圈子里对 Codex 某次重大能力升级的戏称——"焚"是烧掉旧工作流的意思，"决"是决断、定调。说白了，就是这次更新之后，很多人原来那套用法直接过时了。

Codex 是 OpenAI 推出的代码智能体产品，支持在终端、IDE 和云端运行，能读写代码库、执行命令、跑测试、提 PR。而这次被讨论最多的，是围绕AGENTS.md、Skills、GPT-6 Astra这一整套东西的组合拳。如果你最近在搜"codex 安装教程""codex 使用教程""codex skills""agents.md"这些词，说明你已经踩在门槛上了。

这篇东西我打算按一个真实使用者的视角来写：Codex 现在这套体系里，哪些是必须搞懂的，哪些是容易踩坑的，哪些是网上教程没讲清楚的。适合三类人看——刚听说 Codex 想上手的、已经在用但总觉得没发挥出全部能力的、以及想搞清楚 AGENTS.md 和 Skills 到底该怎么配合的。

先把结论摆前面：Codex 的能力上限，很大程度上不取决于模型本身，而取决于你给它的上下文和技能配置。这句话是整篇的核心，后面所有内容都在展开它。

2. AGENTS.md 不是 README 的替代品，它是给智能体的"作业说明书"

很多人第一次接触 AGENTS.md，会下意识觉得"这不就是个项目说明文件吗，跟 README 差不多"。这个理解偏差会直接导致你写出来的 AGENTS.md 毫无作用。

2.1 AGENTS.md 和 README 的本质区别

README 是写给人看的，读者是有背景知识的开发者，很多约定俗成的东西可以省略。AGENTS.md 是写给智能体看的，它没有你脑子里的隐性知识，你项目里那些"大家都知道"的规矩，对它来说完全不存在。

举个具体的例子。你项目里可能有个约定：所有数据库操作必须走db/目录下的封装层，不允许在业务代码里直接写 SQL。这个规矩在老员工脑子里，新人来了口头带一句就懂了。但智能体不知道，它看到你在写一个查询功能，很可能直接在 service 层拼了个 SQL 字符串出来。

AGENTS.md 要解决的就是这类问题。它应该包含：

• 项目结构说明：哪个目录放什么，模块之间怎么依赖
• 编码规范：命名习惯、错误处理方式、日志规范
• 禁止事项：哪些写法绝对不允许出现
• 常用命令：怎么跑测试、怎么构建、怎么启动本地环境
• 验证方式：改完代码后怎么确认没改坏

2.2 一份能真正生效的 AGENTS.md 长什么样

我见过太多 AGENTS.md 写成了一篇散文，读起来很流畅，但对智能体毫无约束力。有效的写法是命令式、具体化、可验证。

对比一下两种写法：

看出区别了吗？差的写法是态度，好的写法是规则。智能体需要的是规则，不是态度。

2.3 AGENTS.md 的层级与作用范围

Codex 支持多层级的 AGENTS.md，这一点很多人不知道。你可以在项目根目录放一份，在子目录再放一份，子目录的会覆盖或补充根目录的规则。

这个机制非常有用。比如你有个 monorepo，前端和后端的规范完全不同，就可以在frontend/AGENTS.md和backend/AGENTS.md里分别写各自的规则，根目录那份只放全局通用的部分。

提示：子目录的 AGENTS.md 不是简单叠加，而是就近优先。如果你在子目录里写了和根目录冲突的规则，以子目录为准。这个行为要心里有数，否则容易出现"明明根目录写了禁止，怎么还是这么干了"的困惑。

2.4 我踩过的坑：AGENTS.md 写太长的反效果

刚开始我很兴奋，把能想到的规则全塞进去了，写了两千多行。结果发现智能体反而不听话了——因为上下文被稀释了，真正重要的规则淹没在大量次要信息里。

后来我做了减法，把 AGENTS.md 控制在 200 行以内，只保留高频、关键、容易出错的规则。那些偶尔才用到的细节，放到具体的 Skills 里或者临时在对话里说明。

这个经验值得记一下：AGENTS.md 是常驻上下文，写得越长，每条规则的权重越低。它不是文档，是约束。

3. Skills 体系：把重复劳动打包成可复用的能力单元

如果说 AGENTS.md 是"规矩"，那 Skills 就是"手艺"。这是 Codex 这套体系里我觉得最有价值、也最容易被低估的部分。

3.1 Skills 到底是什么，为什么需要它

Skills 可以理解为一组预定义的操作流程或知识包。当你需要智能体做某件有固定套路的事情时，不用每次从头解释，直接调用对应的 Skill 就行。

举个最典型的场景：LaTeX 排版。热词里有人搜"怎么做一个 latex 排版 skills"，这个需求很真实。学术论文的 LaTeX 排版有一套固定流程——模板选择、公式规范、参考文献格式、图表编号规则。如果你每次都跟智能体口头描述一遍，效率极低且容易遗漏。做成 Skill 之后，一句话就能触发整套流程。

Skills 的价值在于三个字：可复用。它把一次性的经验沉淀成资产，下次直接调用。

3.2 Skills 的几种常见类型

根据我自己的使用和观察，Skills 大致可以分成几类：

流程型 Skills：封装一套固定的操作步骤。比如"发布流程 Skill"，包含跑测试、更新版本号、生成 changelog、打 tag、推送。触发一次，全流程自动走完。

知识型 Skills：封装特定领域的知识。比如"公司 API 规范 Skill"，里面写清楚内部接口的命名规则、鉴权方式、错误码约定。智能体写接口时会自动遵循。

工具型 Skills：封装对特定工具的使用方式。比如"图片生成 Skill"，把调用图像生成接口的参数、格式、后处理流程都定义好。

模板型 Skills：封装代码或文档模板。比如"React 组件模板 Skill"，新建组件时自动套用团队约定的结构。

3.3 怎么写一个真正好用的 Skill

写 Skill 和写 AGENTS.md 有相似之处，但更强调可执行性。一个好的 Skill 应该包含：

1. 触发条件：什么情况下该用这个 Skill
2. 前置检查：执行前需要确认什么
3. 执行步骤：具体做什么，按什么顺序
4. 输出格式：结果应该长什么样
5. 异常处理：出错了怎么办

我拿"清理 Skills"这个场景举例，因为热词里有人搜"tibo 关于清理 skills 的方法推荐"。Skill 用久了会积累一堆不再需要的，定期清理是必要的。一个清理 Skill 可以这样设计：

## 触发条件 当用户说"清理 skills"或"整理技能库"时触发 ## 前置检查 - 列出当前所有已安装 Skills - 标记最近 30 天未使用的 ## 执行步骤 1. 按使用频率排序输出 2. 对每个低频 Skill 询问是否保留 3. 确认后移入归档目录而非直接删除 ## 输出格式 表格形式，包含 Skill 名称、最后使用时间、建议操作

注意最后一步——归档而非删除。这是我踩过坑之后的经验：有些 Skill 你当时觉得用不上，过两个月突然又需要了。直接删掉就得重写，归档的话随时能捞回来。

3.4 Skills 的安装与来源

Skills 可以从多个渠道获取。官方市场、社区分享、自己编写，各有各的适用场景。

官方和社区来源的 Skills 胜在开箱即用，但要注意版本兼容性。热词里有人搜"superpower skills 安装""常用 skills 源网站"，说明这块确实有需求。我的建议是：优先用官方维护的，社区的要看清更新时间和适用版本。

自己编写的 Skills 最贴合实际需求，但需要投入时间。我的做法是：先手动做几遍某件事，确认这个流程确实会反复用到，再把它固化成 Skill。不要为了写 Skill 而写 Skill。

注意：安装第三方 Skills 前，务必检查它会不会执行危险操作。Skills 本质上是可以让智能体执行命令的，来源不明的 Skill 可能包含你不希望执行的操作。这个安全意识必须有。

3.5 Skills 与 AGENTS.md 的配合关系

这两者不是替代关系，是互补关系。

AGENTS.md 管的是始终生效的底线规则，Skills 管的是特定场景下的操作流程。打个比方，AGENTS.md 是公司的员工手册，Skills 是各个岗位的操作手册。

一个实际例子：AGENTS.md 里写"所有提交必须通过 lint 检查"，这是底线。而"发布 Skill"里写"发布前依次执行 lint、test、build、changelog 生成"，这是流程。两者配合，才能既保证质量又提升效率。

4. 模型选择与接入：GPT-6 Astra 和其他选项怎么选

热词里"gpt-6 astra""gpt-6 astra 怎么用""codex 接入 deepseek"这几个词出现频率很高，说明大家对模型选择这件事很关心。

4.1 不同模型在 Codex 场景下的定位

Codex 本身是一个智能体框架，底层可以接不同的模型。不同模型在代码任务上的表现差异是实实在在的。

GPT-6 Astra是当前讨论度最高的选项。从实际使用反馈看，它在长上下文理解、复杂重构、多文件协同修改这几类任务上表现突出。如果你的项目结构复杂、需要跨多个文件改动，Astra 的优势会很明显。

其他模型在特定场景下也有价值。比如有些模型在特定编程语言的代码生成上更稳，有些在响应速度上更快。选择的核心逻辑是：看你的主要任务类型。

4.2 接入第三方模型的注意事项

热词里"codex 接入 deepseek"这个搜索，反映了一个真实需求：不是所有人都想用同一个模型。接入第三方模型时，有几个点必须注意。

接口兼容性是第一个坎。不同模型的 API 格式不完全一样，Codex 对接口有特定要求。如果格式对不上，就会出现热词里提到的"cc switch local proxy failed while handling codex endpoint /responses"这类报错。

认证配置是第二个坎。"codex auth token is unavailable"这个报错很多人遇到过。通常是 token 没配、配错了位置、或者过期了。排查顺序是：先确认 token 存在，再确认读取路径正确，最后确认 token 本身有效。

模型名称匹配是第三个坎。热词里有个很典型的报错："the 'gpt-5.6-sol' model is not supported when using codex with a..."。这类问题的根源是模型名称写错了，或者该模型在当前接入方式下不被支持。解决办法是查官方文档确认支持的模型列表，别想当然。

4.3 配置文件的正确写法

Codex 的配置通常放在用户目录下的配置文件中。一个常见的配置结构大概是这样：

# 模型配置 model = "your-model-name" model_provider = "your-provider" # 认证配置 [model_providers.your-provider] name = "Your Provider" base_url = "https://your-endpoint/v1" env_key = "YOUR_API_KEY"

几个容易出错的点：

• base_url结尾的/v1不能少，少了会 404
• env_key是环境变量的名字，不是 key 本身
• 模型名称必须和 provider 支持的完全一致，大小写敏感

提示：改完配置后，先用一个最简单的任务测试，比如"列出当前目录文件"。如果这个都跑不通，说明配置有问题，别急着上复杂任务。

4.4 切换模型时的状态管理

热词里"codex ccswitch"这个词值得单独说。切换模型或 provider 时，最容易出问题的是状态不一致——配置文件改了，但缓存没清，导致行为诡异。

我的做法是：切换后先重启 Codex 会话，再跑一个验证任务。如果行为不对，检查三个地方：配置文件、环境变量、缓存目录。这三个地方任何一个没同步，都会出问题。

5. 从安装到跑通：一条少踩坑的路径

热词里"codex 安装""codex 安装教程""codex 安装 windows 桌面版""codex 下载""codex 官网登录入口"这些词密集出现，说明安装环节是很多人的第一道坎。

5.1 安装前的环境确认

在动手之前，先确认几件事：

• 操作系统版本：Windows、macOS、Linux 各有不同的安装方式
• Node.js 版本：很多安装方式依赖 Node 环境，版本太低会失败
• 网络环境：安装过程需要访问包管理源，网络不通会卡住
• 磁盘空间：留出足够空间，别装到一半满了

这几项看起来是废话，但我见过太多人卡在"装不上"上，最后发现是 Node 版本太老。

5.2 不同平台的安装方式

命令行安装是最通用的方式，适合 macOS 和 Linux。通过包管理器一条命令搞定，升级也方便。

Windows 桌面版是热词里明确提到的需求。Windows 用户的体验确实和类 Unix 系统有差异，路径分隔符、权限模型、终端环境都不一样。装的时候注意用管理员权限，否则可能写不进系统目录。

IDE 集成是另一种方式，热词里"vscode 接入 codex"就是这个。好处是直接在编辑器里用，不用切终端。配置时注意 IDE 的版本要支持对应的扩展。

5.3 登录与认证

"codex 官网登录入口""codex 登录"这些搜索说明登录环节也有坑。

登录方式通常有两种：账号密码登录和 API Key 认证。账号登录适合个人使用，API Key 适合自动化和团队场景。

如果遇到"codex 打不开"的情况，排查顺序是：

1. 确认网络能访问服务端点
2. 确认登录状态没过期
3. 确认本地配置没被改坏
4. 查看日志找具体报错

大部分"打不开"的问题，最后都定位到认证失效或配置错误上。

5.4 跑通第一个任务

装完之后别急着上复杂项目，先跑一个最小验证：

# 进入一个测试目录 cd ~/test-codex # 启动 codex codex # 输入一个简单任务 > 创建一个 hello.txt 文件，内容写 "hello codex"

如果这个能跑通，说明基础环境没问题。跑不通的话，问题一定在安装或认证环节，别往复杂方向想。

6. 实战场景：几个高频需求的落地方法

光讲概念没意思，这一节我挑几个热词里反复出现的实际需求，讲讲具体怎么落地。

6.1 前端开发场景下的 Skills 配置

"前端开发 skills"是个高频搜索。前端开发的痛点在于：框架多、规范杂、重复劳动多。

我自己的前端 Skills 配置包含这几块：

组件生成 Skill：定义好组件的目录结构、文件命名、样式方案、测试文件。新建组件时一句话触发，生成的文件直接符合团队规范。

样式规范 Skill：把设计系统的颜色、间距、字号、圆角等变量固化进去。智能体写样式时自动引用变量，不会出现硬编码的魔法数字。

接口对接 Skill：封装请求库的使用方式、错误处理、loading 状态管理。避免每个页面各写一套。

这套配置下来，前端开发的重复劳动能砍掉一大半。

6.2 学术场景：LaTeX 排版 Skill 的构建

前面提到过 LaTeX 排版 Skill，这里展开讲讲怎么建。

学术排版的核心需求是格式一致性。公式编号、图表标题、参考文献、页眉页脚，每一项都有严格规范。

构建步骤：

1. 确定模板：选定期刊或会议的官方模板，把模板文件放进 Skill 目录
2. 定义规则：把格式要求写成明确的规则，比如"公式编号用 (1) 格式，右对齐"
3. 封装命令：把常用的排版操作封装成命令，比如"插入带编号的公式"
4. 验证机制：加一个检查步骤，排版完成后自动检查格式合规性

这样一套下来，写论文时就不用反复查格式手册了。

6.3 建模比赛场景：华为杯这类竞赛的 Skills 用法

热词里"华为杯建模比赛好用的 codex skills"这个搜索很具体。数学建模比赛的特点是：时间紧、任务重、需要快速产出代码和论文。

针对这个场景，Skills 应该覆盖：

• 数据预处理 Skill：常见的数据清洗、缺失值处理、归一化流程
• 模型训练 Skill：常用模型的训练模板，参数配置
• 可视化 Skill：符合论文要求的图表生成
• 论文排版 Skill：建模论文的固定结构

比赛时时间就是分数，这些 Skill 能帮你把机械劳动压缩到最低，把时间留给真正的建模思考。

6.4 AI 漫剧场景：图片生成 Skills 的配置

"ai 漫剧常用 skills""图片生成 skills 安装包"这两个搜索指向一个具体场景：用 AI 生成漫画或短剧素材。

这个场景的 Skills 配置重点是一致性。角色形象要统一、画风要稳定、分镜要连贯。

配置要点：

• 角色定义：把主要角色的外观特征固化成描述模板
• 画风锁定：确定统一的画风关键词，每次生成都带上
• 分镜规范：定义镜头语言，比如远景、中景、特写的描述方式
• 后处理流程：生成后的裁剪、拼接、字幕添加

这套配置能显著提升出图的一致性和可用率。

7. 那些教程不会告诉你的坑

这一节是我自己踩过的坑，以及从社区里看到的高频问题。这些东西官方文档不会写，但实际用起来一定会遇到。

7.1 上下文窗口不是越大越好

很多人以为上下文窗口越大越好，恨不得把所有文件都塞进去。实际用下来，塞得越多，智能体越容易迷失。

原因是注意力机制的特性：上下文越长，每个 token 的权重越分散。关键信息淹没在大量无关内容里，智能体反而抓不住重点。

我的做法是：精准投喂。只给当前任务相关的文件，用 AGENTS.md 和 Skills 提供必要的背景，而不是把整个代码库倒进去。

7.2 Skills 冲突的处理

装多了 Skills 之后，冲突是必然的。两个 Skill 对同一件事有不同规定，智能体就懵了。

处理原则：

• 优先级明确：在配置里定义 Skill 的优先级顺序
• 职责单一：每个 Skill 只管一件事，别搞大杂烩
• 定期清理：不用的 Skill 及时归档，减少冲突面

我遇到过两个 Skill 都定义了代码格式化规则，结果智能体每次格式化结果都不一样。后来把其中一个归档了，问题解决。

7.3 模型切换后的行为漂移

换模型之后，同样的 AGENTS.md 和 Skills，输出质量可能明显变化。这不是配置问题，是模型特性差异。

应对方法：换模型后，用一组标准任务测试，对比输出。如果差异太大，可能需要针对新模型调整 AGENTS.md 的写法。有些模型对指令的遵循更严格，有些更宽松，写法要相应调整。

7.4 认证失效的隐蔽性

"codex auth token is unavailable"这个报错，有时候不是 token 本身的问题，而是读取路径的问题。

我遇到过一次：token 明明配了，但 Codex 就是读不到。排查半天发现是环境变量在某个 shell 配置里被覆盖了。这种问题很隐蔽，因为表面上看配置都对。

排查这类问题的技巧：用最干净的环境测试。开一个新的终端会话，不加载任何自定义配置，看能不能跑通。如果能，说明问题在你的 shell 配置里。

7.5 网络问题的伪装

有些报错看起来是代码问题，实际是网络问题。比如请求超时、响应格式错误，可能是网络中间环节出了问题。

判断方法：看错误发生的时机。如果是稳定复现的，大概率是配置或代码问题；如果是偶发的，网络因素的可能性更大。

8. 把 Codex 用出复利：一些长期实践的心得

用了这段时间，我最大的感受是：Codex 的价值不是线性的，是复利的。你投入在 AGENTS.md 和 Skills 上的每一分精力，都会在后续的每一次使用中产生回报。

8.1 从"用工具"到"养工具"

刚开始大家都是把 Codex 当工具用，用完就走。但真正用得好的人，是在"养"它——持续优化 AGENTS.md，不断沉淀 Skills，让这套配置越来越贴合自己的实际需求。

这个过程有点像养一个助手。刚开始它什么都不懂，你得手把手教。教得越多，它越懂你，后面就越省心。

8.2 建立自己的 Skills 库

我建议每个人都建立自己的 Skills 库，哪怕一开始只有几个。关键是养成习惯：每次发现一个重复劳动，就想想能不能做成 Skill。

积累半年下来，你会发现自己的 Skills 库成了最宝贵的资产。换项目、换公司，这套东西都能带走，直接复用。

8.3 保持对模型更新的关注

这个领域变化很快。新模型、新能力、新用法层出不穷。保持关注，及时把新东西纳入自己的工作流，才能持续保持效率优势。

但也别盲目追新。新东西出来先小范围试，确认确实有提升再全面切换。我见过太多人追新追出问题，反而耽误了正事。

8.4 最后分享一个实用技巧

如果你刚开始用 Codex，不知道从哪下手，我的建议是：先找一个你每天都在做的重复任务，把它做成第一个 Skill。

不要贪多，就一个。做出来之后用一周，感受一下效率变化。有了正反馈，你自然知道下一步该做什么。

这个技巧帮我度过了最开始那段"不知道用来干嘛"的迷茫期。希望对你有用。