vilvona 1.0.0

package/docs/cli/migrate.md

@@ -0,0 +1,334 @@
+---
+summary: "CLI reference for `openclaw migrate` (import state from another agent system)"
+read_when:
+  - You want to migrate from Hermes or another agent system into OpenClaw
+  - You are adding a plugin-owned migration provider
+title: "Migrate"
+---
+
+# `openclaw migrate`
+
+Import state from another agent system through a plugin-owned migration provider. Bundled providers cover Codex CLI state, [Claude](/install/migrating-claude), and [Hermes](/install/migrating-hermes); third-party plugins can register additional providers.
+
+<Tip>
+For user-facing walkthroughs, see [Migrating from Claude](/install/migrating-claude) and [Migrating from Hermes](/install/migrating-hermes). The [migration hub](/install/migrating) lists all paths.
+</Tip>
+
+## Commands
+
+```bash
+openclaw migrate list
+openclaw migrate claude --dry-run
+openclaw migrate codex --dry-run
+openclaw migrate codex --skill gog-vault77-google-workspace
+openclaw migrate codex --plugin google-calendar --dry-run
+openclaw migrate codex --plugin google-calendar --verify-plugin-apps --dry-run
+openclaw migrate hermes --dry-run
+openclaw migrate hermes
+openclaw migrate apply codex --yes --skill gog-vault77-google-workspace
+openclaw migrate apply codex --yes --plugin google-calendar
+openclaw migrate apply codex --yes
+openclaw migrate apply claude --yes
+openclaw migrate apply hermes --yes
+openclaw migrate apply hermes --include-secrets --yes
+openclaw onboard --flow import
+openclaw onboard --import-from claude --import-source ~/.claude
+openclaw onboard --import-from hermes --import-source ~/.hermes
+```
+
+<ParamField path="<provider>" type="string">
+  Name of a registered migration provider, for example `hermes`. Run `openclaw migrate list` to see installed providers.
+</ParamField>
+<ParamField path="--dry-run" type="boolean">
+  Build the plan and exit without changing state.
+</ParamField>
+<ParamField path="--from <path>" type="string">
+  Override the source state directory. Hermes defaults to `~/.hermes`.
+</ParamField>
+<ParamField path="--include-secrets" type="boolean">
+  Import supported credentials without prompting. Interactive apply asks before importing detected auth credentials, with yes selected by default; non-interactive `--yes` requires `--include-secrets` to import them.
+</ParamField>
+<ParamField path="--no-auth-credentials" type="boolean">
+  Skip auth credential import, including the interactive prompt.
+</ParamField>
+<ParamField path="--overwrite" type="boolean">
+  Allow apply to replace existing targets when the plan reports conflicts.
+</ParamField>
+<ParamField path="--yes" type="boolean">
+  Skip the confirmation prompt. Required in non-interactive mode.
+</ParamField>
+<ParamField path="--skill <name>" type="string">
+  Select one skill copy item by skill name or item id. Repeat the flag to migrate multiple skills. When omitted, interactive Codex migrations show a checkbox selector and non-interactive migrations keep all planned skills.
+</ParamField>
+<ParamField path="--plugin <name>" type="string">
+  Select one Codex plugin install item by plugin name or item id. Repeat the flag to migrate multiple Codex plugins. When omitted, interactive Codex migrations show a native Codex plugin checkbox selector and non-interactive migrations keep all planned plugins. This only applies to source-installed `openai-curated` Codex plugins discovered by the Codex app-server inventory.
+</ParamField>
+<ParamField path="--verify-plugin-apps" type="boolean">
+  Codex only. Force a fresh source Codex app-server `app/list` traversal before planning native plugin activation. Off by default to keep migration planning fast.
+</ParamField>
+<ParamField path="--no-backup" type="boolean">
+  Skip the pre-apply backup. Requires `--force` when local OpenClaw state exists.
+</ParamField>
+<ParamField path="--force" type="boolean">
+  Required alongside `--no-backup` when apply would otherwise refuse to skip backup.
+</ParamField>
+<ParamField path="--json" type="boolean">
+  Print the plan or apply result as JSON. With `--json` and no `--yes`, apply prints the plan and does not mutate state.
+</ParamField>
+
+## Safety model
+
+`openclaw migrate` is preview-first.
+
+<AccordionGroup>
+  <Accordion title="Preview before apply">
+    The provider returns an itemized plan before anything changes, including conflicts, skipped items, and sensitive items. JSON plans, apply output, and migration reports redact nested secret-looking keys such as API keys, tokens, authorization headers, cookies, and passwords.
+
+    `openclaw migrate apply <provider>` previews the plan and prompts before changing state unless `--yes` is set. In non-interactive mode, apply requires `--yes`.
+
+  </Accordion>
+  <Accordion title="Backups">
+    Apply creates and verifies an OpenClaw backup before applying the migration. If no local OpenClaw state exists yet, the backup step is skipped and the migration can continue. To skip a backup when state exists, pass both `--no-backup` and `--force`.
+  </Accordion>
+  <Accordion title="Conflicts">
+    Apply refuses to continue when the plan has conflicts. Review the plan, then rerun with `--overwrite` if replacing existing targets is intentional. Providers may still write item-level backups for overwritten files in the migration report directory.
+  </Accordion>
+  <Accordion title="Secrets">
+    Interactive apply asks whether to import detected auth credentials, with yes selected by default. Use `--no-auth-credentials` to skip them, or use `--include-secrets` for unattended credential import with `--yes`.
+  </Accordion>
+</AccordionGroup>
+
+## Claude provider
+
+The bundled Claude provider detects Claude Code state at `~/.claude` by default. Use `--from <path>` to import a specific Claude Code home or project root.
+
+<Tip>
+For a user-facing walkthrough, see [Migrating from Claude](/install/migrating-claude).
+</Tip>
+
+### What Claude imports
+
+- Project `CLAUDE.md` and `.claude/CLAUDE.md` into the OpenClaw agent workspace.
+- User `~/.claude/CLAUDE.md` appended to workspace `USER.md`.
+- MCP server definitions from project `.mcp.json`, Claude Code `~/.claude.json`, and Claude Desktop `claude_desktop_config.json`.
+- Claude skill directories that include `SKILL.md`.
+- Claude command Markdown files converted into OpenClaw skills with manual invocation only.
+
+### Archive and manual-review state
+
+Claude hooks, permissions, environment defaults, local memory, path-scoped rules, subagents, caches, plans, and project history are preserved in the migration report or reported as manual-review items. OpenClaw does not execute hooks, copy broad allowlists, or import OAuth/Desktop credential state automatically.
+
+## Codex provider
+
+The bundled Codex provider detects Codex CLI state at `~/.codex` by default, or
+at `CODEX_HOME` when that environment variable is set. Use `--from <path>` to
+inventory a specific Codex home.
+
+Use this provider when moving to the OpenClaw Codex harness and you want to
+promote useful personal Codex CLI assets deliberately. Local Codex app-server
+launches use a per-agent `CODEX_HOME`, so they do not read your personal
+`~/.codex` by default. The normal process `HOME` is still inherited, so Codex
+can see shared `$HOME/.agents/*` skills/plugin marketplace entries and
+subprocesses can find user-home config and tokens.
+
+Running `openclaw migrate codex` in an interactive terminal previews the full
+plan, then opens checkbox selectors before the final apply confirmation. Skill
+copy items are prompted first. Use `Toggle all on` or `Toggle all off` for bulk
+selection. Press Space to toggle rows, or press Enter to activate the highlighted
+row and continue. Planned skills start checked, conflict skills start unchecked, and
+`Skip for now` skips skill copies for this run while still continuing to plugin
+selection. When source-installed curated Codex plugins are migratable and
+`--plugin` was not supplied, migration then prompts for native Codex plugin
+activation by plugin name. Plugin items
+start checked unless the target OpenClaw Codex plugin config already has that
+plugin. Existing target plugins start unchecked and show a conflict hint such as
+`conflict: plugin exists`; choose `Toggle all off` to migrate no native Codex
+plugins in that run, or `Skip for now` to stop before applying. For scripted or
+exact runs, pass `--skill <name>` once per skill, for example:
+
+```bash
+openclaw migrate codex --dry-run --skill gog-vault77-google-workspace
+openclaw migrate apply codex --yes --skill gog-vault77-google-workspace
+```
+
+Use `--plugin <name>` to limit native Codex plugin migration non-interactively
+to one or more source-installed curated plugins:
+
+```bash
+openclaw migrate codex --dry-run --plugin google-calendar
+openclaw migrate apply codex --yes --plugin google-calendar
+```
+
+### What Codex imports
+
+- Codex CLI skill directories under `$CODEX_HOME/skills`, excluding Codex's
+  `.system` cache.
+- Personal AgentSkills under `$HOME/.agents/skills`, copied into the current
+  OpenClaw agent workspace when you want per-agent ownership.
+- Source-installed `openai-curated` Codex plugins discovered through Codex
+  app-server `plugin/list`. Planning reads `plugin/read` for each enabled
+  installed plugin. App-backed plugins require the source Codex app-server
+  account response to be a ChatGPT subscription account; non-ChatGPT or missing
+  account responses are skipped with `codex_subscription_required`. By default,
+  migration does not call source `app/list`, so app-backed plugins that pass the
+  account gate are planned without source app accessibility verification, and
+  account lookup transport failures skip with `codex_account_unavailable`. Pass
+  `--verify-plugin-apps` when you want migration to force a fresh source
+  `app/list` snapshot and require every owned app to be present, enabled, and
+  accessible before planning native activation. In that mode, account lookup
+  transport failures fall through to source app inventory verification. The
+  source app inventory snapshot is kept in memory for the current process; it
+  is not written to migration output or target config. Disabled plugins,
+  unreadable plugin details, subscription-gated source accounts, and, when
+  verification is requested, missing apps, disabled apps, inaccessible apps, or
+  source app inventory failures become manual skipped items with typed reasons
+  instead of target config entries.
+  Apply calls app-server `plugin/install` for each selected eligible plugin,
+  even if the target app-server already reports that plugin as installed and
+  enabled. Migrated Codex plugins are usable only in sessions that select the
+  native Codex harness; they are not exposed to OpenClaw provider runs,
+  ACP conversation bindings, or other harnesses.
+
+### Manual-review Codex state
+
+Codex `config.toml`, native `hooks/hooks.json`, non-curated marketplaces, cached
+plugin bundles that are not source-installed curated plugins, and source-installed
+plugins that fail the source subscription gate are not activated automatically.
+When `--verify-plugin-apps` is set, plugins that fail the source app-inventory
+gate are also skipped. They are copied or reported in the migration report for
+manual review.
+
+For migrated source-installed curated plugins, apply writes:
+
+- `plugins.entries.codex.enabled: true`
+- `plugins.entries.codex.config.codexPlugins.enabled: true`
+- `plugins.entries.codex.config.codexPlugins.allow_destructive_actions: true`
+- one explicit plugin entry with `marketplaceName: "openai-curated"` and
+  `pluginName` for each selected plugin
+
+Migration never writes `plugins["*"]` and never stores local marketplace cache
+paths. Source-side subscription failures are reported on manual items with typed
+reasons such as `codex_subscription_required`, `codex_account_unavailable`,
+`plugin_disabled`, or `plugin_read_unavailable`. With `--verify-plugin-apps`,
+source app-inventory failures can also appear as `app_inaccessible`,
+`app_disabled`, `app_missing`, or `app_inventory_unavailable`. Skipped plugins
+are not written to target config.
+Target-side auth-required installs are reported on the affected plugin item with
+`status: "skipped"`, `reason: "auth_required"`, and sanitized app identifiers.
+Their explicit config entries are written disabled until you reauthorize and
+enable them. Other install failures are item-scoped `error` results.
+
+If Codex app-server plugin inventory is unavailable during planning, migration
+falls back to cached bundle advisory items instead of failing the whole
+migration.
+
+## Hermes provider
+
+The bundled Hermes provider detects state at `~/.hermes` by default. Use `--from <path>` when Hermes lives elsewhere.
+
+### What Hermes imports
+
+- Default model configuration from `config.yaml`.
+- Configured model providers and custom OpenAI-compatible endpoints from `providers` and `custom_providers`.
+- MCP server definitions from `mcp_servers` or `mcp.servers`.
+- `SOUL.md` and `AGENTS.md` into the OpenClaw agent workspace.
+- `memories/MEMORY.md` and `memories/USER.md` appended to workspace memory files.
+- Memory config defaults for OpenClaw file memory, plus archive or manual-review items for external memory providers such as Honcho.
+- Skills that include a `SKILL.md` file under `skills/<name>/`.
+- Per-skill config values from `skills.config`.
+- OpenCode OpenAI OAuth credentials from OpenCode `auth.json` when interactive credential migration is accepted, or when `--include-secrets` is set. Hermes `auth.json` OAuth entries are legacy state reported for manual OpenAI reauth or doctor repair.
+- Supported API keys and tokens from Hermes `.env` and OpenCode `auth.json` when interactive credential migration is accepted, or when `--include-secrets` is set.
+
+### Supported `.env` keys
+
+- `AI_GATEWAY_API_KEY`
+- `ALIBABA_API_KEY`
+- `ANTHROPIC_API_KEY`
+- `ARCEEAI_API_KEY`
+- `CEREBRAS_API_KEY`
+- `CHUTES_API_KEY`
+- `CLOUDFLARE_AI_GATEWAY_API_KEY`
+- `COPILOT_GITHUB_TOKEN`
+- `DASHSCOPE_API_KEY`
+- `DEEPINFRA_API_KEY`
+- `DEEPSEEK_API_KEY`
+- `FIREWORKS_API_KEY`
+- `GEMINI_API_KEY`
+- `GH_TOKEN`
+- `GITHUB_TOKEN`
+- `GLM_API_KEY`
+- `GOOGLE_API_KEY`
+- `GROQ_API_KEY`
+- `HF_TOKEN`
+- `HUGGINGFACE_HUB_TOKEN`
+- `KILOCODE_API_KEY`
+- `KIMICODE_API_KEY`
+- `KIMI_API_KEY`
+- `MINIMAX_API_KEY`
+- `MINIMAX_CODING_API_KEY`
+- `MISTRAL_API_KEY`
+- `MODELSTUDIO_API_KEY`
+- `MOONSHOT_API_KEY`
+- `NVIDIA_API_KEY`
+- `OPENAI_API_KEY`
+- `OPENCODE_API_KEY`
+- `OPENCODE_GO_API_KEY`
+- `OPENCODE_ZEN_API_KEY`
+- `OPENROUTER_API_KEY`
+- `QIANFAN_API_KEY`
+- `QWEN_API_KEY`
+- `TOGETHER_API_KEY`
+- `VENICE_API_KEY`
+- `XAI_API_KEY`
+- `XIAOMI_API_KEY`
+- `ZAI_API_KEY`
+- `Z_AI_API_KEY`
+
+### Archive-only state
+
+Hermes state that OpenClaw cannot safely interpret is copied into the migration report for manual review, but it is not loaded into live OpenClaw config or credentials. This preserves opaque or unsafe state without pretending OpenClaw can execute or trust it automatically:
+
+- `plugins/`
+- `sessions/`
+- `logs/`
+- `cron/`
+- `mcp-tokens/`
+- `state.db`
+
+### After applying
+
+```bash
+openclaw doctor
+```
+
+## Plugin contract
+
+Migration sources are plugins. A plugin declares its provider ids in `openclaw.plugin.json`:
+
+```json
+{
+  "contracts": {
+    "migrationProviders": ["hermes"]
+  }
+}
+```
+
+At runtime the plugin calls `api.registerMigrationProvider(...)`. The provider implements `detect`, `plan`, and `apply`. Core owns CLI orchestration, backup policy, prompts, JSON output, and conflict preflight. Core passes the reviewed plan into `apply(ctx, plan)`, and providers may rebuild the plan only when that argument is absent for compatibility.
+
+Provider plugins can use `openclaw/plugin-sdk/migration` for item construction and summary counts, plus `openclaw/plugin-sdk/migration-runtime` for conflict-aware file copies, archive-only report copies, cached config-runtime wrappers, and migration reports.
+
+## Onboarding integration
+
+Onboarding can offer migration when a provider detects a known source. Both `openclaw onboard --flow import` and `openclaw setup --wizard --import-from hermes` use the same plugin migration provider and still show a preview before applying.
+
+<Note>
+Onboarding imports require a fresh OpenClaw setup. Reset config, credentials, sessions, and the workspace first if you already have local state. Backup-plus-overwrite or merge imports are feature-gated for existing setups.
+</Note>
+
+## Related
+
+- [Migrating from Hermes](/install/migrating-hermes): user-facing walkthrough.
+- [Migrating from Claude](/install/migrating-claude): user-facing walkthrough.
+- [Migrating](/install/migrating): move OpenClaw to a new machine.
+- [Doctor](/gateway/doctor): health check after applying a migration.
+- [Plugins](/tools/plugin): plugin install and registration.

