> ## Documentation Index
> Fetch the complete documentation index at: https://smartac-justin-client-exports.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 Codex 编写文档

> 通过项目说明和 MCP 配置 OpenAI Codex CLI，以编写遵循你的样式指南和 MDX 标准的 Mintlify 文档。

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

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

**前置条件：**

* 一个可访问 Codex 的 OpenAI 账户

**设置：**

1. 安装 Codex CLI：

```bash theme={null}
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 配合使用
</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
</div>

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

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

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

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

```markdown AGENTS.md theme={null}
# 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
</div>

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

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

**撰写新对象**：

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

**改进现有对象**：

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

**更新导航**：

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

**保持一致性**：

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

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

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

将 MCP 服务器添加到位于 `~/.codex/config.toml` 的全局 Codex 配置中：

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

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

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

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