# `Codex.Options`
[🔗](https://github.com/nshkrdotcom/codex_sdk/blob/v0.18.0/lib/codex/options.ex#L1)

Global configuration for Codex interactions.

Options are built from caller-supplied values merged with environment defaults.

## Models newer than the bundled registry

`Codex.Models` resolves model metadata from a bundled, vendored catalog
(via `CliSubprocessCore.ModelRegistry`). A model id that's newer than the
bundled catalog is passed through as-is by default — matching the
installed `codex` CLI, which does not itself validate `--model` against
this catalog. A warning is logged when this happens. Pass
`allow_unknown_model: false` to restore strict rejection of any model id
not present in the bundled catalog (useful for catching typos early).

# `t`

```elixir
@type t() :: %Codex.Options{
  agent_max_threads: pos_integer() | nil,
  allow_unknown_model: boolean(),
  api_key: String.t() | nil,
  base_url: String.t(),
  codex_path_override: String.t() | nil,
  config_overrides: [String.t() | {String.t(), config_override_value()}],
  execution_surface: CliSubprocessCore.ExecutionSurface.t(),
  governed_authority: Codex.GovernedAuthority.t() | nil,
  hide_agent_reasoning: boolean(),
  history_max_bytes: non_neg_integer() | nil,
  history_persistence: String.t() | nil,
  model: String.t() | nil,
  model_auto_compact_token_limit: pos_integer() | nil,
  model_context_window: pos_integer() | nil,
  model_payload: CliSubprocessCore.ModelRegistry.selection() | nil,
  model_personality: Codex.Protocol.ConfigTypes.personality() | nil,
  model_reasoning_summary: String.t() | nil,
  model_supports_reasoning_summaries: boolean() | nil,
  model_verbosity: String.t() | nil,
  reasoning_effort: Codex.Models.reasoning_effort() | nil,
  review_model: String.t() | nil,
  telemetry_prefix: [atom()],
  tool_output_token_limit: pos_integer() | nil
}
```

# `codex_command_spec`

```elixir
@spec codex_command_spec(
  t(),
  CliSubprocessCore.ExecutionSurface.t() | map() | keyword() | nil
) ::
  {:ok, CliSubprocessCore.CommandSpec.t()} | {:error, term()}
```

Determines a stable command spec for launching `codex`.

Local execution surfaces honor the shared core discovery policy:

1. Explicit override on the struct.
2. `CODEX_PATH`.
3. Shared local discovery through `CliSubprocessCore.ProviderCLI`.

Remote execution surfaces intentionally avoid local-path discovery. They use
an explicit override when supplied, otherwise they fall back to the remote
provider command name (`codex`).

# `codex_path`

```elixir
@spec codex_path(t()) :: {:ok, String.t()} | {:error, term()}
```

Determines the stable executable path to `codex`.

This returns the resolved program from `codex_command_spec/1`. Internal
launchers should prefer `codex_command_spec/1` so argv prefixes remain
available when needed.

# `new`

```elixir
@spec new(map() | keyword()) :: {:ok, t()} | {:error, term()}
```

Builds a validated options struct.

API keys are optional. When omitted, the Codex CLI relies on your existing
`codex` login (ChatGPT tokens stored in `auth.json`).

---

*Consult [api-reference.md](api-reference.md) for complete listing*