OpenClaw Integration

OpenClaw connects to KOPRouter over the OpenAI-compatible interface. Put the Base URL, API key, and model into the config file and OpenClaw’s agents use KOPRouter models, with authentication and billing handled through KOPRouter.

**Prerequisites**
  • Node.js 22 or newer (the OpenClaw runtime)
  • A KOPRouter API key (prefixed with sk-)

Install OpenClaw

Install globally with npm:

npm install -g openclaw@latest

You can also use the official installer: on macOS / Linux run curl -fsSL https://openclaw.ai/install.sh | bash, or on Windows run iwr -useb https://openclaw.ai/install.ps1 | iex in PowerShell.

Then run openclaw --version — seeing a version number means it installed successfully.

Core configuration

Connecting to KOPRouter needs three values:

  • Base URL: https://koprouter.kopglobal.com/v1 (KOPRouter’s OpenAI-compatible root)
  • API Key: your KOPRouter API key (prefixed with sk-)
  • Model: a model ID in KOPRouter, taken from the id returned by /v1/models

Option 1: Write to openclaw.json (recommended)

OpenClaw reads the user-level config file ~/.openclaw/openclaw.json. Put all three values there at once — no other setup needed.

The file path is `~/.openclaw/openclaw.json`. Create the `.openclaw` directory first if it doesn't exist: 
```bash
mkdir -p ~/.openclaw
nano ~/.openclaw/openclaw.json
```
The file path is `%USERPROFILE%\.openclaw\openclaw.json` (usually `C:\Users\\.openclaw\openclaw.json`). Using CMD as an example: 
```bat
if not exist "%USERPROFILE%\.openclaw" mkdir "%USERPROFILE%\.openclaw"
notepad "%USERPROFILE%\.openclaw\openclaw.json"
```

Write the following (replace MODEL_ID with a model ID returned by /v1/models):

{
  "models": {
    "mode": "merge",
    "providers": {
      "koprouter": {
        "baseUrl": "https://koprouter.kopglobal.com/v1",
        "apiKey": "sk-...",
        "api": "openai-completions",
        "models": [
          { "id": "MODEL_ID" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "koprouter/MODEL_ID" },
      "models": { "koprouter/MODEL_ID": {} }
    }
  },
  "gateway": { "mode": "local" }
}

Save it, then restart OpenClaw.

* `baseUrl` must live under `models.providers.koprouter` — placing it on a model entry or under a top-level `providers` key is ignored. * `agents.defaults.model.primary` uses the `provider/model-id` format and must also be listed in `agents.defaults.models` (the allowlist), otherwise OpenClaw reports "model not allowed". * If the file already exists, **merge** your changes in rather than overwriting the whole file (overwriting drops other existing config); back it up first. * An inline key is stored in plaintext: run `chmod 600 ~/.openclaw/openclaw.json` and never commit it to git.

Option 2: Configure with openclaw onboard

If you’d rather not hand-write JSON, run OpenClaw’s built-in setup wizard and follow the prompts (it writes to openclaw.json as well):

openclaw onboard

In the wizard, choose a Custom / OpenAI-compatible provider and enter https://koprouter.kopglobal.com/v1, your API key, and the model ID.

Select and switch models

Set the default model to one available in KOPRouter:

openclaw models set koprouter/MODEL_ID

Check the state of your configured models:

openclaw models status --plain

Model IDs always come from the id returned by /v1/models. If you don’t set one, OpenClaw uses its built-in default model name, which will fail with “model not found” if KOPRouter has no matching model.

Verify

openclaw config validate

If validation passes and openclaw models status --plain lists your model, the setup is correct. You can then start a conversation to test.

* If KOPRouter and OpenClaw run on the same machine behind a local proxy, use `127.0.0.1` instead of `localhost` in the Base URL to avoid IPv6 resolution issues. * `models[].id` may carry optional metadata such as `name`, `contextWindow`, and `maxTokens` — if unsure, just set `id`.

Troubleshooting

There is no `openclaw restart` command — kill the process and relaunch it (some versions auto-reload based on `gateway.reload.mode`). Confirm the changes are saved to `~/.openclaw/openclaw.json` and that `openclaw config validate` passes. The `provider/model-id` in `agents.defaults.model.primary` must also appear in `agents.defaults.models` — keep the two in sync. The model ID in `models[].id` and `model.primary` must be an `id` returned by `/v1/models`; anything else returns a 404. **Can't connect (network restricted)?**

If your network cannot reach KOPRouter directly (e.g. mainland China), write the proxy into openclaw.json or set it with a command:

openclaw config set proxy.proxyUrl http://127.0.0.1:7890

7890 is only an example port — replace it with your own proxy client’s actual port. OpenClaw does not read the HTTP_PROXY / HTTPS_PROXY environment variables — it only supports proxy.proxyUrl. See Network & Proxy for details.