> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw integration guide

[OpenClaw](https://openclaw.ai/) is a personal AI assistant that runs directly on your own devices. It responds through the messaging platforms you already use, such as WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, Microsoft Teams, and WebChat, as well as extended channels like BlueBubbles, Matrix, Zalo, and Zalo Personal. It can talk and listen on macOS, iOS, and Android, and display a live, interactive Canvas that you manage. The Gateway serves only as the control layer, the real product is the assistant itself.

## Prerequisites

Before you begin, ensure you have the following set up:

* A free [SambaCloud](https://cloud.sambanova.ai/?utm_source=openclaw\&utm_medium=external\&utm_campaign=cloud_signup) account and API key
* [Node.js](https://nodejs.org/en/download) 22.22.3+, 24.15+, 25.9+, or 26 (recommended). The installer script provisions Node automatically if it is missing.

Confirm your Node.js version:

```bash theme={}
node --version
```

```text theme={}
# Expected output
v26.x.x
```

## Setup

<Steps>
  <Step title="Install OpenClaw">
    ```bash theme={}
    npm install -g openclaw@latest
    ```

    Confirm the install:

    ```bash theme={}
    openclaw --version
    ```

    ```text theme={}
    # Expected output
    OpenClaw <version>
    ```

    <Note>
      npm 12 blocks package lifecycle scripts by default, which skips OpenClaw's `preinstall` and `postinstall` steps. If your install reports blocked scripts, allow them explicitly:

      ```bash theme={}
      npm install -g openclaw@latest --allow-scripts openclaw
      ```
    </Note>
  </Step>

  <Step title="Start OpenClaw">
    ```bash theme={}
    openclaw onboard --install-daemon
    ```

    The onboarding wizard runs once, installs the Gateway as a background service, and opens the Control UI in your browser. Follow the quick-start prompts and keep the default configuration.
  </Step>

  <Step title="Open the Control UI">
    The Control UI is served at [http://127.0.0.1:18789](http://127.0.0.1:18789) by default. To reopen it later, run:

    ```bash theme={}
    openclaw dashboard
    ```

    Confirm the Gateway is running:

    ```bash theme={}
    openclaw gateway status
    ```

    The output should show `Runtime: running` and `Connectivity probe: ok`.
  </Step>
</Steps>

## Add SambaNova as a provider

<Steps>
  <Step title="Add the SambaNova provider configuration">
    Open `~/.openclaw/openclaw.json` in a text editor and add the following keys to the top-level object, replacing `<YOUR-API-KEY>` with your SambaCloud API key from the [SambaCloud portal](https://cloud.sambanova.ai/apis).

    ```json theme={}
    "models": {
      "providers": {
        "sambanova": {
          "baseUrl": "https://api.sambanova.ai/v1",
          "apiKey": "<YOUR-API-KEY>",
          "auth": "api-key",
          "api": "openai-completions",
          "models": [
            {
              "id": "MiniMax-M3",
              "name": "MiniMax-M3",
              "reasoning": true,
              "input": ["text"],
              "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
              "contextWindow": 1048576,
              "maxTokens": 16000,
              "compat": { "maxTokensField": "max_tokens" }
            }
          ]
        }
      }
    },
    "agents": {
      "defaults": {
        "model": {
          "primary": "sambanova/MiniMax-M3"
        }
      }
    },
    ```

    <Note>
      `~/.openclaw/openclaw.json` is JSON5, so comments and trailing commas are allowed. If an `agents` key already exists in your config, merge the `defaults.model.primary` value into it rather than adding a duplicate key.
    </Note>
  </Step>

  <Step title="Validate the config">
    Before restarting, confirm the file has no syntax errors:

    ```bash theme={}
    openclaw config validate
    ```

    ```text theme={}
    # Expected output
    Config valid: <path>
    ```

    If validation fails, open the file and fix the reported line. Common mistakes: a missing comma between top-level keys, or a mismatched brace.
  </Step>

  <Step title="Restart the Gateway">
    ```bash theme={}
    openclaw gateway restart
    ```
  </Step>

  <Step title="Verify the model is registered">
    ```bash theme={}
    openclaw models list
    ```

    `sambanova/MiniMax-M3` appears in the list with `default,configured` in the Tags column.
  </Step>

  <Step title="Start using SambaNova models">
    Return to the chat in the upper-left sidebar of the Control UI and send a message. You can also switch models from the chat by running `/model sambanova/MiniMax-M3`.

    <Frame>
      <img src="https://mintcdn.com/sambanova-systems/R6yzm_ZM-x1BtCKs/images/docs/integrations/openclaw/openclaw3.png?fit=max&auto=format&n=R6yzm_ZM-x1BtCKs&q=85&s=613f6fa6c757555f22901b471c8ff995" alt="OpenClaw chat interface using a SambaNova model" style={{ maxWidth:"100%" }} width="2932" height="1690" data-path="images/docs/integrations/openclaw/openclaw3.png" />
    </Frame>
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Config validation fails after editing openclaw.json">
    Run `openclaw config validate` to see the exact error. The most common causes are a missing comma between top-level JSON keys, a mismatched brace or bracket, or a stray character near the edit. The file is JSON5, so trailing commas inside objects and arrays are allowed — the issue is usually a missing comma between sibling keys at the top level.
  </Accordion>

  <Accordion title="Model override is not allowed">
    If `agents.defaults.modelPolicy.allow` is set, it acts as an allowlist for every model selection. Add `sambanova/MiniMax-M3` or the `sambanova/*` wildcard to that list, or remove the list to allow any model.
  </Accordion>

  <Accordion title="Model not found">
    OpenClaw model refs use the format `provider/model`, so always use `sambanova/MiniMax-M3`. Run `openclaw models list` to confirm the model appears with `configured` in the flags column. If it does not, confirm the `models.providers.sambanova` block was added correctly and that `openclaw gateway restart` ran after the edit.
  </Accordion>

  <Accordion title="Authentication errors from SambaNova">
    Confirm `apiKey` under `models.providers.sambanova` in `~/.openclaw/openclaw.json` holds a valid key from the [SambaCloud portal](https://cloud.sambanova.ai/apis). After editing the config, run `openclaw config validate`, then `openclaw gateway restart`, and verify with `openclaw models status`.
  </Accordion>

  <Accordion title="npm reports blocked lifecycle scripts">
    npm 12 blocks package lifecycle scripts by default, so OpenClaw's `preinstall` and `postinstall` steps are skipped. Reinstall with `npm install -g openclaw@latest --allow-scripts openclaw`.
  </Accordion>

  <Accordion title="The Control UI does not open">
    Run `openclaw dashboard` to reopen it, or browse to [http://127.0.0.1:18789](http://127.0.0.1:18789) directly. Check that the Gateway is running with `openclaw gateway status`, and run `openclaw doctor` for configuration issues.
  </Accordion>
</AccordionGroup>

## Additional resources

* [OpenClaw documentation](https://docs.openclaw.ai/)
* [OpenClaw model providers](https://docs.openclaw.ai/concepts/model-providers)
* [OpenClaw configuration reference](https://docs.openclaw.ai/gateway/configuration-reference)
* [SambaCloud models](/docs/en/models/sambacloud-models)
* [SambaCloud API reference](/docs/en/api-reference/overview)