Transfer Codex Settings to Another Computer

Transfer Codex configuration by backing up both computers and merging reviewed config.toml, AGENTS.md, agent-role files, and skill folders. Sign in again and recreate secrets on the destination. Do not copy auth.json, session history, logs, caches, or the whole Codex state directory.

What you can transfer

• User configuration: ~/.codex/config.toml
• Optional user guidance: ~/.codex/AGENTS.md
• User skills: ~/.agents/skills/<skill-name>/
• User agent-role files referenced by your configuration, commonly under ~/.codex/agents/
• Project guidance and configuration: AGENTS.md, .codex/config.toml, .agents/skills/, and project agent-role files

Codex also reads nested project configuration and guidance. Keep shared files in version control when they are intentionally part of the repository.

What not to copy

Do not transfer accounts, authentication, auth.json, OS-keychain entries, history.jsonl, sessions, SQLite state, logs, caches, or other machine-local state under CODEX_HOME. Do not assume a provider token or MCP OAuth credential can be copied safely. Reauthenticate on the destination instead.

1. Back up source and destination

Quit Codex clients on both computers. On macOS or Linux:

cp -a ~/.codex ~/.codex.backup-before-transfer
cp -a ~/.agents ~/.agents.backup-before-transfer

Use an equivalent file copy on Windows. Back up existing destination folders before merging anything.

2. Review configuration before copying

Open config.toml and inventory the sections you use. Remove stale absolute paths and keep credentials out of the file. MCP servers should name environment variables instead of embedding their values:

[mcp_servers.team_api]
url = "https://api.example.com/mcp"
bearer_token_env_var = "TEAM_API_TOKEN"

Review agent-role config_file paths and supporting skill files. Relative paths must still resolve from the configuration or skill location on the destination.

3. Merge configuration on the destination

Install and launch Codex once, then quit it. Merge the reviewed user config.toml into ~/.codex/config.toml; do not replace the destination file wholesale. Copy user skills to ~/.agents/skills/ and only the agent-role files your merged configuration references.

For project configuration, use the repository’s normal workflow to carry AGENTS.md, .codex/config.toml, and .agents/skills/. Codex loads project configuration only for trusted projects, so review it before granting trust.

4. Reauthenticate and verify

Sign in on the destination. Set required environment variables in the shell or secure credential system used to start Codex. Then:

codex mcp list

Open Codex in a disposable project, inspect /mcp, invoke each transferred skill explicitly, and confirm the applicable AGENTS.md guidance. Verify both user and project configuration independently so a higher-precedence project setting does not hide a user-level problem.

Troubleshooting

• If Codex rejects config.toml, restore the backup and add transferred tables in small groups until the invalid entry is clear.
• If an MCP server cannot authenticate, recreate its environment variable or run codex mcp login <name> for OAuth.
• If a skill is missing, confirm its directory contains SKILL.md under ~/.agents/skills/ or <project>/.agents/skills/.
• If an agent role fails, inspect its config_file path relative to the file that declared the role.
• If behavior differs from the source computer, compare project .codex/config.toml layers and repository AGENTS.md files before changing global config.

Official sources

These instructions were checked against the following vendor documentation.

• OpenAI: Advanced Codex configuration
• OpenAI: Codex configuration reference
• OpenAI: Build skills