AI Providers

OpenAlice does not run the main model loop inside its own backend. The model lives in the native workspace CLI — claude, codex, opencode, or pi — so each agent keeps its own login, config format, prompt cache, terminal behavior, and provider quirks.

What OpenAlice keeps is the configuration layer around that loop: a credential vault for API-key credentials, plus workspace injection that writes the right native config for the selected CLI. Subscription logins (Claude Pro/Max, ChatGPT) stay in the CLI's own login and never touch the vault.

Two different "providers" — don't conflate them. This page is about AI model providers (the keys that drive the agent CLI). The keys that power market data — FRED, FMP, EIA, … — are a separate thing entirely, and you mostly don't need them at all: the Data Hub serves that data keyless. When you do bring your own, they live in market-data.json / provider-keys.json, not the vault here.

Two ways a workspace gets a model

1. CLI subscription login (zero config) — Run claude (or codex) once to log in with your Pro/Max or ChatGPT subscription. Any workspace using that CLI inherits the login. No API key, nothing in OpenAlice's config.
2. Vault credential — Add an api-key credential in the Web UI's AI Provider page. At workspace-create time OpenAlice injects it into the chosen agent's native config file. The same page can now also set a per-agent workspace default credential — pick a vault cred per agent once and OpenAlice seeds it into every new workspace, so you don't open the per-workspace AI config on each launch. See Default workspace credentials.

Packaged desktop shortcut. The macOS and Windows desktop packages include a managed Pi runtime. A fresh packaged install can therefore use option 2 without separately installing an agent CLI: save a compatible key, set it as Pi's default Workspace credential, and create a Pi workspace. The package supplies the runtime; the vault supplies the model connection.

The credential vault

Credentials live in ~/.openalice/data/config/ai-provider-manager.json as a map of slug → credential:

{
  "credentials": {
    "glm-1": {
      "vendor": "glm",
      "authType": "api-key",
      "apiKey": "•••",
      "wires": {
        "anthropic":   "https://open.bigmodel.cn/api/anthropic",
        "openai-chat": "https://open.bigmodel.cn/api/paas/v4"
      }
    }
  }
}

A credential is deduplicated by { vendor, authType, apiKey }: re-adding the same key upgrades its wires in place rather than creating a duplicate. Save a key once, then add more shapes/regions to it later.

Wire shapes

A "wire shape" is the on-the-wire HTTP protocol an endpoint speaks — independent of the model. There are three:

openai-chat and openai-responses share a base URL but are not interchangeable on the wire — that's why they're distinct shapes. A single key can declare several shapes at once (wires is a map), so one GLM key, for example, covers both an Anthropic-compatible endpoint and an OpenAI-Chat-compatible one.

How a credential reaches a workspace

At workspace-create time OpenAlice picks the shape the target agent speaks, by preference:

It selects the first wire the credential actually declares that the agent can speak (pickAgentWire), then writes that CLI's native config file inside the workspace — Claude's settings for the anthropic wire, Codex's wire_api: responses for openai-responses, and so on. If a credential offers no shape the agent can speak (e.g. an OpenAI-Chat-only key for codex), injection is skipped loudly rather than writing a broken config.

See Settings Injection — AI provider config.

The preset catalog

The Web UI's credential form is driven by a preset catalog — suggestions only, not an execution layer. Each preset declares a vendor's model list and its regions × wire shapes, so the form can pre-fill endpoints and gate you to a valid region/key pair.

Region-aware endpoints. Chinese vendors with split deployments — MiniMax, GLM, Kimi — have separate China and International consoles with region-locked keys. The picker gates you to a valid pair so you can't paste a China key against an International endpoint.

Test before save. Adding a credential runs a one-shot probe against the chosen wire + endpoint + key — a single "Hi" round-trip — before it commits. The same probe backs the per-workspace AI-config Test button. This probe is the only in-process AI call left in OpenAlice; it validates a key, nothing more.

