Codex.Options (Codex SDK v0.16.1)

Copy Markdown View Source

Global configuration for Codex interactions.

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

Summary

Types

t()

Functions

codex_command_spec(opts, execution_surface_override \\ nil)

Determines a stable command spec for launching codex.

codex_path(opts)

Determines the stable executable path to codex.

new(attrs \\ %{})

Builds a validated options struct.

Types

t()

@type t() :: %Codex.Options{
  agent_max_threads: pos_integer() | nil,
  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(),
  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
}

Functions

codex_command_spec(opts, execution_surface_override \\ nil)

@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(opts)

@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(attrs \\ %{})

@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).