DownloadCodex Unofficial guide
English

Set up Codex

After installing Codex, set it up in this order. Sign in with ChatGPT or an API key, then run a small first task inside a Git repository. Add an AGENTS.md file with your project's rules. Adjust ~/.codex/config.toml for model, approvals, and sandbox. Connect MCP servers only when you need outside tools.

Where Codex keeps its settings

FileScopeWhat it’s for
~/.codex/config.tomlYou, everywhereModel, approvals, sandbox, MCP servers
.codex/config.toml in a repoThat project (trusted projects only)Project overrides
~/.codex/AGENTS.mdYou, everywhereYour personal working agreements
AGENTS.md in a repoThat project and its subfoldersProject conventions, test commands, rules
~/.codex/auth.jsonYouCached sign-in, if file storage is used. Keep it private.

~/.codex is the default Codex home. Set the CODEX_HOME environment variable to use a different folder.

Shortcut: our config generator builds a starter config.toml and AGENTS.md from a few choices.

In this section

  • Run your first Codex task A careful first session with Codex: start in a Git repo, ask it to explain the project, make one small reviewed change, and learn to undo anything you don't want.
  • Sign in to Codex: ChatGPT account or API key Choose between signing in to Codex with ChatGPT or an OpenAI API key, sign in on SSH and headless machines with device codes, and keep auth.json safe.
  • Configure Codex with config.toml Where Codex's config.toml lives, how project and user settings override each other, and the options people change most: model, approval policy, sandbox, web search.
  • Give Codex standing instructions with AGENTS.md How Codex discovers AGENTS.md files, how global and nested project files combine, how overrides work, and how to check which instructions Codex loaded.
  • Connect MCP servers to Codex Add Model Context Protocol servers to Codex with codex mcp add, the desktop app, the IDE extension, or config.toml, with STDIO and HTTP examples.
  • Codex sandbox and approvals What Codex's sandbox_mode and approval_policy settings do, safe defaults, the Windows sandbox, and why OpenAI warns against full access mode.

Sources

We link to the official source for every instruction on this page. If anything here disagrees with them, trust the official source and tell us.

Read next