OpenClaw

OpenClaw reaches any OpenAI-compatible endpoint through a custom provider. Onboarding writes the entry for you, and the config file holds it afterwards. OpenClaw has no per-request deadline field of its own, so the deadline goes on the key. Create one first (see agent keys).

Set this up with an agent

Open the block below and copy it into any coding agent. The prompt never asks for your API key: the agent configures everything else, then prints the one export line for you to run yourself.

Copy agent setup prompt

Configure OpenClaw to send its requests to FlexInference through a custom provider. Use the OpenClaw CLI, not hand-edited JSON, so every write is schema-validated.

You will never see or handle my API key. OpenClaw will read it from the `FLEXINFERENCE_API_KEY` environment variable through a secret reference, and I export that myself. Do not ask me for the key, do not pass it on any command line, and do not read it from my environment.

Ask whether to use my default OpenClaw profile or a separate one. A separate profile isolates config, state, gateway port, and workspace, and is the safe way to try this. Prefix every command with `--profile flex` if I choose one.

1. Confirm which config file is active with `openclaw config file`.

2. Tell me to export the key first, and stop until I confirm. Print this line; do not run it and do not ask for the value:

export FLEXINFERENCE_API_KEY=<paste your key here>

3. Write the provider entry. It carries no credential. The model row is required, because OpenClaw refuses a third-party provider that declares no `models`; step 5 replaces it with the full catalog:

openclaw config set models.providers.flexinference --merge --strict-json '{"baseUrl":"https://api.flexinference.com/v1","api":"openai-completions","models":[{"id":"gpt-5.6-sol","name":"GPT-5.6 Sol","compat":{"supportsUsageInStreaming":true}}]}'

4. Declare an environment secrets provider, then point the provider's apiKey at it. Both commands pass only the VARIABLE NAME, never the value:

openclaw config set secrets.providers.default \
  --provider-source env --provider-allowlist FLEXINFERENCE_API_KEY

openclaw config set models.providers.flexinference.apiKey \
  --ref-provider default --ref-source env --ref-id FLEXINFERENCE_API_KEY

5. Fill the model list from the live FlexInference catalog rather than by hand:

curl -s https://api.flexinference.com/v1/models \
  -H "Authorization: Bearer $FLEXINFERENCE_API_KEY" \
| jq '{models:{providers:{flexinference:{models:
    [.data[] | {id, name: .id, compat: {supportsUsageInStreaming: true}}]}}}}' \
| openclaw config patch --stdin

Run every write with `--dry-run` first and show me the diff before applying it.

6. Verify with `openclaw models list --provider flexinference`, then run `openclaw security audit`.

Rules that matter, do not deviate:
- Never pass my key as an argument to an `openclaw` command, and never write it into a config file. `openclaw onboard --custom-api-key` does both, which is why step 4 uses a reference instead.
- Step 5 is the one place the key expands, into curl's `-H` argument, where a same-user process can read it. That is a deliberate trade for a single catalog read. Do not extend it to any other command.
- The provider id must be `flexinference` in every command. If an earlier setup derived `custom-api-flexinference-com` from the host, tell me, and use that id consistently instead of creating a second provider.
- `api` must be `openai-completions`. That is the only adapter FlexInference's Chat Completions surface works with here.
- The base URL must end in `/v1`.
- You MUST list models explicitly. OpenClaw only lets its own built-in provider ids omit `models`, and it will never call `GET /v1/models` for a provider defined in config. Model discovery is a plugin capability and does not apply here.
- Every model row needs `compat: { supportsUsageInStreaming: true }`. OpenClaw makes streaming usage opt-in for third-party endpoints, and without it every streamed turn reports zero tokens and no cost.
- Leave `"mode": "merge"` alone so my existing providers survive.
- Step 4 resolves the reference at write time, so it fails if I have not exported the variable yet. That failure is expected, not a reason to fall back to a literal key.
- FlexInference's catalog publishes no context window or token ceiling, so generated rows carry neither. Do not invent values; leave them out unless I give you numbers.

Report what you changed and which config file you wrote.

Onboard a custom provider

Start the guided setup.
openclaw onboard
Pick the custom provider option when it asks about auth. That is custom-api-key.
Enter the router as the base URL, including the /v1 suffix.
https://api.flexinference.com/v1
Paste your agent key.
Leave the compatibility mode on openai. That is our Chat Completions surface.
Enter a model id we run, such as gpt-5.6-sol.

The prompt never puts your key on a command line, which is why it’s the path shown here. openclaw onboard --non-interactive exists too, but its custom-api-key auth mode reads the credential from --custom-api-key, so the secret ends up in your shell history and in process arguments. Script the setup with config commands and a secret reference instead, which is the same result without the exposure. Whichever route you take, set the provider id yourself:

openclaw config set models.providers.flexinference --merge --strict-json \
  '{"baseUrl":"https://api.flexinference.com/v1","api":"openai-completions","models":[{"id":"gpt-5.6-sol","name":"GPT-5.6 Sol","compat":{"supportsUsageInStreaming":true}}]}'

Left to itself, OpenClaw derives the id from the host and ends up with custom-api-flexinference-com, and every later command on this page would need that name instead. The write includes a model row because it has to. OpenClaw refuses a third-party provider that declares no models, so a baseUrl-only write fails schema validation. Replace the whole row in the next section. The compatibility mode maps to api. openai writes openai-completions, which is the one our Chat Completions endpoint works with. The other choices are openai-responses and anthropic.

The config file

Onboarding writes into ~/.openclaw/openclaw.json under models.providers. Print the path OpenClaw is using with openclaw config file.

