Add Model Provider
Add and live-prove a model provider with non-interactive config one-liners, without exposing credentials.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Add Model Provider when an AI agent needs a reusable SKILL.md workflow for this job: Add and live-prove a model provider with non-interactive config one-liners, without exposing credentials.
When not to use it
Skip Add Model Provider when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/add-model-provider # Save SKILL.md to ~/.claude/skills/add-model-provider/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/add-model-provider/SKILL.md. For a shared project, commit the folder at .claude/skills/add-model-provider/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Add Model Provider skill for this task: Use Add Model Provider when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
68/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 70/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeinferred
The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- chatgptinferred
The skill text mentions ChatGPT or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Add a model provider
Never print or persist secret values; credentials enter config only as SecretRefs (env or file source). Never hand-edit config files on disk — every mutation goes through `openclaw config` so it is validated and audited. Every run ends with the observable Prove result or an exact explanation of why it could not be proven.
In-session `config_set`/`config_set_ref` tool actions are policy-blocked for `models.*` and `secrets.*`; use the trusted shell (`exec`) for the commands below. `set_default_model` is the one in-session action allowed to change the default route — it live-tests before saving.
## Gather
``` openclaw config get models --json # "Config path not found" is normal before first setup openclaw models list --agent <agentId> # --agent is required in multi-agent rosters openclaw models auth list --agent <agentId> openclaw config schema --json | jq '.properties.models' # confirm exact provider paths before writing openclaw plugins list # OpenAI routes need the codex harness plugin; enable/install NOW, not mid-proof ```
If the harness plugin for the target provider is missing or disabled, remediate here (`openclaw plugins enable codex` or `openclaw plugins install @openclaw/codex`) so the Prove step does not stall on it later; plugin enable is picked up by gateway hot-reload.
Decide the auth contract: API-key providers take a SecretRef on `models.providers.<id>.apiKey`; subscription/OAuth providers (ChatGPT/Codex, Claude subscriptions) use `openclaw models auth login --provider <id>` instead and must not be given an API key path.
## Mutate
API-key example (OpenAI), key staged by the operator in a `0600` file — validate first with `--dry-run`, then write:
``` openclaw config set secrets.providers.openai_key_file --provider-source file --provider-path /path/to/openai.key --provider-mode singleValue --dry-run openclaw config set secrets.providers.openai_key_file --provider-source file --provider-path /path/to/openai.key --provider-mode singleValue openclaw config set models.providers.openai.apiKey --ref-provider openai_key_file --ref-source file --ref-id value ```
Env-var alternative when the gateway process env carries the key:
``` openclaw config set models.providers.openai.apiKey --ref-provider default --ref-source env --ref-id OPENAI_API_KEY ```
To change a default model, use the in-session `set_default_model` action (with `agentId` for a non-default agent); it live-tests the route before saving. Do not change defaults with raw config writes.
## Repair
``` openclaw doctor --lint ```
`doctor --lint` can exit `1` for findings: read the report and continue the remaining checks. Ordinary `doctor` and `doctor --non-interactive` can write config/state; do not use them for diagnosis before approval. If a repair is needed, get explicit approval, run `openclaw doctor --fix --non-interactive`, then re-run the Gather reads.
## Prove
Roster-safe test (works in every setup; use your own agent id or any configured agent):
``` openclaw agent --agent <agentId> --model openai/gpt-5.4 -m "Reply with exactly: PROVIDER-PROOF-OK" ```
Single-agent installs can use the lighter completion test instead — it has no `--agent` flag and fails with "no explicit owner" on multi-agent rosters, so do not retry it there:
``` openclaw infer model run --gateway --model openai/gpt-5.4 --prompt "Reply with exactly: PROVIDER-PROOF-OK" ```
Expect the exact requested reply; record model id and wall time. Known dependency: OpenAI routes need the codex harness plugin at runtime — if the test reports the runtime unavailable, run `openclaw plugins install @openclaw/codex` and restart the gateway, then test again.
## Report
State the provider added, the SecretRef path written (never the value), the test result with model id and latency, and whether the default model changed. If the test failed, report the exact error and the next command to try.
Further reference: https://docs.openclaw.ai/providers/models and https://docs.openclaw.ai/providers/openai
Intended uses
- Use Add Model Provider when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.