Skip to main content

OpenClaw manual configuration reference

Use this page only when you skipped onboarding, onboarding did not save the UniKey provider, or you need to restore a known-good configuration. For a new installation, use the onboarding guide first.

This is a complete, copy-and-paste openclaw.json example. You only need to replace PASTE_YOUR_UNIKEY_API_KEY_HERE with your real UniKey API key.

1. Find openclaw.json​

SystemPath
macOS~/.openclaw/openclaw.json
Linux~/.openclaw/openclaw.json
Windows%USERPROFILE%\.openclaw\openclaw.json

~ means your home folder. For example, ~/.openclaw/openclaw.json on macOS is /Users/your-name/.openclaw/openclaw.json.

2. Back up the existing file first​

Do this before editing. The backup gives you an immediate way to restore the previous working configuration.

macOS, Linux, or WSL2:

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

Windows PowerShell:

Copy-Item "$env:USERPROFILE\.openclaw\openclaw.json" "$env:USERPROFILE\.openclaw\openclaw.json.bak"

3. Replace the file contents​

Open the original openclaw.json file, select all its content, and replace it with the following standard configuration. Replace only PASTE_YOUR_UNIKEY_API_KEY_HERE; keep the quotation marks.

{
  "models": {
    "mode": "merge",
    "providers": {
      "unikey": {
        "baseUrl": "https://www.getunikey.ai/v1",
        "apiKey": "PASTE_YOUR_UNIKEY_API_KEY_HERE",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-5.5",
            "name": "GPT-5.5"
          },
          {
            "id": "claude-sonnet-4-6",
            "name": "Claude Sonnet 4.6"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "unikey/gpt-5.2",
        "fallbacks": [
          "unikey/claude-sonnet-4-6"
        ]
      }
    }
  }
}

Save the file. Do not add /chat/completions to the Base URL; OpenClaw adds it automatically.

4. Restart and check OpenClaw​

Run:

openclaw gateway restart
openclaw gateway status
openclaw models status

The model status should include unikey/gpt-5.2. Then send a short message in an OpenClaw chat to confirm it can respond.

If something goes wrong​

  1. Restore the backup file you made in step 2.

    macOS, Linux, or WSL2:

    cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json

    Windows PowerShell:

    Copy-Item "$env:USERPROFILE\.openclaw\openclaw.json.bak" "$env:USERPROFILE\.openclaw\openclaw.json" -Force

  2. Restart the Gateway:

    openclaw gateway restart
    openclaw gateway status

  3. If the problem remains, send the error message and the configuration with the apiKey value replaced by REDACTED to UniKey support. Never send a real API key.

Direct API check​

If the configuration is valid but OpenClaw still cannot respond, check the UniKey key and model directly first.

macOS, Linux, or WSL2:

export UNIKEY_API_KEY="PASTE_YOUR_UNIKEY_API_KEY_HERE"

curl https://www.getunikey.ai/v1/chat/completions \
  -H "Authorization: Bearer $UNIKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.2",
    "messages": [{"role": "user", "content": "Reply with OK."}]
  }'

Windows PowerShell:

$env:UNIKEY_API_KEY = "PASTE_YOUR_UNIKEY_API_KEY_HERE"

curl.exe https://www.getunikey.ai/v1/chat/completions `
  -H "Authorization: Bearer $env:UNIKEY_API_KEY" `
  -H "Content-Type: application/json" `
  -d "{\"model\":\"gpt-5.2\",\"messages\":[{\"role\":\"user\",\"content\":\"Reply with OK.\"}]}"

If this command succeeds but OpenClaw does not, recheck the JSON above and run openclaw models status. If it also fails, check the API key, model access, balance, and network connection.