# Codex Configuration reference

> Codex: Reference for config.toml, auth.json, profiles, providers, models, permissions and environment variables.

URL: https://docs.passion8.cc/en/docs/codex/config-reference
Language: en
Publisher: Passion8

[Configuration](https://docs.passion8.cc/en/docs/codex/config) gets Passion8 working. This page explains configuration layers and common fields for team templates, profiles, CI and advanced permission policies.

## File locations

| File | Purpose |
| --- | --- |
| `~/.codex/config.toml` | User defaults |
| `~/.codex/auth.json` | File-based credential cache or API key |
| `~/.codex/<profile>.config.toml` | Named configuration loaded with `--profile` |
| `.codex/config.toml` | Project configuration, loaded only for trusted projects |
| `.codex/hooks.json` / `.codex/rules/` | Project hooks and rules |

Local state defaults to `~/.codex`. Setting `CODEX_HOME` moves configuration, authentication, logs, skills and sessions to that directory.

## Configuration precedence

From highest to lowest:

1. CLI flags and `-c key=value` overrides.
2. Project `.codex/config.toml` layers from the project root to the current directory; the closest wins.
3. `~/.codex/<name>.config.toml` selected by `--profile <name>`.
4. User `~/.codex/config.toml`.
5. System configuration, including applicable managed defaults.
6. Built-in defaults.




Project configuration is loaded only in trusted projects. Untrusted projects skip their configuration, hooks and rules. Enforced organizational requirements constrain allowed values independently of ordinary default precedence.




## Passion8 provider template

```toml title="~/.codex/config.toml"
model_provider = "Passion8"
cli_auth_credentials_store = "file"
forced_login_method = "api"
model = "gpt-6-sol"
review_model = "gpt-6-sol"
model_reasoning_effort = "medium"
model_context_window = 272000
model_auto_compact_token_limit = 250000
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

[model_providers.Passion8]
name = "Passion8"
wire_api = "responses"
requires_openai_auth = true
base_url = "https://passion8.cc/v1"
```

Store the credential in `~/.codex/auth.json`:

```json title="~/.codex/auth.json"
{
  "OPENAI_API_KEY": "YOUR_PASSION8_API_KEY"
}
```




Include `/v1`. Keep the key out of config.toml so sharing or synchronizing ordinary configuration does not expose credentials. These context values are the Passion8 gpt-6-sol client settings, not a universal official limit.




## Profiles

Profiles store common settings for deep reviews, read-only inspections or quick edits. Codex loads user configuration and overlays the profile file.

```toml title="~/.codex/deep-review.config.toml"
model = "gpt-6-sol"
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"
approval_policy = "on-request"
```

Start it with:

```bash
codex --profile deep-review
codex exec --profile deep-review "review this change"
```

Use top-level settings in the profile file, not `[profiles.deep-review]`. Select only reasoning levels supported by the chosen model.

## Common fields

| Field | Example | Meaning |
| --- | --- | --- |
| `model` | `"gpt-6-sol"` | Default model |
| `review_model` | `"gpt-6-sol"` | Optional model for review tasks |
| `model_provider` | `"Passion8"` | Selected provider |
| `model_reasoning_effort` | `"medium"` | Supported reasoning effort |
| `model_verbosity` | `"low"` | Response verbosity where supported |
| `model_context_window` | `272000` | Passion8 gpt-6-sol client limit; keep manual and CC Switch settings consistent |
| `model_auto_compact_token_limit` | `250000` | Compaction threshold below that client window; check other routes separately |
| `approval_policy` | `"on-request"` | When approval is required |
| `sandbox_mode` | `"workspace-write"` | File and command execution boundary |
| `web_search` | `"cached"` | cached / indexed / live / disabled |
| `personality` | `"pragmatic"` | Communication style |
| `log_dir` | `"./.codex-log"` | Plaintext diagnostic log directory |

## Project configuration restrictions

Project `.codex/config.toml` is appropriate for repository-specific defaults, hooks, rules and instruction discovery settings. It is not the place for provider routing or credentials.

Codex ignores or warns about sensitive project-local keys including:

- `model_provider`
- `model_providers`
- `openai_base_url`
- `chatgpt_base_url`
- `profile`
- `profiles`
- `notify`
- `otel`

Keep these in user or administrator configuration instead.

## Environment variables

| Variable | Purpose |
| --- | --- |
| `CODEX_HOME` | Changes the local state directory |
| `CODEX_API_KEY` | API key for a `codex exec` invocation |
| `CODEX_ACCESS_TOKEN` | Codex access token for trusted automation |
| `CODEX_CA_CERTIFICATE` | Enterprise TLS proxy or private CA |
| `RUST_LOG` | CLI / app-server log level |

Scope automation keys to the command that needs them instead of exposing them to every subsequent CI step.

## Web search

```toml
web_search = "cached"   # OpenAI-maintained cached results
# web_search = "live"   # Live access, equivalent to --search
# web_search = "disabled"
```

Live search increases exposure to untrusted content. Treat webpages, issues, README files and embedded instructions as untrusted input. Gateway availability of search features must be verified separately.

## Diagnostic commands

```bash
codex --version
codex doctor
codex --strict-config
codex -c log_dir=./.codex-log
```

In the TUI:

```text
/status
/debug-config
/model
/permissions
```

## Official references

- [Configuration basics](https://developers.openai.com/codex/config-basic)
- [Advanced configuration](https://developers.openai.com/codex/config-advanced)
- [Configuration reference](https://developers.openai.com/codex/config-reference)
- [Codex manual: environment variables](https://developers.openai.com/codex/codex-manual.md)