Codex
Codex é o agente de código em nuvem da OpenAI para tarefas assíncronas em lote sobre repositórios GitHub.
Codex é o agente de código em nuvem da OpenAI. Ele roda sobre os seus repositórios do GitHub. Você não precisa de um ambiente local.
Codex e Claude Code diferem principalmente no fluxo de trabalho. O Codex roda na nuvem e trabalha de forma assíncrona. Você descreve um bloco de trabalho, se afasta e revisa um PR quando ele termina. Isso se encaixa em tarefas em lote (dividir um README de 500 linhas em uma dúzia de páginas, ou gerar uma página de solução de problemas a partir dos seus últimos seis meses de issues no GitHub). Não se encaixa bem no vaivém de refinar uma única página. Use o Claude Code para trabalho interativo em uma página por vez.
Configuração rápida
Abra o seu repositório GitHub de documentação Jamdesk no Codex.
Crie um arquivo AGENTS.md na raiz do projeto com os seus padrões de documentação. O Codex segue as convenções definidas nele.
Adicione o endpoint MCP da sua documentação em .codex/config.toml. Assim, o Codex pode pesquisar a sua documentação publicada.
Modelo de AGENTS.md
Crie AGENTS.md na raiz do projeto:
# Jamdesk Documentation Project
Jamdesk docs project. Pages are MDX (Markdown + React components). Config is in `docs.json`.
## How This Project Works
- `docs.json`: navigation structure, theme, colors, branding. Pages must be listed here to appear in the sidebar.
- `*.mdx` files: documentation pages. Every page needs `title` and `description` frontmatter.
- `images/`: static assets. Always use `.webp` format.
- `snippets/`: reusable MDX fragments. Import with `<Snippet file="name.mdx" />`.
## Page Template
Every page follows this structure:
---
title: Clear, Specific Title
description: One sentence. Used in search results and social previews.
---
Opening paragraph: what this page covers and who it's for. No heading needed.
## First Section
Content. Use components where they help, not for decoration.
## What's Next?
<Columns cols={2}>
<Card title="Related Page" icon="arrow-right" href="/path">
Why the reader would go here next
</Card>
</Columns>
The opening paragraph comes right after frontmatter with no heading. "What's Next?" is always the last section. Card descriptions explain why, not what.
## Writing Style
Start with why. What problem does this solve? Show the answer first, then unpack the how.
Use progressive disclosure: simple example up top, advanced options tucked into Accordions or later sections.
Active voice. "Run this command", not "This command should be run".
One idea per paragraph. If you find yourself reaching for "also" or "additionally", that's the cue to start a new paragraph instead.
Code examples have to actually work. Every block should be complete and copy-pasteable, never partial or pseudocode.
And write like a person. No filler ("It's important to note that", "This allows you to"). No hedging ("you might want to consider"). If a paragraph reads like a chatbot wrote it, rewrite it shorter.
## Components
Only use these. Do not invent others.
Layout: Card, Columns, Tabs, Tab, Accordion, AccordionGroup, Steps, Step, Expandable, Frame, CodeGroup
Callouts: Note, Info, Warning, Tip, Check, Danger
| Use | For | Don't use for |
|-----|-----|---------------|
| Tabs | Mutually exclusive choices (npm/yarn, OS) | Sequential content |
| Steps | Ordered procedures | Unordered lists |
| Accordion | Optional/advanced detail | Core content |
| Card + Columns | Navigation links, feature grids | Inline content |
| Note/Tip/Warning | Important context | Every other paragraph |
Cards always go inside Columns:
<Columns cols={2}>
<Card title="Page Title" icon="icon-name" href="/path">
Brief description
</Card>
</Columns>
Icons are Font Awesome Light names: "rocket", "code", "terminal", "book-open", "gear"
## Adding Pages
1. Create the `.mdx` file
2. Add the page path (no `.mdx` extension) to `docs.json` in the right navigation group
3. Link to it from related pages via "What's Next?" cards
If you skip step 2, the page won't show up in the sidebar. Read `docs.json` before creating pages so you understand the navigation structure.
## Common Mistakes
- Inventing components like `<CodeBlock>`, `<Alert>`, `<Section>`. They don't exist.
- Using `<Card>` without a `<Columns>` wrapper.
- Skipping `description` in frontmatter, which breaks search results and link previews.
- Using raw HTML tags instead of MDX components.
- Writing "click here" links instead of descriptive link text.Adicione a terminologia do seu produto, as convenções de nomenclatura de API e quaisquer regras de estilo específicas da sua documentação.
Configuração do MCP
Adicione o endpoint da sua documentação em .codex/config.toml:
[mcp_servers.my-docs]
url = "https://your-project.jamdesk.app/_mcp"Substitua your-project pelo seu subdomínio Jamdesk. Se você já tiver um domínio personalizado ativo, use-o no lugar: url = "https://docs.acme.com/_mcp". Veja Servidor MCP para os detalhes do endpoint.
Prompts de exemplo
O Codex executa tarefas de forma assíncrona. Envie uma tarefa longa e volte depois para conferir. Prompts que pedem um bloco de trabalho rendem melhor.
Uma boa primeira tentativa: "Escreva a documentação da API de autenticação com base no código em /src/auth". O Codex lê a sua base de código, encontra os arquivos relevantes e gera páginas correspondentes. Aponte-o para o seu histórico de bugs para trabalhos mais confusos. "Crie uma página de solução de problemas cobrindo os 5 erros mais comuns nas nossas issues do GitHub" tende a produzir uma página mais precisa do que qualquer coisa que você escreveria de memória.
Reestruturações de vários arquivos funcionam bem neste modo. Copie este prompt no Codex para uma tarefa com critérios de revisão claros:
Reestruturar um README grande
A skill /update-jamdesk
Instale a skill /update-jamdesk para atualizar a documentação automaticamente quando o código mudar:
npx skills add jamdesk/skills --skill update-jamdesk -a codex
Veja Atualizações automáticas para o guia completo.
