fengming 0.3.9 → 0.3.11

package/docs/providers/openai.md

@@ -1,1093 +0,0 @@
----
-summary: "Use OpenAI via API keys or Codex subscription in FengMing"
-read_when:
-  - You want to use OpenAI models in FengMing
-  - You want Codex subscription auth instead of API keys
-  - You need stricter GPT-5 agent execution behavior
-title: "OpenAI"
----
-
-OpenAI provides developer APIs for GPT models, and Codex is also available as a
-ChatGPT-plan coding agent through OpenAI's Codex clients. FengMing uses one
-provider id, `openai`, for both auth shapes.
-
-FengMing uses `openai/*` as the canonical OpenAI model route. Embedded agent
-turns on OpenAI models run through the native Codex app-server runtime by
-default; direct OpenAI API-key auth remains available for non-agent OpenAI
-surfaces such as images, embeddings, speech, and realtime.
-
-- **Agent models** - `openai/*` models through the Codex runtime; sign in with
-  Codex auth for ChatGPT/Codex subscription use, or configure a Codex-compatible
-  OpenAI API-key backup when you intentionally want API-key auth.
-- **Non-agent OpenAI APIs** - direct OpenAI Platform access with usage-based
-  billing through `OPENAI_API_KEY` or OpenAI API-key onboarding.
-- **Legacy config** - `openai-codex/*` model refs are repaired by
-  `fengming doctor --fix` to `openai/*` plus the Codex runtime.
-
-OpenAI explicitly supports subscription OAuth usage in external tools and workflows like FengMing.
-
-Provider, model, runtime, and channel are separate layers. If those labels are
-getting mixed together, read [Agent runtimes](/concepts/agent-runtimes) before
-changing config.
-
-## Quick choice
-
-| Goal                                                 | Use                                                      | Notes                                                                 |
-| ---------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------- |
-| ChatGPT/Codex subscription with native Codex runtime | `openai/gpt-5.5`                                         | Default OpenAI agent setup. Sign in with Codex auth.                  |
-| Direct API-key billing for agent models              | `openai/gpt-5.5` plus a Codex-compatible API-key profile | Use `auth.order.openai` to place the backup after subscription auth.  |
-| Direct API-key billing through explicit FengMing     | `openai/gpt-5.5` plus provider/model runtime `fengming`  | Select a normal `openai` API-key profile.                             |
-| Latest ChatGPT Instant API alias                     | `openai/chat-latest`                                     | Direct API-key only. Moving alias for experiments, not the default.   |
-| ChatGPT/Codex subscription auth through FengMing     | `openai/gpt-5.5` plus provider/model runtime `fengming`  | Select an `openai` OAuth profile for the compatibility route.         |
-| Image generation or editing                          | `openai/gpt-image-2`                                     | Works with either `OPENAI_API_KEY` or OpenAI Codex OAuth.             |
-| Transparent-background images                        | `openai/gpt-image-1.5`                                   | Use `outputFormat=png` or `webp` and `openai.background=transparent`. |
-
-## Naming map
-
-The names are similar but not interchangeable:
-
-| Name you see                            | Layer             | Meaning                                                                                           |
-| --------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
-| `openai`                                | Provider prefix   | Canonical OpenAI model route; agent turns use the Codex runtime.                                  |
-| `openai-codex`                          | Legacy prefix     | Older model/profile namespace. `fengming doctor --fix` migrates it to `openai`.                   |
-| `codex` plugin                          | Plugin            | Bundled FengMing plugin that provides native Codex app-server runtime and `/codex` chat controls. |
-| provider/model `agentRuntime.id: codex` | Agent runtime     | Force the native Codex app-server harness for matching embedded turns.                            |
-| `/codex ...`                            | Chat command set  | Bind/control Codex app-server threads from a conversation.                                        |
-| `runtime: "acp", agentId: "codex"`      | ACP session route | Explicit fallback path that runs Codex through ACP/acpx.                                          |
-
-This means a config can intentionally contain `openai/*` model refs while auth
-profiles point at either API-key or ChatGPT/Codex OAuth credentials. Use
-`auth.order.openai` for config; `fengming doctor --fix` rewrites legacy
-`openai-codex/*` model refs, `openai-codex:*` profile ids, and
-`auth.order.openai-codex` to the canonical OpenAI route.
-
-<Note>
-GPT-5.5 is available through both direct OpenAI Platform API-key access and
-subscription/OAuth routes. For ChatGPT/Codex subscription plus native Codex
-execution, use `openai/gpt-5.5`; unset runtime config now selects the Codex
-harness for OpenAI agent turns. Use OpenAI API-key profiles only when you want
-direct API-key auth for an OpenAI agent model.
-</Note>
-
-<Note>
-OpenAI agent model turns require the bundled Codex app-server plugin. Explicit
-FengMing runtime config remains available as an opt-in compatibility route. When FengMing is
-explicitly selected with an `openai` OAuth profile, FengMing keeps the
-public model ref as `openai/*` and routes internally through the Codex-auth
-transport. Run `fengming doctor --fix` to repair stale
-`openai-codex/*`, `codex-cli/*`, or old runtime session pins that do not come from
-explicit runtime config.
-</Note>
-
-## FengMing feature coverage
-
-| OpenAI capability         | FengMing surface                                                                              | Status                                                                 |
-| ------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| Chat / Responses          | `openai/<model>` model provider                                                               | Yes                                                                    |
-| Codex subscription models | `openai/<model>` with OpenAI OAuth                                                            | Yes                                                                    |
-| Legacy Codex model refs   | `openai-codex/<model>` or `codex-cli/<model>`                                                 | Repaired by doctor to `openai/<model>`                                 |
-| Codex app-server harness  | `openai/<model>` with omitted runtime or provider/model `agentRuntime.id: codex`              | Yes                                                                    |
-| Server-side web search    | Native OpenAI Responses tool                                                                  | Yes, when web search is enabled and no provider pinned                 |
-| Images                    | `image_generate`                                                                              | Yes                                                                    |
-| Videos                    | `video_generate`                                                                              | Yes                                                                    |
-| Text-to-speech            | `messages.tts.provider: "openai"` / `tts`                                                     | Yes                                                                    |
-| Batch speech-to-text      | `tools.media.audio` / media understanding                                                     | Yes                                                                    |
-| Streaming speech-to-text  | Voice Call `streaming.provider: "openai"`                                                     | Yes                                                                    |
-| Realtime voice            | Voice Call `realtime.provider: "openai"` / Control UI Talk `talk.realtime.provider: "openai"` | Yes (requires OpenAI Platform credits, not Codex/ChatGPT subscription) |
-| Embeddings                | memory embedding provider                                                                     | Yes                                                                    |
-
-<Note>
-  OpenAI Realtime voice (used by Voice Call's `realtime.provider: "openai"` and
-  Control UI Talk with `talk.realtime.provider: "openai"`) goes through the
-  public **OpenAI Platform Realtime API**, which is billed against OpenAI
-  Platform credits rather than Codex/ChatGPT subscription quota. An account
-  with healthy OpenAI OAuth that runs Codex-backed chat models without
-  issue can still hit `insufficient_quota` / "You exceeded your current
-  quota" on the first Realtime turn if the same OpenAI organization has no
-  Platform billing set up.
-
-Fix: top up Platform credits at
-[platform.openai.com/account/billing](https://platform.openai.com/account/billing)
-for the organization backing your realtime credentials. Realtime accepts
-either a Platform `OPENAI_API_KEY` (configured via `talk.realtime.providers.openai.apiKey`
-for Control UI Talk, or `plugins.entries.voice-call.config.realtime.providers.openai.apiKey`
-for Voice Call) or an `openai` OAuth profile whose underlying
-organization has Platform billing — both routes mint Realtime client secrets
-through the Platform API, so either way the org needs funded Platform
-credits. For chat turns you can still use Codex-backed `openai/*` models against the same
-FengMing install; Realtime is the one route that needs Platform billing.
-</Note>
-
-## Memory embeddings
-
-FengMing can use OpenAI, or an OpenAI-compatible embedding endpoint, for
-`memory_search` indexing and query embeddings:
-
-```json5
-{
-  agents: {
-    defaults: {
-      memorySearch: {
-        provider: "openai",
-        model: "text-embedding-3-small",
-      },
-    },
-  },
-}
-```
-
-For OpenAI-compatible endpoints that require asymmetric embedding labels, set
-`queryInputType` and `documentInputType` under `memorySearch`. FengMing forwards
-those as provider-specific `input_type` request fields: query embeddings use
-`queryInputType`; indexed memory chunks and batch indexing use
-`documentInputType`. See the [Memory configuration reference](/reference/memory-config#provider-specific-config) for the full example.
-
-## Getting started
-
-Choose your preferred auth method and follow the setup steps.
-
-<Tabs>
-  <Tab title="API key (OpenAI Platform)">
-    **Best for:** direct API access and usage-based billing.
-
-    <Steps>
-      <Step title="Get your API key">
-        Create or copy an API key from the [OpenAI Platform dashboard](https://platform.openai.com/api-keys).
-      </Step>
-      <Step title="Run onboarding">
-        ```bash
-        fengming onboard --auth-choice openai-api-key
-        ```
-
-        Or pass the key directly:
-
-        ```bash
-        fengming onboard --openai-api-key "$OPENAI_API_KEY"
-        ```
-      </Step>
-      <Step title="Verify the model is available">
-        ```bash
-        fengming models list --provider openai
-        ```
-      </Step>
-    </Steps>
-
-    ### Route summary
-
-    | Model ref              | Runtime config             | Route                       | Auth             |
-    | ---------------------- | -------------------------- | --------------------------- | ---------------- |
-    | `openai/gpt-5.5`      | omitted / provider/model `agentRuntime.id: "codex"` | Codex app-server harness | Codex-compatible OpenAI profile |
-    | `openai/gpt-5.4-mini` | omitted / provider/model `agentRuntime.id: "codex"` | Codex app-server harness | Codex-compatible OpenAI profile |
-    | `openai/gpt-5.5`      | provider/model `agentRuntime.id: "fengming"`              | FengMing embedded runtime      | Selected `openai` profile |
-
-    <Note>
-    `openai/*` agent models use the Codex app-server harness. To use API-key
-    auth for an agent model, create a Codex-compatible API-key profile and order
-    it with `auth.order.openai`; `OPENAI_API_KEY` remains the direct fallback for
-    non-agent OpenAI API surfaces. Run `fengming doctor --fix` to migrate older
-    `auth.order.openai-codex` entries.
-    </Note>
-
-    ### Config example
-
-    ```json5
-    {
-      env: { OPENAI_API_KEY: "example-openai-key-not-real" },
-      agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
-    }
-    ```
-
-    To try ChatGPT's current Instant model from the OpenAI API, set the model
-    to `openai/chat-latest`:
-
-    ```json5
-    {
-      env: { OPENAI_API_KEY: "example-openai-key-not-real" },
-      agents: { defaults: { model: { primary: "openai/chat-latest" } } },
-    }
-    ```
-
-    `chat-latest` is a moving alias. OpenAI documents it as the latest Instant
-    model used in ChatGPT and recommends `gpt-5.5` for production API usage, so
-    keep `openai/gpt-5.5` as the stable default unless you explicitly want that
-    alias behavior. The alias currently accepts only `medium` text verbosity, so
-    FengMing normalizes incompatible OpenAI text-verbosity overrides for this
-    model.
-
-    <Warning>
-    FengMing does **not** expose `gpt-5.3-codex-spark` on the direct OpenAI API-key route. It is available only through Codex subscription catalog entries when your signed-in account exposes it.
-    </Warning>
-
-  </Tab>
-
-  <Tab title="Codex subscription">
-    **Best for:** using your ChatGPT/Codex subscription with native Codex app-server execution instead of a separate API key. Codex cloud requires ChatGPT sign-in.
-
-    <Steps>
-      <Step title="Run Codex OAuth">
-        ```bash
-        fengming onboard --auth-choice openai
-        ```
-
-        Or run OAuth directly:
-
-        ```bash
-        fengming models auth login --provider openai
-        ```
-
-        For headless or callback-hostile setups, add `--device-code` to sign in with a ChatGPT device-code flow instead of the localhost browser callback:
-
-        ```bash
-        fengming models auth login --provider openai --device-code
-        ```
-      </Step>
-      <Step title="Use the canonical OpenAI model route">
-        ```bash
-        fengming config set agents.defaults.model.primary openai/gpt-5.5
-        ```
-
-        No runtime config is required for the default path. OpenAI agent turns
-        select the native Codex app-server runtime automatically, and FengMing
-        installs or repairs the bundled Codex plugin when this route is chosen.
-      </Step>
-      <Step title="Verify Codex auth is available">
-        ```bash
-        fengming models list --provider openai
-        ```
-
-        After the gateway is running, send `/codex status` or `/codex models`
-        in chat to verify the native app-server runtime.
-      </Step>
-    </Steps>
-
-    ### Route summary
-
-    | Model ref | Runtime config | Route | Auth |
-    |-----------|----------------|-------|------|
-    | `openai/gpt-5.5` | omitted / provider/model `agentRuntime.id: "codex"` | Native Codex app-server harness | Codex sign-in or ordered `openai` auth profile |
-    | `openai/gpt-5.5` | provider/model `agentRuntime.id: "fengming"` | FengMing embedded runtime with internal Codex-auth transport | Selected `openai` OAuth profile |
-    | `openai-codex/gpt-5.5` | repaired by doctor | Legacy route rewritten to `openai/gpt-5.5` | Migrated OpenAI OAuth profile |
-    | `codex-cli/gpt-5.5` | repaired by doctor | Legacy CLI route rewritten to `openai/gpt-5.5` | Codex app-server auth |
-
-    <Warning>
-    Prefer `openai/gpt-5.5` for new subscription-backed agent config. Older
-    `openai-codex/gpt-*` refs are legacy FengMing routes, not the native Codex runtime
-    path; run `fengming doctor --fix` when you want to migrate them to canonical
-    `openai/*` refs. `gpt-5.3-codex-spark` remains limited to accounts whose
-    Codex subscription catalog advertises that model; direct OpenAI API-key and
-    Azure refs for it remain suppressed.
-    </Warning>
-
-    <Note>
-    The `openai-codex/*` model prefix is legacy config repaired by doctor. For
-    the common subscription plus native runtime setup, sign in with Codex auth
-    but keep the model ref as `openai/gpt-5.5`. New config should put OpenAI
-    agent auth order under `auth.order.openai`; doctor migrates older
-    `auth.order.openai-codex` entries.
-    </Note>
-
-    ### Config example
-
-    ```json5
-    {
-      plugins: { entries: { codex: { enabled: true } } },
-      agents: {
-        defaults: {
-          model: { primary: "openai/gpt-5.5" },
-        },
-      },
-    }
-    ```
-
-    With an API-key backup, keep the model on `openai/gpt-5.5` and put the
-    auth order under `openai`. FengMing will try the subscription first, then
-    the API key, while staying on the Codex harness:
-
-    ```json5
-    {
-      plugins: { entries: { codex: { enabled: true } } },
-      agents: {
-        defaults: {
-          model: { primary: "openai/gpt-5.5" },
-        },
-      },
-      auth: {
-        order: {
-          openai: [
-            "openai:user@example.com",
-            "openai:api-key-backup",
-          ],
-        },
-      },
-    }
-    ```
-
-    <Note>
-    Onboarding no longer imports OAuth material from `~/.codex`. Sign in with browser OAuth (default) or the device-code flow above — FengMing manages the resulting credentials in its own agent auth store.
-    </Note>
-
-    ### Check and recover Codex OAuth routing
-
-    Use these commands to see which model, runtime, and auth route your default
-    agent is using:
-
-    ```bash
-    fengming models status
-    fengming models auth list --provider openai
-    fengming config get agents.defaults.model --json
-    fengming config get models.providers.openai.agentRuntime --json
-    ```
-
-    For a specific agent, add `--agent <id>`:
-
-    ```bash
-    fengming models status --agent <id>
-    fengming models auth list --agent <id> --provider openai
-    ```
-
-    If an older config still has `openai-codex/gpt-*` or a stale OpenAI runtime
-    session pin without explicit runtime config, repair it:
-
-    ```bash
-    fengming doctor --fix
-    fengming config validate
-    ```
-
-    If `models auth list --provider openai` shows no usable profile, sign
-    in again:
-
-    ```bash
-    fengming models auth login --provider openai
-    fengming models status --probe --probe-provider openai
-    ```
-
-    Use `--profile-id` when you want multiple Codex OAuth logins in the same
-    agent and later want to control them via auth ordering or `/model ...@<profileId>`:
-
-    ```bash
-    fengming models auth login --provider openai --profile-id openai:ritsuko
-    fengming models auth login --provider openai --profile-id openai:lain
-    ```
-
-    `openai/*` is the model route for OpenAI agent turns through Codex. Run
-    `fengming doctor --fix` to migrate older `openai-codex` profile ids and
-    order entries before relying on profile ordering.
-
-    ### Status indicator
-
-    Chat `/status` shows which model runtime is active for the current session.
-    The bundled Codex app-server harness appears as `Runtime: OpenAI Codex` for
-    OpenAI agent model turns. Stale OpenAI runtime session pins are repaired to Codex unless
-    config explicitly pins FengMing.
-
-    ### Doctor warning
-
-    If `openai-codex/*` routes or stale OpenAI runtime pins remain in config or
-    session state, `fengming doctor --fix` rewrites them to `openai/*` with the
-    Codex runtime unless FengMing is explicitly configured.
-
-    ### Context window cap
-
-    FengMing treats model metadata and the runtime context cap as separate values.
-
-    For `openai/gpt-5.5` through the Codex OAuth catalog:
-
-    - Native `contextWindow`: `1000000`
-    - Default runtime `contextTokens` cap: `272000`
-
-    The smaller default cap has better latency and quality characteristics in practice. Override it with `contextTokens`:
-
-    ```json5
-    {
-      models: {
-        providers: {
-          openai: {
-            models: [{ id: "gpt-5.5", contextTokens: 160000 }],
-          },
-        },
-      },
-    }
-    ```
-
-    <Note>
-    Use `contextWindow` to declare native model metadata. Use `contextTokens` to limit the runtime context budget.
-    </Note>
-
-    ### Catalog recovery
-
-    FengMing uses upstream Codex catalog metadata for `gpt-5.5` when it is
-    present. If live Codex discovery omits the `gpt-5.5` row while
-    the account is authenticated, FengMing synthesizes that OAuth model row so
-    cron, sub-agent, and configured default-model runs do not fail with
-    `Unknown model`.
-
-  </Tab>
-</Tabs>
-
-## Native Codex app-server auth
-
-The native Codex app-server harness uses `openai/*` model refs plus omitted
-runtime config or provider/model `agentRuntime.id: "codex"`, but its auth is
-still account-based. FengMing selects auth in this order:
-
-1. Ordered OpenAI auth profiles for the agent, preferably under
-   `auth.order.openai`. Run `fengming doctor --fix` to migrate older
-   `openai-codex:*` profiles and `auth.order.openai-codex`.
-2. The app-server's existing account, such as a local Codex CLI ChatGPT sign-in.
-3. For local stdio app-server launches only, `CODEX_API_KEY`, then
-   `OPENAI_API_KEY`, when the app-server reports no account and still requires
-   OpenAI auth.
-
-That means a local ChatGPT/Codex subscription sign-in is not replaced just
-because the gateway process also has `OPENAI_API_KEY` for direct OpenAI models
-or embeddings. Env API-key fallback is only the local stdio no-account path; it
-is not sent to WebSocket app-server connections. When a subscription-style Codex
-profile is selected, FengMing also keeps `CODEX_API_KEY` and `OPENAI_API_KEY`
-out of the spawned stdio app-server child and sends the selected credentials
-through the app-server login RPC. When that subscription profile is blocked by a
-Codex usage limit, FengMing can rotate to the next ordered `openai:*` API-key
-profile without changing the selected model or dropping out of the Codex
-harness. Once the subscription reset time passes, the subscription profile is
-eligible again.
-
-## Image generation
-
-The bundled `openai` plugin registers image generation through the `image_generate` tool.
-It supports both OpenAI API-key image generation and Codex OAuth image
-generation through the same `openai/gpt-image-2` model ref.
-
-| Capability                | OpenAI API key                     | Codex OAuth                          |
-| ------------------------- | ---------------------------------- | ------------------------------------ |
-| Model ref                 | `openai/gpt-image-2`               | `openai/gpt-image-2`                 |
-| Auth                      | `OPENAI_API_KEY`                   | OpenAI Codex OAuth sign-in           |
-| Transport                 | OpenAI Images API                  | Codex Responses backend              |
-| Max images per request    | 4                                  | 4                                    |
-| Edit mode                 | Enabled (up to 5 reference images) | Enabled (up to 5 reference images)   |
-| Size overrides            | Supported, including 2K/4K sizes   | Supported, including 2K/4K sizes     |
-| Aspect ratio / resolution | Not forwarded to OpenAI Images API | Mapped to a supported size when safe |
-
-```json5
-{
-  agents: {
-    defaults: {
-      imageGenerationModel: { primary: "openai/gpt-image-2" },
-    },
-  },
-}
-```
-
-<Note>
-See [Image Generation](/tools/image-generation) for shared tool parameters, provider selection, and failover behavior.
-</Note>
-
-`gpt-image-2` is the default for both OpenAI text-to-image generation and image
-editing. `gpt-image-1.5`, `gpt-image-1`, and `gpt-image-1-mini` remain usable as
-explicit model overrides. Use `openai/gpt-image-1.5` for transparent-background
-PNG/WebP output; the current `gpt-image-2` API rejects
-`background: "transparent"`.
-
-For a transparent-background request, agents should call `image_generate` with
-`model: "openai/gpt-image-1.5"`, `outputFormat: "png"` or `"webp"`, and
-`background: "transparent"`; the older `openai.background` provider option is
-still accepted. FengMing also protects the public OpenAI and
-OpenAI Codex OAuth routes by rewriting default `openai/gpt-image-2` transparent
-requests to `gpt-image-1.5`; Azure and custom OpenAI-compatible endpoints keep
-their configured deployment/model names.
-
-The same setting is exposed for headless CLI runs:
-
-```bash
-fengming infer image generate \
-  --model openai/gpt-image-1.5 \
-  --output-format png \
-  --background transparent \
-  --prompt "A simple red circle sticker on a transparent background" \
-  --json
-```
-
-Use the same `--output-format` and `--background` flags with
-`fengming infer image edit` when starting from an input file.
-`--openai-background` remains available as an OpenAI-specific alias.
-
-For ChatGPT/Codex OAuth installs, keep the same `openai/gpt-image-2` ref. When an
-`openai` OAuth profile is configured, FengMing resolves that stored OAuth
-access token and sends image requests through the Codex Responses backend. It
-does not first try `OPENAI_API_KEY` or silently fall back to an API key for that
-request. Configure `models.providers.openai` explicitly with an API key,
-custom base URL, or Azure endpoint when you want the direct OpenAI Images API
-route instead.
-If that custom image endpoint is on a trusted LAN/private address, also set
-`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; FengMing keeps
-private/internal OpenAI-compatible image endpoints blocked unless this opt-in is
-present.
-
-Generate:
-
-```
-/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for FengMing on macOS" size=3840x2160 count=1
-```
-
-Generate a transparent PNG:
-
-```
-/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent
-```
-
-Edit:
-
-```
-/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536
-```
-
-## Video generation
-
-The bundled `openai` plugin registers video generation through the `video_generate` tool.
-
-| Capability       | Value                                                                             |
-| ---------------- | --------------------------------------------------------------------------------- |
-| Default model    | `openai/sora-2`                                                                   |
-| Modes            | Text-to-video, image-to-video, single-video edit                                  |
-| Reference inputs | 1 image or 1 video                                                                |
-| Size overrides   | Supported for text-to-video and image-to-video                                    |
-| Other overrides  | `aspectRatio`, `resolution`, `audio`, `watermark` are ignored with a tool warning |
-
-OpenAI image-to-video requests use `POST /v1/videos` with an image
-`input_reference`. Single-video edits use `POST /v1/videos/edits` with the
-uploaded video in the `video` field.
-
-```json5
-{
-  agents: {
-    defaults: {
-      videoGenerationModel: { primary: "openai/sora-2" },
-    },
-  },
-}
-```
-
-<Note>
-See [Video Generation](/tools/video-generation) for shared tool parameters, provider selection, and failover behavior.
-</Note>
-
-## GPT-5 prompt contribution
-
-FengMing adds a shared GPT-5 prompt contribution for GPT-5-family runs on FengMing-assembled prompt surfaces. It applies by model id, so FengMing/provider routes such as legacy pre-repair refs (`openai-codex/gpt-5.5`), `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5`, and other compatible GPT-5 refs receive the same overlay. Older GPT-4.x models do not.
-
-The bundled native Codex harness does not receive this FengMing GPT-5 overlay through Codex app-server developer instructions. Native Codex keeps Codex-owned base, model, and project-doc behavior, while FengMing disables Codex's built-in personality for native threads so agent workspace personality files stay authoritative. FengMing contributes only runtime context such as channel delivery, FengMing dynamic tools, ACP delegation, workspace context, and FengMing skills.
-
-The GPT-5 contribution adds a tagged behavior contract for persona persistence, execution safety, tool discipline, output shape, completion checks, and verification on matching FengMing-assembled prompts. Channel-specific reply and silent-message behavior stays in the shared FengMing system prompt and outbound delivery policy. The friendly interaction-style layer is separate and configurable.
-
-| Value                  | Effect                                      |
-| ---------------------- | ------------------------------------------- |
-| `"friendly"` (default) | Enable the friendly interaction-style layer |
-| `"on"`                 | Alias for `"friendly"`                      |
-| `"off"`                | Disable only the friendly style layer       |
-
-<Tabs>
-  <Tab title="Config">
-    ```json5
-    {
-      agents: {
-        defaults: {
-          promptOverlays: {
-            gpt5: { personality: "friendly" },
-          },
-        },
-      },
-    }
-    ```
-  </Tab>
-  <Tab title="CLI">
-    ```bash
-    fengming config set agents.defaults.promptOverlays.gpt5.personality off
-    ```
-  </Tab>
-</Tabs>
-
-<Tip>
-Values are case-insensitive at runtime, so `"Off"` and `"off"` both disable the friendly style layer.
-</Tip>
-
-<Note>
-Legacy `plugins.entries.openai.config.personality` is still read as a compatibility fallback when the shared `agents.defaults.promptOverlays.gpt5.personality` setting is not set.
-</Note>
-
-## Voice and speech
-
-<AccordionGroup>
-  <Accordion title="Speech synthesis (TTS)">
-    The bundled `openai` plugin registers speech synthesis for the `messages.tts` surface.
-
-    | Setting | Config path | Default |
-    |---------|------------|---------|
-    | Model | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
-    | Voice | `messages.tts.providers.openai.speakerVoice` | `coral` |
-    | Speed | `messages.tts.providers.openai.speed` | (unset) |
-    | Instructions | `messages.tts.providers.openai.instructions` | (unset, `gpt-4o-mini-tts` only) |
-    | Format | `messages.tts.providers.openai.responseFormat` | `opus` for voice notes, `mp3` for files |
-    | API key | `messages.tts.providers.openai.apiKey` | Falls back to `OPENAI_API_KEY` |
-    | Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
-    | Extra body | `messages.tts.providers.openai.extraBody` / `extra_body` | (unset) |
-
-    Available models: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Available voices: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`.
-
-    `extraBody` is merged into `/audio/speech` request JSON after FengMing's generated fields, so use it for OpenAI-compatible endpoints that require additional keys such as `lang`. Prototype keys are ignored.
-
-    ```json5
-    {
-      messages: {
-        tts: {
-          providers: {
-            openai: { model: "gpt-4o-mini-tts", speakerVoice: "coral" },
-          },
-        },
-      },
-    }
-    ```
-
-    <Note>
-    Set `OPENAI_TTS_BASE_URL` to override the TTS base URL without affecting the chat API endpoint. OpenAI TTS is still configured through an API key; for OAuth-only live talk-back, use the Realtime voice path instead of agent-mode STT -> TTS speech.
-    </Note>
-
-  </Accordion>
-
-  <Accordion title="Speech-to-text">
-    The bundled `openai` plugin registers batch speech-to-text through
-    FengMing's media-understanding transcription surface.
-
-    - Default model: `gpt-4o-transcribe`
-    - Endpoint: OpenAI REST `/v1/audio/transcriptions`
-    - Input path: multipart audio file upload
-    - Supported by FengMing wherever inbound audio transcription uses
-      `tools.media.audio`, including Discord voice-channel segments and channel
-      audio attachments
-
-    To force OpenAI for inbound audio transcription:
-
-    ```json5
-    {
-      tools: {
-        media: {
-          audio: {
-            models: [
-              {
-                type: "provider",
-                provider: "openai",
-                model: "gpt-4o-transcribe",
-              },
-            ],
-          },
-        },
-      },
-    }
-    ```
-
-    Language and prompt hints are forwarded to OpenAI when supplied by the
-    shared audio media config or per-call transcription request.
-
-  </Accordion>
-
-  <Accordion title="Realtime transcription">
-    The bundled `openai` plugin registers realtime transcription for the Voice Call plugin.
-
-    | Setting | Config path | Default |
-    |---------|------------|---------|
-    | Model | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
-    | Language | `...openai.language` | (unset) |
-    | Prompt | `...openai.prompt` | (unset) |
-    | Silence duration | `...openai.silenceDurationMs` | `800` |
-    | VAD threshold | `...openai.vadThreshold` | `0.5` |
-    | Auth | `...openai.apiKey`, `OPENAI_API_KEY`, or `openai` OAuth | API keys connect directly; OAuth mints a Realtime transcription client secret |
-
-    <Note>
-    Uses a WebSocket connection to `wss://api.openai.com/v1/realtime` with G.711 u-law (`g711_ulaw` / `audio/pcmu`) audio. When only `openai` OAuth is configured, the Gateway mints an ephemeral Realtime transcription client secret before opening the WebSocket. This streaming provider is for Voice Call's realtime transcription path; Discord voice currently records short segments and uses the batch `tools.media.audio` transcription path instead.
-    </Note>
-
-  </Accordion>
-
-  <Accordion title="Realtime voice">
-    The bundled `openai` plugin registers realtime voice for the Voice Call plugin.
-
-    | Setting | Config path | Default |
-    |---------|------------|---------|
-    | Model | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-2` |
-    | Voice | `...openai.voice` | `alloy` |
-    | Temperature (Azure deployment bridge) | `...openai.temperature` | `0.8` |
-    | VAD threshold | `...openai.vadThreshold` | `0.5` |
-    | Silence duration | `...openai.silenceDurationMs` | `500` |
-    | Prefix padding | `...openai.prefixPaddingMs` | `300` |
-    | Reasoning effort | `...openai.reasoningEffort` | (unset) |
-    | Auth | `...openai.apiKey`, `OPENAI_API_KEY`, or `openai` OAuth | Browser Talk and non-Azure backend bridges can use OpenAI OAuth |
-
-    Available built-in Realtime voices for `gpt-realtime-2`: `alloy`, `ash`,
-    `ballad`, `coral`, `echo`, `sage`, `shimmer`, `verse`, `marin`, `cedar`.
-    OpenAI recommends `marin` and `cedar` for the best Realtime quality. This
-    is a separate set from the Text-to-speech voices above; do not assume a TTS
-    voice such as `fable`, `nova`, or `onyx` is valid for Realtime sessions.
-
-    <Note>
-    Backend OpenAI realtime bridges use the GA Realtime WebSocket session shape, which does not accept `session.temperature`. Azure OpenAI deployments remain available via `azureEndpoint` and `azureDeployment` and keep the deployment-compatible session shape. Supports bidirectional tool calling and G.711 u-law audio.
-    </Note>
-
-    <Note>
-    Realtime voice is selected when the session is created. OpenAI allows most
-    session fields to change later, but the voice cannot be changed after the
-    model has emitted audio in that session. FengMing currently exposes the
-    built-in Realtime voice ids as strings.
-    </Note>
-
-    <Note>
-    Control UI Talk uses OpenAI browser realtime sessions with a Gateway-minted
-    ephemeral client secret and a direct browser WebRTC SDP exchange against the
-    OpenAI Realtime API. When no direct OpenAI API key is configured, the
-    Gateway can mint that client secret with the selected `openai` OAuth
-    profile. Gateway relay and Voice Call backend realtime WebSocket bridges use
-    the same OAuth fallback for native OpenAI endpoints. Maintainer live
-    verification is available with
-    `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`;
-    the OpenAI legs verify both the backend WebSocket bridge and the browser
-    WebRTC SDP exchange without logging secrets.
-    </Note>
-
-  </Accordion>
-</AccordionGroup>
-
-## Azure OpenAI endpoints
-
-The bundled `openai` provider can target an Azure OpenAI resource for image
-generation by overriding the base URL. On the image-generation path, FengMing
-detects Azure hostnames on `models.providers.openai.baseUrl` and switches to
-Azure's request shape automatically.
-
-<Note>
-Realtime voice uses a separate configuration path
-(`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`)
-and is not affected by `models.providers.openai.baseUrl`. See the **Realtime
-voice** accordion under [Voice and speech](#voice-and-speech) for its Azure
-settings.
-</Note>
-
-Use Azure OpenAI when:
-
-- You already have an Azure OpenAI subscription, quota, or enterprise agreement
-- You need regional data residency or compliance controls Azure provides
-- You want to keep traffic inside an existing Azure tenancy
-
-### Configuration
-
-For Azure image generation through the bundled `openai` provider, point
-`models.providers.openai.baseUrl` at your Azure resource and set `apiKey` to
-the Azure OpenAI key (not an OpenAI Platform key):
-
-```json5
-{
-  models: {
-    providers: {
-      openai: {
-        baseUrl: "https://<your-resource>.openai.azure.com",
-        apiKey: "<azure-openai-api-key>",
-      },
-    },
-  },
-}
-```
-
-FengMing recognizes these Azure host suffixes for the Azure image-generation
-route:
-
-- `*.openai.azure.com`
-- `*.services.ai.azure.com`
-- `*.cognitiveservices.azure.com`
-
-For image-generation requests on a recognized Azure host, FengMing:
-
-- Sends the `api-key` header instead of `Authorization: Bearer`
-- Uses deployment-scoped paths (`/openai/deployments/{deployment}/...`)
-- Appends `?api-version=...` to each request
-- Uses a 600s default request timeout for Azure image-generation calls.
-  Per-call `timeoutMs` values still override this default.
-
-Other base URLs (public OpenAI, OpenAI-compatible proxies) keep the standard
-OpenAI image request shape.
-
-<Note>
-Azure routing for the `openai` provider's image-generation path requires
-FengMing 2026.4.22 or later. Earlier versions treat any custom
-`openai.baseUrl` like the public OpenAI endpoint and will fail against Azure
-image deployments.
-</Note>
-
-### API version
-
-Set `AZURE_OPENAI_API_VERSION` to pin a specific Azure preview or GA version
-for the Azure image-generation path:
-
-```bash
-export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
-```
-
-The default is `2024-12-01-preview` when the variable is unset.
-
-### Model names are deployment names
-
-Azure OpenAI binds models to deployments. For Azure image-generation requests
-routed through the bundled `openai` provider, the `model` field in FengMing
-must be the **Azure deployment name** you configured in the Azure portal, not
-the public OpenAI model id.
-
-If you create a deployment called `gpt-image-2-prod` that serves `gpt-image-2`:
-
-```
-/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
-```
-
-The same deployment-name rule applies to image-generation calls routed through
-the bundled `openai` provider.
-
-### Regional availability
-
-Azure image generation is currently available only in a subset of regions
-(for example `eastus2`, `swedencentral`, `polandcentral`, `westus3`,
-`uaenorth`). Check Microsoft's current region list before creating a
-deployment, and confirm the specific model is offered in your region.
-
-### Parameter differences
-
-Azure OpenAI and public OpenAI do not always accept the same image parameters.
-Azure may reject options that public OpenAI allows (for example certain
-`background` values on `gpt-image-2`) or expose them only on specific model
-versions. These differences come from Azure and the underlying model, not
-FengMing. If an Azure request fails with a validation error, check the
-parameter set supported by your specific deployment and API version in the
-Azure portal.
-
-<Note>
-Azure OpenAI uses native transport and compat behavior but does not receive
-FengMing's hidden attribution headers — see the **Native vs OpenAI-compatible
-routes** accordion under [Advanced configuration](#advanced-configuration).
-
-For chat or Responses traffic on Azure (beyond image generation), use the
-onboarding flow or a dedicated Azure provider config — `openai.baseUrl` alone
-does not pick up the Azure API/auth shape. A separate
-`azure-openai-responses/*` provider exists; see
-the Server-side compaction accordion below.
-</Note>
-
-## Advanced configuration
-
-<AccordionGroup>
-  <Accordion title="Transport (WebSocket vs SSE)">
-    FengMing uses WebSocket-first with SSE fallback (`"auto"`) for `openai/*`.
-
-    In `"auto"` mode, FengMing:
-    - Retries one early WebSocket failure before falling back to SSE
-    - After a failure, marks WebSocket as degraded for ~60 seconds and uses SSE during cool-down
-    - Attaches stable session and turn identity headers for retries and reconnects
-    - Normalizes usage counters (`input_tokens` / `prompt_tokens`) across transport variants
-
-    | Value | Behavior |
-    |-------|----------|
-    | `"auto"` (default) | WebSocket first, SSE fallback |
-    | `"sse"` | Force SSE only |
-    | `"websocket"` | Force WebSocket only |
-
-    ```json5
-    {
-      agents: {
-        defaults: {
-          models: {
-            "openai/gpt-5.5": {
-              params: { transport: "auto" },
-            },
-          },
-        },
-      },
-    }
-    ```
-
-    Related OpenAI docs:
-    - [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
-    - [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
-
-  </Accordion>
-
-  <Accordion title="Fast mode">
-    FengMing exposes a shared fast-mode toggle for `openai/*`:
-
-    - **Chat/UI:** `/fast status|on|off`
-    - **Config:** `agents.defaults.models["<provider>/<model>"].params.fastMode`
-
-    When enabled, FengMing maps fast mode to OpenAI priority processing (`service_tier = "priority"`). Existing `service_tier` values are preserved, and fast mode does not rewrite `reasoning` or `text.verbosity`.
-
-    ```json5
-    {
-      agents: {
-        defaults: {
-          models: {
-            "openai/gpt-5.5": { params: { fastMode: true } },
-          },
-        },
-      },
-    }
-    ```
-
-    <Note>
-    Session overrides win over config. Clearing the session override in the Sessions UI returns the session to the configured default.
-    </Note>
-
-  </Accordion>
-
-  <Accordion title="Priority processing (service_tier)">
-    OpenAI's API exposes priority processing via `service_tier`. Set it per model in FengMing:
-
-    ```json5
-    {
-      agents: {
-        defaults: {
-          models: {
-            "openai/gpt-5.5": { params: { serviceTier: "priority" } },
-          },
-        },
-      },
-    }
-    ```
-
-    Supported values: `auto`, `default`, `flex`, `priority`.
-
-    <Warning>
-    `serviceTier` is only forwarded to native OpenAI endpoints (`api.openai.com`) and native Codex endpoints (`chatgpt.com/backend-api`). If you route either provider through a proxy, FengMing leaves `service_tier` untouched.
-    </Warning>
-
-  </Accordion>
-
-  <Accordion title="Server-side compaction (Responses API)">
-    For direct OpenAI Responses models (`openai/*` on `api.openai.com`), the OpenAI plugin's FengMing stream wrapper auto-enables server-side compaction:
-
-    - Forces `store: true` (unless model compat sets `supportsStore: false`)
-    - Injects `context_management: [{ type: "compaction", compact_threshold: ... }]`
-    - Default `compact_threshold`: 70% of `contextWindow` (or `80000` when unavailable)
-
-    This applies to the built-in FengMing runtime path and to OpenAI provider hooks used by embedded runs. The native Codex app-server harness manages its own context through Codex and is configured by OpenAI's default agent route or provider/model runtime policy.
-
-    <Tabs>
-      <Tab title="Enable explicitly">
-        Useful for compatible endpoints like Azure OpenAI Responses:
-
-        ```json5
-        {
-          agents: {
-            defaults: {
-              models: {
-                "azure-openai-responses/gpt-5.5": {
-                  params: { responsesServerCompaction: true },
-                },
-              },
-            },
-          },
-        }
-        ```
-      </Tab>
-      <Tab title="Custom threshold">
-        ```json5
-        {
-          agents: {
-            defaults: {
-              models: {
-                "openai/gpt-5.5": {
-                  params: {
-                    responsesServerCompaction: true,
-                    responsesCompactThreshold: 120000,
-                  },
-                },
-              },
-            },
-          },
-        }
-        ```
-      </Tab>
-      <Tab title="Disable">
-        ```json5
-        {
-          agents: {
-            defaults: {
-              models: {
-                "openai/gpt-5.5": {
-                  params: { responsesServerCompaction: false },
-                },
-              },
-            },
-          },
-        }
-        ```
-      </Tab>
-    </Tabs>
-
-    <Note>
-    `responsesServerCompaction` only controls `context_management` injection. Direct OpenAI Responses models still force `store: true` unless compat sets `supportsStore: false`.
-    </Note>
-
-  </Accordion>
-
-  <Accordion title="Strict-agentic GPT mode">
-    For GPT-5-family runs on `openai/*`, FengMing can use a stricter embedded execution contract:
-
-    ```json5
-    {
-      agents: {
-        defaults: {
-          embeddedAgent: { executionContract: "strict-agentic" },
-        },
-      },
-    }
-    ```
-
-    With `strict-agentic`, FengMing:
-    - No longer treats a plan-only turn as successful progress when a tool action is available
-    - Retries the turn with an act-now steer
-    - Auto-enables `update_plan` for substantial work
-    - Surfaces an explicit blocked state if the model keeps planning without acting
-
-    <Note>
-    Scoped to OpenAI and Codex GPT-5-family runs only. Other providers and older model families keep default behavior.
-    </Note>
-
-  </Accordion>
-
-  <Accordion title="Native vs OpenAI-compatible routes">
-    FengMing treats direct OpenAI, Codex, and Azure OpenAI endpoints differently from generic OpenAI-compatible `/v1` proxies:
-
-    **Native routes** (`openai/*`, Azure OpenAI):
-    - Keep `reasoning: { effort: "none" }` only for models that support the OpenAI `none` effort
-    - Omit disabled reasoning for models or proxies that reject `reasoning.effort: "none"`
-    - Default tool schemas to strict mode
-    - Attach hidden attribution headers on verified native hosts only
-    - Keep OpenAI-only request shaping (`service_tier`, `store`, reasoning-compat, prompt-cache hints)
-
-    **Proxy/compatible routes:**
-    - Use looser compat behavior
-    - Strip Completions `store` from non-native `openai-completions` payloads
-    - Accept advanced `params.extra_body`/`params.extraBody` pass-through JSON for OpenAI-compatible Completions proxies
-    - Accept `params.chat_template_kwargs` for OpenAI-compatible Completions proxies such as vLLM
-    - Do not force strict tool schemas or native-only headers
-
-    Azure OpenAI uses native transport and compat behavior but does not receive the hidden attribution headers.
-
-  </Accordion>
-</AccordionGroup>
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
-    Choosing providers, model refs, and failover behavior.
-  </Card>
-  <Card title="Image generation" href="/tools/image-generation" icon="image">
-    Shared image tool parameters and provider selection.
-  </Card>
-  <Card title="Video generation" href="/tools/video-generation" icon="video">
-    Shared video tool parameters and provider selection.
-  </Card>
-  <Card title="OAuth and auth" href="/gateway/authentication" icon="key">
-    Auth details and credential reuse rules.
-  </Card>
-</CardGroup>