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

# OpenClaw

> Setup Guide for OpenClaw Agent using ZnapAI Gateway

# OpenClaw Setup on Windows with Custom Provider

## 1. Install OpenClaw

You can install OpenClaw using the official installer or via npm.

### Option 1: Official Installer (Recommended)

### Windows (PowerShell)

```powershell theme={null}
iwr -useb https://openclaw.ai/install.ps1 | iex
```

### macOS / Linux

```bash theme={null}
curl -fsSL https://openclaw.ai/install.sh | bash
```

This installs OpenClaw and performs the initial setup automatically.

### Option 2: Install via npm

Requires Node.js to be installed.

```bash theme={null}
npm install -g openclaw
```

### Verify Installation

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

You should see the installed OpenClaw version displayed.

***

## 2. Locate the Configuration File

Open:

```text theme={null}
C:\Users\<username>\.openclaw\openclaw.json
```

or

```powershell theme={null}
notepad $env:USERPROFILE\.openclaw\openclaw.json
```

Replace the entire contents of `openclaw.json` with:

```json theme={null}
{
  "agents": {
    "defaults": {
      "workspace": "C:\\Users\\<username>\\.openclaw\\workspace",
      "models": {
        "znapai/gpt-5.3-codex": {
          "alias": "GPT"
        }
      },
      "model": {
        "primary": "znapai/gpt-5.3-codex"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "znapai": {
        "baseUrl": "https://api.znapai.com/v1",
        "apiKey": "${ZNAPAI_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-5.3-codex",
            "name": "GPT-5.3 Codex",
            "contextWindow": 128000,
            "maxTokens": 32000
          }
        ]
      }
    }
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "hello"
    },
    "port": 18789,
    "bind": "loopback",
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    }
  }
}
```

<Note>
  If you need to add additional models, ensure you add them to both the `agents.defaults.models` object and the `models.providers.znapai.models` array in the JSON file using the same format as `gpt-5.3-codex`.
</Note>

***

## 3. Configure API Key

Set the API key as an environment variable:

### For Current PowerShell Session

```powershell theme={null}
$env:ZNAPAI_API_KEY="your-api-key"
```

Verify:

```powershell theme={null}
echo $env:ZNAPAI_API_KEY
```

### Permanent Configuration

```powershell theme={null}
[Environment]::SetEnvironmentVariable(
  "ZNAPAI_API_KEY",
  "<your-api-key>",
  "User"
)
```

Open a new PowerShell window and verify:

```powershell theme={null}
echo $env:ZNAPAI_API_KEY
```

***

## 4. Validate Configuration

```powershell theme={null}
Get-Content $env:USERPROFILE\.openclaw\openclaw.json | ConvertFrom-Json
```

No output means the JSON is valid.

***

## 5. Start OpenClaw Gateway

```powershell theme={null}
openclaw gateway
```

Expected output:

```text theme={null}
[gateway] agent model: znapai/gpt-5.3-codex
[gateway] ready
```

***

## 6. Verify Gateway Health

Open another terminal:

```powershell theme={null}
openclaw gateway health
```

Expected:

```text theme={null}
Gateway Health
OK
```

Check status:

```powershell theme={null}
openclaw gateway status
```

Expected:

```text theme={null}
Listening: 127.0.0.1:18789
```

***

## 7. Launch OpenClaw

```powershell theme={null}
openclaw
```

<Frame>
  <img src="https://mintcdn.com/znapai/1L_GdOoq052j6SDb/images/integrations/openclaw-terminal.png?fit=max&auto=format&n=1L_GdOoq052j6SDb&q=85&s=4a33e43f407eb90e103ff8f30870b5f1" alt="OpenClaw Terminal" width="1083" height="402" data-path="images/integrations/openclaw-terminal.png" />
</Frame>

Initially, OpenClaw launches into **Crestodian**, the setup and troubleshooting assistant.

Example:

```text theme={null}
Hi, I'm Crestodian.

- Start me when setup, config, Gateway, model choice, or agent routing feels off.
- Using: znapai/gpt-5.3-codex for fuzzy local planning.
```

Crestodian is not the main conversational agent.

To switch to the actual chat agent, type:

```text theme={null}
talk to agent
```

Expected output:

```text theme={null}
Opening your normal agent TUI.
```

After switching, you can chat normally with the configured model.

***

## Troubleshooting

### JSON Syntax Error

Example:

```json theme={null}
"apiKey": "${ZNAPAI_API_KEY}"
"api": "openai-completions"
```

Missing comma.

Correct:

```json theme={null}
"apiKey": "${ZNAPAI_API_KEY}",
"api": "openai-completions"
```

### Unknown Model Error

```text theme={null}
Unknown model: znapai/gpt-5.3-codex
```

Ensure:

* Provider name is `znapai`
* Default model is `znapai/gpt-5.3-codex`
* Model exists under `models.providers.znapai.models[]`

### Gateway Start Blocked

```text theme={null}
Gateway start blocked: existing config is missing gateway.mode
```

Ensure:

```json theme={null}
"gateway": {
  "mode": "local"
}
```

exists in the configuration.