OpenClaw + Luma Cloud

Before you start

• Create a portable key in Dashboard → API. Use API Wallet credit, or a Builder key when that option is available to your account.
• This is a direct API connection. SuperGPT is not required. Use a named Wallet key on any plan, or a subscription key if your Builder account offers one; your desktop sign-in is not an API key.
• Load LUMA_CLOUD_API_KEY from your secret manager or a private environment before starting the client. Never put the key in a prompt, Git, or a shared configuration file.
• OpenClaw already installed and configured. Run the checks on the machine that hosts your OpenClaw process; a remote web UI does not read files from your laptop.

Get an API key and a model ID →

Set up OpenClaw

1. Find the active file and keep a backup

   Run openclaw config file before editing. The default is ~/.openclaw/openclaw.json, but a profile or OPENCLAW_CONFIG_PATH may select another file. On Windows/WSL, use the path reported by the OpenClaw command in that environment, not a similarly named host folder. Make a private backup and merge only the new provider.

2. Add the provider

   Merge luma-cloud under models.providers in ~/.openclaw/openclaw.json. Keep existing entries, channel settings, and agent defaults. Replace MODEL_ID_FROM_CATALOG with the exact Luma model ID.

3. Connect the secret

   The example uses an environment SecretRef. For a running service, enter LUMA_CLOUD_API_KEY in its supported secret environment or the private runtime file ~/.openclaw/.env (OPENCLAW_STATE_DIR/.env if customized), then restart that service normally after active work finishes. A key exported in another terminal or stored only in a project's .env is not sufficient. If your default environment secret provider has another name, use that name instead of default.

4. Validate before opening chat

   Run openclaw config validate and openclaw models list --provider luma-cloud. Correct schema or secret-reference errors first. A listed model verifies configuration only. Open your normal OpenClaw chat after its configuration has reloaded; do not start a second service over the existing one.

5. Choose it for a new session

   In OpenClaw chat, use /model luma-cloud/MODEL_ID_FROM_CATALOG -s. The -s flag keeps the choice within this session. If a model policy blocks it, add this exact model to the existing allowlist without deleting other entries.

{
  "models": {
    "providers": {
      "luma-cloud": {
        "baseUrl": "https://api.lumaos.cloud/v1",
        "api": "openai-completions",
        "apiKey": {
          "source": "env",
          "provider": "default",
          "id": "LUMA_CLOUD_API_KEY"
        },
        "models": [
          {
            "id": "MODEL_ID_FROM_CATALOG",
            "name": "Luma Cloud model",
            "input": [
              "text"
            ]
          }
        ]
      }
    }
  }
}

openclaw --version
openclaw config file
openclaw config validate
openclaw models list --provider luma-cloud

/model luma-cloud/MODEL_ID_FROM_CATALOG -s
/model status
Reply with: Luma connection ready.

/model default -s

Check the connection

1. Run openclaw models list --provider luma-cloud to inspect configured models. In chat, /model status shows the selected provider and protocol.
2. Start a new session with the exact Luma Cloud model selected and ask for a short text reply. This is a billable API request.
3. For Wallet keys, check Usage → API Wallet for the matching usage. For Builder keys, check subscription Usage. A model in a picker confirms configuration, not a successful response.

For errors or a request that stops, see troubleshooting. A visible model list alone does not confirm that a chat or editing task can complete.

What to expect

• openai-completions means Chat Completions in OpenClaw. Use openai-responses only for a model and workflow that support Responses.
• Image, tool, reasoning, and stored-response continuation flags are separate capabilities. Do not enable them merely because the base URL is accepted.

Troubleshooting OpenClaw