OpenClaw

OpenClaw reads its config from ~/.openclaw/openclaw.json, a JSON5 file. A custom provider names an API format and a base URL. This guide uses Chat Completions with https://deference.si/v1.

Set up

1. Create a key in API keys.
2. Add the key to ~/.openclaw/.env. The Gateway runs as a background service, so a variable exported in your shell may not reach it.

DEFERENCE_API_KEY=sk-df-...

3. Add the provider and the model to ~/.openclaw/openclaw.json.

{
  agents: {
    defaults: {
      model: { primary: "deference/anthropic/claude-sonnet-5.5" },
      models: {
        "deference/anthropic/claude-sonnet-5.5": { alias: "Sonnet" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      deference: {
        baseUrl: "https://deference.si/v1",
        apiKey: "${DEFERENCE_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "anthropic/claude-sonnet-5.5",
            name: "Claude Sonnet 5.5",
            reasoning: false,
            input: ["text", "image"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 64000,
          },
        ],
      },
    },
  },
}

Provider changes apply without a restart. If OpenClaw does not pick them up, run openclaw gateway restart.

Each model needs its own entry in models. An alias under agents.defaults.models does not register a model by itself. cost stays at zero because Activity tracks the real cost.

Verify

1. Run openclaw models list --provider deference. The model you declared is listed.
2. Run openclaw models status --probe. It makes a live call and reports ok, or a bucket such as auth, billing or timeout.
3. Send a message to the agent.
4. Open Activity. The request is the top row, with the model you chose.

Pick a model

• A model reference is provider/model-id. OpenClaw splits on the first slash, so deference/anthropic/claude-sonnet-5.5 is provider deference and model anthropic/claude-sonnet-5.5.
• Pin a model with openclaw models set deference/anthropic/claude-sonnet-5.5, or /model deference/anthropic/claude-sonnet-5.5 in chat.
• api is openai-completions (the default), openai-responses or anthropic-messages. For anthropic-messages, set baseUrl to https://deference.si: OpenClaw adds /v1. Implicit beta headers are off on a custom host, so set headers: { "anthropic-beta": "..." } if a model needs them.
• Raise timeoutSeconds on the provider for slow models.

Troubleshooting