The AI Provider page

The Web UI surfaces the vault as a credential manager plus an Agent runtimes view and a Default workspace credentials section:

• Vault — list / add / test / delete credentials, each showing its vendor, wire shapes, and resolved endpoint.
• Agent runtimes — which credential is injected into each agent (claude / codex / opencode / pi), with a load-from-saved picker and a "save to Alice" button so a hand-entered workspace config becomes a reusable vault credential.
• Default workspace credentials — the per-agent credential auto-seeded into every new workspace, set once and forgotten. See below.

Default workspace credentials

Injecting a vault credential per workspace is fine for a one-off, but tedious when you spin up workspaces constantly. The Default workspace credentials section is the fix: it's the user-level counterpart to a template's per-agent agentCredentials. Pick a vault credential per agent once, and OpenAlice seeds it into every new workspace at create time — no more opening the per-workspace AI config on each launch.

Defaults are stored as workspaceCredentialDefaults (a map of agentId → { credentialSlug, model? }) in ai-provider-manager.json, alongside the vault itself. Setting a default only affects future workspaces — existing ones are untouched, and you can still override any workspace afterward from its own AI config.

The four defaultable agents

Only the four native agents can carry a default. The UI splits them into a primary case and an advanced reveal:

opencode and Pi are loginless — they need a key to run at all, so they're the primary case and the section's whole reason for existing. Claude Code and Codex normally run on their own CLI subscription login (claude login / codex login), so they sit behind an "Advanced — unofficial API" reveal; a default set there overwrites the CLI login in each new workspace, which is only what you want if you drive them through an unofficial API key.

Each agent's dropdown offers only the vault slugs that agent can actually speak (the wire-shape funnel computed server-side: claude → anthropic-only, codex → openai-responses-only, opencode/pi → any of the three), plus a "Don't seed" option to leave that agent on its login.

Seeding mechanics

The seed runs as part of workspace creation, after the workspace's initial git commit — so the secret never lands in the first commit (the adapter config files are git-excluded anyway; post-commit is belt-and-braces). It writes into the agent's native config inside the workspace:

Seeding is best-effort: a disabled agent, a dangling slug (credential since deleted), or an incompatible wire warns and skips — the workspace stays fully usable. The effective source merges your user defaults with the template's agentCredentials, with the template winning per agent (explicit per-template intent overrides the user-wide default).

Deleting a vault credential also prunes any workspace default that referenced it, so the dropdown never shows a dangling default.

Quick Chat runtime and provider

Ask Alice reuses the selected or recent Chat Workspace. Its runtime picker is a user-level default for future interactive Sessions, while the provider pill is a launch choice for the target Workspace.

For Pi and opencode, OpenAlice resolves the effective credential in this order:

1. the credential explicitly picked in the composer;
2. the credential already detected in the existing Workspace;
3. the configured per-agent Workspace default;
4. the last compatible choice;
5. the first compatible vault entry.

An existing Workspace's detected provider remains authoritative while its files are loading; OpenAlice does not briefly submit a global fallback and overwrite the desk's actual choice. Claude Code and Codex normally keep their CLI login unless an explicit compatible vault credential was configured.

API

The section is backed by two routes (optional — the UI calls them for you):

Per-channel overrides

The Web UI's lightweight chat sub-channels can carry their own system prompt and disabled-tools list in data/config/web-subchannels.json:

[
  {
    "id": "research",
    "label": "Research",
    "systemPrompt": "You are a research assistant...",
    "disabledTools": ["placeOrder"]
  }
]

For serious multi-model work, prefer a dedicated workspace per agent — that's where the model actually runs.

Next Steps

• Installation Overview — Choose the right run path for your machine.
• Workspaces — See where credentials are injected into native agent configs.
• Configuration Reference — Inspect the credential vault shape.
• Quick Start — Start a workspace-backed conversation after setup.