{
  "models": {
    "mode": "merge",
    "providers": {
      "flexinference": {
        "baseUrl": "https://api.flexinference.com/v1",
        "api": "openai-completions",
        "apiKey": {
          "source": "env",
          "provider": "default",
          "id": "FLEXINFERENCE_API_KEY"
        },
        "models": [
          {
            "id": "gpt-5.6-sol",
            "name": "GPT-5.6 Sol",
            "contextWindow": 400000,
            "maxTokens": 128000,
            "input": ["text", "image"],
            "compat": { "supportsUsageInStreaming": true }
          }
        ]
      }
    }
  }
}

"mode": "merge" keeps your built-in providers and adds this one beside them. api must be openai-completions. The onboarding openai compatibility mode writes exactly that. apiKey takes a plain string too, which is what onboarding writes. The reference shown here keeps the secret out of the file. See keep the key out of the config file. List your models yourself. Only OpenClaw’s built-in provider ids may leave models out. A third-party id must declare both baseUrl and models, so add a row per model you want in the picker. Set compat.supportsUsageInStreaming. OpenClaw makes streaming usage opt-in for a third-party endpoint, because some servers refuse it. Without this flag we never get the request for a usage frame, so every streamed turn reports zero tokens and no cost.

Fill the model list from our catalog

OpenClaw won’t call GET /v1/models for a provider you define in config. Model discovery is a plugin capability, and the bundled plugins that have it are the only ones that use it. A config-defined provider reads its models array and nothing else. Generate that array from our catalog instead, and write it in one command.

export FLEXINFERENCE_API_KEY=<your agent key>

curl -s https://api.flexinference.com/v1/models \
  -H "Authorization: Bearer $FLEXINFERENCE_API_KEY" \
| jq '{models:{providers:{flexinference:{models:
    [.data[] | {id, name: .id, compat: {supportsUsageInStreaming: true}}]}}}}' \
| openclaw config patch --stdin

config patch merges objects and replaces arrays, so this swaps the model list and leaves baseUrl and apiKey untouched. Add --dry-run to see the write first. Keep only the models that race the cheaper tier by filtering on the catalog’s own flag.

jq '[.data[] | select(.flexinference.flex_race) | {id, name: .id}]'

Our catalog publishes no context window and no token ceiling, so rows made this way have neither. Add contextWindow and maxTokens yourself where OpenClaw’s defaults don’t fit the model. Re-run the command whenever our catalog changes. Check the result:

openclaw models list --provider flexinference

Global config and profiles

OpenClaw keeps one config per profile, not one per folder. The working directory never changes which file it reads.

Scope	Config path	How to select it
Default	`~/.openclaw/openclaw.json`	the default
Named	`~/.openclaw-<name>/`	`--profile <name>`
Dev	`~/.openclaw-dev/`	`--dev`
Explicit	any path	`OPENCLAW_CONFIG_PATH`

Use a named profile to try FlexInference without touching your usual setup.

openclaw --profile flex onboard

A profile isolates state as well as config, so its gateway port and workspace are separate too.

Keep the key out of the config file

Onboarding writes the key into openclaw.json in plain text. Set apiKey to a secret reference instead, and the config stores the variable’s name rather than its value.

Export the key in the shell you will run these commands from.
export FLEXINFERENCE_API_KEY=<your agent key>

Declare an environment secrets provider and allow that one variable.

openclaw config set secrets.providers.default \
  --provider-source env --provider-allowlist FLEXINFERENCE_API_KEY

Point the provider’s apiKey at it.

openclaw config set models.providers.flexinference.apiKey \
  --ref-provider default --ref-source env --ref-id FLEXINFERENCE_API_KEY

The config then holds {"source": "env", "provider": "default", "id": "FLEXINFERENCE_API_KEY"} and no secret. The key never reaches a command line either, because step 3 passes only the variable’s name. OpenClaw resolves the reference when you run step 3, so export the variable first. A missing or empty variable fails the write with SecretRefResolutionError rather than storing something broken. Add --dry-run to check without writing. Check what’s exposed with the built-in audit.

openclaw security audit

Confirm the key applied

Every response comes with x-flexinference-defaults-applied. OpenClaw doesn’t show response headers, so read the request in the dashboard under Logs instead.

Troubleshooting

The model picker is short, or a model is missing. A config-defined provider never calls GET /v1/models, so it shows only the rows you wrote. Regenerate the list from our catalog. Turns report zero tokens and no cost. OpenClaw didn’t ask us for streaming usage, so we sent no usage frame. Set compat.supportsUsageInStreaming to true on each model row. A model id is refused. Rows you wrote by hand can drift from what we run, since the id goes out exactly as written. Regenerate the list from our catalog rather than editing ids. Config edits don’t take effect. The gateway holds the old config. Restart it, and confirm you edited the file that openclaw config file prints. See errors for every refusal we return, and agent keys for the ones that are not specific to OpenClaw.

Get started

Concepts

Using the API

Agent Keys + Integrations

FAQ

Set this up with an agent

Onboard a custom provider

The config file

Fill the model list from our catalog

Global config and profiles

Keep the key out of the config file

Confirm the key applied

Troubleshooting

​Set this up with an agent

​Onboard a custom provider

​The config file

​Fill the model list from our catalog

​Global config and profiles

​Keep the key out of the config file

​Confirm the key applied

​Troubleshooting

Set this up with an agent

Onboard a custom provider

The config file

Fill the model list from our catalog

Global config and profiles

Keep the key out of the config file

Confirm the key applied

Troubleshooting