Models

The built-in agent isn’t bound to one vendor — you choose which model drives it, and switching is one command.

A model is named by a provider/model ref: the part before the slash picks the provider (and which engine runs it); the part after is the model id, passed to that provider’s API verbatim. For example anthropic/claude-sonnet-4-6, openai/gpt-5.4, or qwen/qwen3.6-plus. That single ref — stored as [agent] model in ~/.physiclaw/config.toml, or the PHYSICLAW_MODEL env var — selects the whole stack.

Supported providers

PhysiClaw’s own in-process engine talks to five vendors over their chat APIs, and a sixth ref shells out to Anthropic’s claude CLI:

Provider id	Vendor / models	API key
anthropic	Claude, via the official Anthropic SDK	ANTHROPIC_API_KEY
openai	GPT / reasoning models (gpt-5, o4-mini)	OPENAI_API_KEY
google	Gemini, via Google’s OpenAI-compatible endpoint	GOOGLE_API_KEY
moonshot	Kimi (K2)	MOONSHOT_API_KEY
qwen	Qwen, via Alibaba DashScope	QWEN_API_KEY / DASHSCOPE_API_KEY
claude-code	the claude CLI as a subprocess (shares anthropic’s catalog + key)	ANTHROPIC_API_KEY

Every key can come from an environment variable (above) or from [provider] <id>_api_key in the config file; the env var wins if both are set.

Why no DeepSeek

deepseek appears in the provider list but is a deliberate stub — its chat endpoint is text-only, and PhysiClaw needs vision on every peek to read the screen. Selecting it fails loudly at startup rather than silently driving blind. A couple of Gemini variants are left out for a related reason: PhysiClaw requires a reasoning model, and any Gemini that defaults its thinking budget off is excluded until that’s wired.

Two engines, one ref

The provider id also decides how the model runs:

• claude-code/... runs Anthropic’s claude CLI as a subprocess. Its model ids and API key are Anthropic’s — the CLI talks to the same API — so claude-code reuses the anthropic catalog and key.
• Everything else runs inside PhysiClaw’s own in-process engine (the native tool-call loop), pointed at that vendor’s API.

You don’t manage engines directly; picking the ref picks the engine.

Set and switch the model

The physiclaw models command group is the front door. PhysiClaw ships no curated model list — it fetches each vendor’s live /v1/models and caches it, so discovery is the source of truth.

1. Set a provider’s API key. Omit the value to be prompted (keeps the secret out of shell history). Writing the key immediately fetches that vendor’s live model list, so you can pick one right away.

   bash

   physiclaw models key anthropic

2. List what’s available. Show the discovered models for one provider (or all of them, with no argument).

   bash

   physiclaw models list anthropic

3. Pick the active model with an exact provider/model ref. It’s validated against the discovery cache, so a typo fails fast.

   bash

   physiclaw models use anthropic/claude-sonnet-4-6

4. Restart the server to apply — the running agent reads [agent] model at startup.

   bash

   physiclaw server

The bare physiclaw models prints the current state — the active ref, where it came from (env var or config file), and whether that provider’s key is set:

Active model
✓ anthropic/claude-sonnet-4-6  (from config.toml [agent] model)
  anthropic/claude-sonnet-4-6
  anthropic api key: ********  [ANTHROPIC_API_KEY env]

The rest of the commands

Command	Does
physiclaw models	show the active ref, its source, and the active provider’s key status
physiclaw models list [provider]	list discovered models, per provider
physiclaw models use <provider/model>	switch the active model (alias: set)
physiclaw models key <provider> [value]	set a provider’s API key (prompts if value omitted)
physiclaw models keys	show every provider’s key status, masked, with source
physiclaw models discover <provider>	re-fetch a vendor’s live model list

New release landed?

models key discovers automatically, so you rarely call discover by hand. Reach for it when a vendor ships a new model and you want it to appear in models list before you can models use it.