package/docs/cli/models.md

@@ -0,0 +1,239 @@
+---
+summary: "CLI reference for `openclaw models` (status/list/set/scan, aliases, fallbacks, auth)"
+read_when:
+  - You want to change default models or view provider auth status
+  - You want to scan available models/providers and debug auth profiles
+title: "Models"
+---
+
+# `openclaw models`
+
+Model discovery, scanning, and configuration (default model, fallbacks, auth profiles).
+
+Related:
+
+- Providers + models: [Models](/providers/models)
+- Model selection concepts + `/models` slash command: [Models concept](/concepts/models)
+- Provider auth setup: [Getting started](/start/getting-started)
+
+## Common commands
+
+```bash
+openclaw models status
+openclaw models list
+openclaw models set <model-or-alias>
+openclaw models scan
+```
+
+`openclaw models status` shows the resolved default/fallbacks plus an auth overview.
+When provider usage snapshots are available, the OAuth/API-key status section includes
+provider usage windows and quota snapshots.
+Current usage-window providers: Anthropic, GitHub Copilot, Gemini CLI, OpenAI,
+MiniMax, Xiaomi, and z.ai. Usage auth comes from provider-specific hooks
+when available; otherwise OpenClaw falls back to matching OAuth/API-key
+credentials from auth profiles, env, or config.
+In `--json` output, `auth.providers` is the env/config/store-aware provider
+overview, while `auth.oauth` is auth-store profile health only.
+Add `--probe` to run live auth probes against each configured provider profile.
+Probes are real requests (may consume tokens and trigger rate limits).
+Use `--agent <id>` to inspect a configured agent's model/auth state. When omitted,
+the command uses `OPENCLAW_AGENT_DIR` if set, otherwise the
+configured default agent.
+Probe rows can come from auth profiles, env credentials, or `models.json`.
+For OpenAI ChatGPT/Codex OAuth troubleshooting, `openclaw models status`,
+`openclaw models auth list --provider openai`, and
+`openclaw config get agents.defaults.model --json` are the quickest way to
+confirm whether an agent has a usable `openai` OAuth profile for
+`openai/*` through the native Codex runtime. See [OpenAI provider setup](/providers/openai#check-and-recover-codex-oauth-routing).
+
+Notes:
+
+- `models set <model-or-alias>` accepts `provider/model` or an alias.
+- `models list` is read-only: it reads config, auth profiles, existing catalog
+  state, and provider-owned catalog rows, but it does not rewrite
+  `models.json`.
+- The `Auth` column is provider-level and read-only. It is computed from local
+  auth profile metadata, env markers, configured provider keys, local-provider
+  markers, AWS Bedrock env/profile markers, and plugin synthetic-auth metadata;
+  it does not load provider runtime, read keychain secrets, call provider
+  APIs, or prove exact per-model execution readiness.
+- `models list --all --provider <id>` can include provider-owned static catalog
+  rows from plugin manifests or bundled provider catalog metadata even when you
+  have not authenticated with that provider yet. Those rows still show as
+  unavailable until matching auth is configured.
+- `models list` keeps the control plane responsive while provider catalog
+  discovery is slow. The default and configured views fall back to configured or
+  synthetic model rows after a short wait and let discovery finish in the
+  background. Use `--all` when you need the exact full discovered catalog and
+  are willing to wait for provider discovery.
+- Broad `models list --all` merges manifest catalog rows over registry rows
+  without loading provider runtime supplement hooks. Provider-filtered manifest
+  fast paths use only providers marked `static`; providers marked `refreshable`
+  stay registry/cache-backed and append manifest rows as supplements, while
+  providers marked `runtime` stay on registry/runtime discovery.
+- `models list` keeps native model metadata and runtime caps distinct. In table
+  output, `Ctx` shows `contextTokens/contextWindow` when an effective runtime
+  cap differs from the native context window; JSON rows include `contextTokens`
+  when a provider exposes that cap.
+- `models list --provider <id>` filters by provider id, such as `moonshot` or
+  `openai`. It does not accept display labels from interactive provider
+  pickers, such as `Moonshot AI`.
+- Model refs are parsed by splitting on the **first** `/`. If the model ID includes `/` (OpenRouter-style), include the provider prefix (example: `openrouter/moonshotai/kimi-k2`).
+- If you omit the provider, OpenClaw resolves the input as an alias first, then
+  as a unique configured-provider match for that exact model id, and only then
+  falls back to the configured default provider with a deprecation warning.
+  If that provider no longer exposes the configured default model, OpenClaw
+  falls back to the first configured provider/model instead of surfacing a
+  stale removed-provider default.
+- `models status` may show `marker(<value>)` in auth output for non-secret placeholders (for example `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) instead of masking them as secrets.
+
+### Models scan
+
+`models scan` reads OpenRouter's public `:free` catalog and ranks candidates for
+fallback use. The catalog itself is public, so metadata-only scans do not need
+an OpenRouter key.
+
+By default OpenClaw tries to probe tool and image support with live model calls.
+If no OpenRouter key is configured, the command falls back to metadata-only
+output and explains that `:free` models still require `OPENROUTER_API_KEY` for
+probes and inference.
+
+Options:
+
+- `--no-probe` (metadata only; no config/secrets lookup)
+- `--min-params <b>`
+- `--max-age-days <days>`
+- `--provider <name>`
+- `--max-candidates <n>`
+- `--timeout <ms>` (catalog request and per-probe timeout)
+- `--concurrency <n>`
+- `--yes`
+- `--no-input`
+- `--set-default`
+- `--set-image`
+- `--json`
+
+`--set-default` and `--set-image` require live probes; metadata-only scan
+results are informational and are not applied to config.
+
+### Models status
+
+Options:
+
+- `--json`
+- `--plain`
+- `--check` (exit 1=expired/missing, 2=expiring)
+- `--probe` (live probe of configured auth profiles)
+- `--probe-provider <name>` (probe one provider)
+- `--probe-profile <id>` (repeat or comma-separated profile ids)
+- `--probe-timeout <ms>`
+- `--probe-concurrency <n>`
+- `--probe-max-tokens <n>`
+- `--agent <id>` (configured agent id; overrides `OPENCLAW_AGENT_DIR`)
+
+`--json` keeps stdout reserved for the JSON payload. Auth-profile, provider,
+and startup diagnostics are routed to stderr so scripts can pipe stdout directly
+into tools such as `jq`.
+
+Probe status buckets:
+
+- `ok`
+- `auth`
+- `rate_limit`
+- `billing`
+- `timeout`
+- `format`
+- `unknown`
+- `no_model`
+
+Probe detail/reason-code cases to expect:
+
+- `excluded_by_auth_order`: a stored profile exists, but explicit
+  `auth.order.<provider>` omitted it, so probe reports the exclusion instead of
+  trying it.
+- `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`:
+  profile is present but not eligible/resolvable.
+- `no_model`: provider auth exists, but OpenClaw could not resolve a probeable
+  model candidate for that provider.
+
+## Aliases + fallbacks
+
+```bash
+openclaw models aliases list
+openclaw models fallbacks list
+```
+
+## Auth profiles
+
+```bash
+openclaw models auth add
+openclaw models auth list [--provider <id>] [--json]
+openclaw models auth login --provider <id>
+openclaw models auth login --provider openai --profile-id openai:work
+openclaw models auth paste-api-key --provider <id>
+openclaw models auth setup-token --provider <id>
+openclaw models auth paste-token
+```
+
+`models auth add` is the interactive auth helper. It can launch a provider auth
+flow (OAuth/API key) or guide you into manual token paste, depending on the
+provider you choose.
+
+`models auth list` lists saved auth profiles for the selected agent without
+printing token, API-key, or OAuth secret material. Use `--provider <id>` to
+filter to one provider, such as `openai`, and `--json` for scripting.
+
+`models auth login` runs a provider plugin's auth flow (OAuth/API key). Use
+`openclaw plugins list` to see which providers are installed.
+Use `openclaw models auth --agent <id> <subcommand>` to write auth results to a
+specific configured agent store. The parent `--agent` flag is honored by
+`add`, `list`, `login`, `paste-api-key`, `setup-token`, `paste-token`, and
+`login-github-copilot`.
+
+For OpenAI models, `--provider openai` defaults to ChatGPT/Codex account login.
+Use `--method api-key` only when you want to add an OpenAI API-key profile,
+usually as a backup for Codex subscription limits. Run `openclaw doctor --fix`
+to migrate older legacy OpenAI Codex prefix auth/profile state to `openai`.
+
+Examples:
+
+```bash
+openclaw models auth login --provider openai --set-default
+openclaw models auth login --provider openai --method api-key
+openclaw models auth paste-api-key --provider openai
+openclaw models auth list --provider openai
+```
+
+Notes:
+
+- `login` accepts `--profile-id <id>` for providers that support named
+  profiles during login. Use this to keep multiple logins for the same
+  provider separate.
+- `paste-api-key` accepts API keys generated elsewhere, prompts for the key
+  value, and writes it to the default profile id `<provider>:manual` unless you
+  pass `--profile-id`. In automation, pipe the key on stdin, for example
+  `printf "%s\n" "$OPENAI_API_KEY" | openclaw models auth paste-api-key --provider openai`.
+- `setup-token` and `paste-token` remain generic token commands for providers
+  that expose token auth methods.
+- `setup-token` requires an interactive TTY and runs the provider's token-auth
+  method (defaulting to that provider's `setup-token` method when it exposes
+  one).
+- `paste-token` accepts a token string generated elsewhere or from automation.
+- `paste-token` requires `--provider`, prompts for the token value by default,
+  and writes it to the default profile id `<provider>:manual` unless you pass
+  `--profile-id`.
+- In automation, pipe the token on stdin instead of passing it as an argument so
+  provider credentials do not appear in shell history or process lists.
+- `paste-token --expires-in <duration>` stores an absolute token expiry from a
+  relative duration such as `365d` or `12h`.
+- For `openai`, OpenAI API keys and ChatGPT/OAuth token material are
+  different auth shapes. Use `paste-api-key` for `sk-...` OpenAI API keys and
+  `paste-token` only for token auth material.
+- Anthropic note: Anthropic staff told us OpenClaw-style Claude CLI usage is allowed again, so OpenClaw treats Claude CLI reuse and `claude -p` usage as sanctioned for this integration unless Anthropic publishes a new policy.
+- Anthropic `setup-token` / `paste-token` remain available as a supported OpenClaw token path, but OpenClaw now prefers Claude CLI reuse and `claude -p` when available.
+
+## Related
+
+- [CLI reference](/cli)
+- [Model selection](/concepts/model-providers)
+- [Model failover](/concepts/model-failover)