# Configuration & authorization

[Back to README](../README.md) · [简体中文](configuration.zh.md)

## Credentials

The adapter reads and writes the Codex OAuth document at `$DSH_HOME/.openai-codex-auth.json` (`~/.dsh` when `$DSH_HOME` is unset), in the format the Codex CLI login already produced:

```json
{ "version": 1, "credential": { "type": "oauth", "access": "…", "refresh": "…", "expires": 0 } }
```

An existing login therefore keeps working, refreshes write the same document, and no re-login is needed. The file is written `0600` by atomic rename; a malformed document fails loudly rather than degrading to a partial credential. Set `credentialFile` to an absolute path to point at another document.

Inside a harness the credential lives in one `ctx.credentials` record instead, and that is where a sign-in through the settings card lands. A populated record always wins; while it is still empty the document is read as well, so a CLI login (or one imported from the Codex CLI) works without signing in again — and the first refresh adopts it into the record, leaving exactly one writer afterwards. Signing out clears both planes, because a credential that reads fall back to must not survive a sign-out.

## Configuration

| Field | Default | Meaning |
| --- | --- | --- |
| `credentialFile` | `$DSH_HOME/.openai-codex-auth.json` | Absolute path of the Codex OAuth document. |
| `displayName` | `Codex` | Name shown by model-selection surfaces. |
| `streamIdleTimeoutMs` | `300000` | Provider-idle interval before a stream is failed. |
| `requestImagePixelBudget` | `2560000` | Total-pixel budget for request images. |
| `requestImageMaxBytes` | `1073741824` | Per-image byte cap for request images. |
| `imagegen.enabled` | `true` | Allow the `imagegen` tool to call the Codex image endpoints. |
| `imagegen.model` | `gpt-image-2` | Image model requested by `imagegen`. |
| `search.enabled` | `true` | Offer this route to `ctx.web`; a deployment selects it by naming `openai-codex`. |
| `search.model` | `gpt-5.6-sol` | Model the standalone search endpoint runs. |
| `search.mode` | `cached` | `cached`, `indexed`, or `live` server-side retrieval. |
| `search.contextSize` | `medium` | `low`, `medium`, or `high` search context. |
| `search.maxOutputTokens` | `10000` | Output budget for one search response. |

## Where this configuration lives

Three planes, in the order the loader and the settings document apply:

| Plane | File | What it decides |
| --- | --- | --- |
| Bundle composition | this package's `cordis.patch.yml` | The route default: it overrides the harness `agent-default-model` row (`provider: openai-codex`, `model: gpt-5.6-sol`) and inserts our row with the defaults above. |
| Your profile | `$DSH_HOME/profiles/<name>/cordis.patch.yml`, or `--patch <file>` | Per-deployment overrides. A patch replaces a row's **whole** `config` value, so restate every key. |
| Settings document | `$DSH_HOME/settings.yaml` (hot-reloaded; what the UI writes) | The saved model selection. `agent-default-model:` here **wins over** the composition default. |

```yaml
# $DSH_HOME/profiles/web/cordis.patch.yml — override our row without touching the package
- id: llm-openai-codex-adapter
  config:
    displayName: Codex (work)
    credentialFile: /Users/me/.codex/alt-auth.json
    streamIdleTimeoutMs: 600000
    requestImagePixelBudget: 2560000
    requestImageMaxBytes: 1073741824
```

```yaml
# $DSH_HOME/settings.yaml — make Codex the default model (equivalent to picking it in the UI)
agent-default-model:
  provider: openai-codex
  model: gpt-5.6-sol
```

The harness's own `llm-pi-ai:` settings section configures its dormant pi-ai adapter for **API-key** routes; this adapter owns the Codex **OAuth** route, so that section does not describe it.

## Authorization

The route needs a Codex OAuth credential. It reads the document the adapter also writes, so an existing login keeps working and token refreshes are written back by pi-ai under the store lock. Expiry is visible without exposing the token:

```sh
dsh-codex-adapter status      # metadata only: account, expiry, refresh presence
```

| Command | What it does |
| --- | --- |
| `status` | Reports the stored credential's metadata. Never prints tokens. |
| `login` | Runs the provider's own OAuth flow, printing the URL or device code it issues and forwarding what it asks. |
| `logout` | Removes the credential document. |
| `import [path]` | Copies the Codex CLI login (`$CODEX_HOME/auth.json`, default `~/.codex/auth.json`) into this adapter's document — no network, no browser. |

With the bundle installed, the binary is linked in the profile:

```sh
cd "$DSH_HOME/profiles/web" && pnpm exec dsh-codex-adapter status
# or
node "$DSH_HOME/profiles/web/node_modules/dsh-codex-adapter/lib/cli.js" status
```

`--credential-file <path>` points any command at another document, so an import can be staged before it replaces the live credential.

Re-login is needed only when the refresh chain breaks: `status` reports `expired: true`, or a request fails with an auth error. Importing the Codex CLI document is the cheapest recovery; `login` is the one that does not depend on the CLI being installed.