# OpenClaw + Luma Cloud Add a custom Luma Cloud provider and select it for one agent session. API connection: Chat Completions. Instructions checked: 2026-09-28. Client capabilities and versions may vary; follow the verification steps below. This is an API setup guide. SuperGPT desktop installation and sign-in are separate; use a customer API key for the client described here. ## 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. ## Setup 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. ## Merge into openclaw.json ```json { "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" ] } ] } } } } ``` Keep the secret reference as an object; do not replace it with the key. This fragment does not change global defaults or existing fallback lists. ## Inspect and validate · terminal on the OpenClaw machine ```sh openclaw --version openclaw config file openclaw config validate openclaw models list --provider luma-cloud ``` Run once before editing to record the original state, then validate and list again after saving. These commands do not ask a model to generate a response. Do not share full diagnostic files without checking for private data. ## Inside a new OpenClaw chat · keep the choice session-only ```text /model luma-cloud/MODEL_ID_FROM_CATALOG -s /model status Reply with: Luma connection ready. ``` Replace the placeholder first and send the commands separately. Confirm the selected model before the billable third line. Do not use -g or -a unless you intend to change defaults for other sessions or agents. ## Return this session to its existing default ```text /model default -s ``` This clears the session choice; it does not delete the Luma provider or change the shared default. For full removal, first move Luma sessions to another model, then remove only the provider entry and its unused secret reference. ## Verify - Run openclaw models list --provider luma-cloud to inspect configured models. In chat, /model status shows the selected provider and protocol. - Start a new session with the exact Luma Cloud model selected and ask for a short text reply. This is a billable API request. - 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. ## Limits - 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 ### SecretRef resolution failed Check the variable exists in the actual OpenClaw runtime environment, and that provider: default matches your environment secret provider. A service does not inherit an export from your current terminal. Keep secrets in the private runtime environment, not a shared workspace file. ### Model exists but selection is blocked Check the existing agent model policy. Add only luma-cloud/ followed by your exact model ID to the appropriate allowlist if that is your intended policy. Keep other entries and agent defaults; do not replace the full allowlist with this one model. ### Configuration is valid but a request returns 404 or 400 Use the Base URL ending in /v1, not /chat/completions, and api: openai-completions for this recipe. Check the exact model ID and remove unverified capability or reasoning overrides. A valid JSON file does not prove the API parameters are supported. ### Usage comes from a different model or provider Inspect /model status, the session selection and existing fallback settings. Confirm which request actually completed before comparing usage. Do not change every agent's fallback list to troubleshoot one new Luma session. ## Official client documentation - [OpenClaw: custom providers](https://docs.openclaw.ai/gateway/config-tools/custom-providers) - [OpenClaw: environment SecretRefs](https://docs.openclaw.ai/gateway/secrets/secretref-contract) - [OpenClaw: session model selection](https://docs.openclaw.ai/concepts/models) - [OpenClaw: active configuration and validation](https://docs.openclaw.ai/cli/config) - [OpenClaw: runtime environment and private dotenv](https://docs.openclaw.ai/help/environment)