# 使用 Codex 编写文档 (/zh/guides/codex)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 1185 · updated: 2026-07-30 -->
Related: [构建应用内助手](/zh/guides/assistant-embed.md), [配置 GitHub 应用的自动合并](/zh/guides/configure-automerge.md), [使用自动化](/zh/guides/use-automations.md), [使用 Claude Code 编写文档](/zh/guides/claude-code.md), [使用 Cursor 编写文档](/zh/guides/cursor.md), [使用 Devin Desktop 编写文档](/zh/guides/devin-desktop.md)

使用 OpenAI 的 Codex CLI 在终端中编写和维护 Mintlify 文档。`AGENTS.md` 中的项目说明可为 Codex 提供关于你的文档标准、组件和样式指南的持久 context。

<div id="getting-started">
  ## 开始使用 [#开始使用]
</div>

**前置条件：**

* 一个可访问 Codex 的 OpenAI 账户

**设置：**

1. 安装 Codex CLI：

```bash
npm install -g @openai/codex
```

2. 进入你的文档目录。
3. （可选）将下面的 `AGENTS.md` 文件添加到你的项目中。
4. 运行 `codex` 启动会话。

有关安装替代方案和身份验证选项，请参阅 [Codex CLI 文档](https://developers.openai.com/codex/cli)。

<div id="use-codex-with-mintlify">
  ## 将 Codex 与 Mintlify 配合使用 [#将-codex-与-mintlify-配合使用]
</div>

Codex 会在开始工作之前读取仓库中的 `AGENTS.md` 文件，以了解项目特定的规则和约定。你可以在文档仓库的根目录中放置一个 `AGENTS.md` 文件，为 Codex 提供有关 Mintlify 组件、写作标准以及你如何组织文档结构的 context。

Codex 会在多个层级发现 `AGENTS.md` 文件：

* **全局说明**位于 `~/.codex/AGENTS.md`，适用于你的所有项目。
* **项目说明**位于你的仓库根目录（或任何子目录），适用于该范围内的工作。

Codex 会将这些文件从根目录到当前目录依次拼接，因此项目级说明会扩展或覆盖全局说明。

在你的文档仓库根目录创建 `AGENTS.md` 并提交，让所有贡献者都能受益于相同的 context。完整详情请参阅 Codex 文档中的 [AGENTS.md](https://developers.openai.com/codex/guides/agents-md)。

<div id="example-agentsmd">
  ## 示例 AGENTS.md [#示例-agentsmd]
</div>

此文件为 Codex 提供有关 Mintlify 组件和技术写作标准的 context。

根据你的文档进行自定义：

* **写作标准**：更新语言规范以符合你的风格指南。
* **组件模式**：添加项目特定的组件，或修改现有示例。
* **代码示例**：将通用示例替换为与你的产品相关的真实 API 调用与响应。
* **风格与语气偏好**：调整术语、格式和其他规则。

将其保存为文档仓库根目录中的 `AGENTS.md`。

```markdown title="AGENTS.md"
# Mintlify documentation project

## Project context

- This is a documentation project on the Mintlify platform
- We use MDX files with YAML frontmatter
- Navigation is configured in `docs.json`
- We follow technical writing best practices

## Writing standards

- Use second person ("you") for instructions
- Write in active voice and present tense
- Use sentence case for headings ("Getting started", not "Getting Started")
- Start procedures with prerequisites
- Include expected outcomes for major steps
- Keep sentences concise but informative
- Never use marketing language ("powerful", "seamless", "robust")

## Required page structure

Every page must start with frontmatter:

---
title: "Clear, specific title"
description: "Concise description for SEO and navigation."
keywords: ["relevant", "keywords", "here"]
---

## Mintlify components

### docs.json

- Refer to the [docs.json schema](https://mintlify.com/docs.json) when modifying navigation or site settings

### Callouts

- `<Note>` for helpful supplementary information
- `<Warning>` for important cautions and breaking changes
- `<Tip>` for best practices and expert advice
- `<Info>` for neutral contextual information
- `<Check>` for success confirmations

### Code examples

- All code blocks must have a language tag
- Use `<CodeGroup>` for multiple language examples
- Use `<RequestExample>` and `<ResponseExample>` for API docs

### Procedures

- Use `<Steps>` for sequential instructions
- Include verification steps with `<Check>` when relevant

### Content organization

- Use `<Tabs>` for platform-specific content
- Use `<Accordion>` for progressive disclosure
- Use `<Card>` and `<CardGroup>` for highlighting content
- Wrap images in `<Frame>` with descriptive alt text

## Internal links

Use root-relative paths: `/guides/quickstart`, not `../quickstart` or full URLs.

## Quality checklist

Before finishing any documentation task:
- Verify all code blocks have language tags
- Check that frontmatter includes title, description, and keywords
- Confirm internal links use root-relative paths
- Read changes aloud to catch awkward phrasing
```

<div id="working-with-codex">
  ## 使用 Codex [#使用-codex]
</div>

完成 `AGENTS.md` 的配置后，当你在文档仓库中启动会话时，Codex 会自动读取该文件。

<div id="example-prompts">
  ### 示例提示 [#示例提示]
</div>

**撰写新对象**：

```text wrap
在 guides/authentication.mdx 创建一个新页面，说明如何通过我们的 API 进行身份验证。包含 JavaScript 和 Python 的代码示例。
```

**改进现有对象**：

```text wrap
审查 docs/quickstart.mdx 并提出改进清晰度的建议。重点让步骤更易于理解，并确保正确使用组件。
```

**更新导航**：

```text wrap
我在 guides/webhooks.mdx 添加了一个新页面。请将其添加到 docs.json 中 Guides 部分的 guides/authentication 之后。
```

**保持一致性**：

```text wrap
检查此新页面是否符合 AGENTS.md 中的写作标准，并标记出任何问题。
```

<div id="enhance-with-mcp-server">
  ## 使用 MCP 服务器增强功能 [#使用-mcp-服务器增强功能]
</div>

将 Mintlify MCP 服务器连接到 Codex，使其在帮助你写作时可以搜索 Mintlify 文档。连接 MCP 服务器后，Codex 可以查阅组件用法和配置选项，无需离开终端。

将 MCP 服务器添加到位于 `~/.codex/config.toml` 的全局 Codex 配置中。如果该文件不存在，请先创建：

```toml
[mcp_servers.mintlify]
url = "https://mintlify.com/docs/mcp"
```

如需连接到你自己文档站点的 MCP 服务器，请将 URL 替换为你站点的 MCP 端点：

```toml
[mcp_servers.my-docs]
url = "https://your-docs.mintlify.site/mcp"
```

重启你的 `codex` 会话以使配置更改生效。要确认 MCP 服务器已连接，可向 Codex 提问 `Which MCP servers do you have access to?`——它应列出你刚才添加的条目。

使用 `config.toml` 会为你计算机上的每个 Codex 会话注册该 MCP 服务器。前面展示的会话内 skill 和 MCP 提示则可以在单个会话中按需加载相同的 context——当你需要一次性运行或无法编辑 `config.toml` 时，请使用该方式。

有关 MCP 服务器以及如何查找你站点 MCP 端点的更多信息，请参阅 [Model Context Protocol](/zh/ai/model-context-protocol)。