# OpenClaw Gateway Setup Guide

## Architecture Overview

OpenClaw consists of two main components:

```
┌─────────────────────────────────────────────────────────────┐
│                    OpenClaw System                           │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────┐         ┌──────────────────────────┐     │
│  │  Dashboard  │◄────────┤  Gateway (API Server)    │     │
│  │  (Web UI)   │   HTTP  │  Port 18789              │     │
│  └─────────────┘         └──────────────────────────┘     │
│         ▲                          │                       │
│         │                          │                       │
│         └──────────────────────────┘                       │
│    Your Browser          Background Service                │
└─────────────────────────────────────────────────────────────┘
```

### Components

1. **Gateway** (`openclaw gateway`)
   - Background API service that runs the AI agent
   - Listens on port 18789
   - Handles AI model connections (Ollama, OpenAI, etc.)
   - Manages chat state and channels
   - **Must be running** for the dashboard to work

2. **Dashboard** (`openclaw dashboard`)
   - Web UI that connects to the gateway API
   - Displays chat interface, model status, and configuration
   - Runs in your browser at http://127.0.0.1:18789/
   - **Cannot function** without the gateway running

## Your Current Setup

### Status: ✅ Working

You have successfully:
1. Installed OpenClaw with zero-interaction installer
2. Automatically removed old conflicting installation
3. Installed the gateway service
4. Started the gateway service
5. Verified dashboard and gateway functionality

### What Works Now

```powershell
# Check gateway status
& "$env:USERPROFILE\bin\openclaw.cmd" gateway status

# Start/restart gateway (if needed)
& "$env:USERPROFILE\bin\openclaw.cmd" gateway restart

# Open dashboard
& "$env:USERPROFILE\bin\openclaw.cmd" dashboard

# All of these now work without errors!
```

### PATH Issue Reminder

Your installation is complete, but you need to **restart PowerShell** for the PATH changes to take effect. After restart, you'll be able to use:

```powershell
openclaw dashboard  # Instead of the full path
openclaw gateway status
openclaw --version
```

Until you restart, continue using the full path:
```powershell
& "$env:USERPROFILE\bin\openclaw.cmd" dashboard
```

## Complete Installation Process

### What the Zero-Interaction Installer Does

1. **Node.js Setup**
   ```
   • Checks for Node.js v22+
   • Downloads v22.16.0 if missing/broken
   • Configures isolated Node.js environment
   ```

2. **OpenClaw Installation**
   ```
   • Installs openclaw package locally (not globally)
   • Clears npm cache to prevent corruption
   • Installs to: %LOCALAPPDATA%\openclaw-installer\
   ```

3. **Configuration**
   ```
   • Sets AI provider credentials from config file
   • Runs openclaw onboard --yes
   ```

4. **Wrapper Creation**
   ```
   • Creates: %USERPROFILE%\bin\openclaw.cmd
   • Sets NODE_PATH for module resolution
   • Removes old conflicting wrappers automatically
   ```

5. **Gateway Installation (NEW)**
   ```
   • Runs: openclaw gateway install
   • Sets up Windows Scheduled Task
   • Creates service scripts in ~/.openclaw/
   ```

6. **Gateway Startup (NEW)**
   ```
   • Runs: openclaw gateway start
   • Starts background API service
   • Service runs on port 18789
   ```

## Troubleshooting

### If Dashboard Shows "Unable to Connect"

The gateway is not running. Check status:
```powershell
& "$env:USERPROFILE\bin\openclaw.cmd" gateway status
```

If not running, start it:
```powershell
& "$env:USERPROFILE\bin\openclaw.cmd" gateway start
```

### If Gateway Won't Start

Check logs:
```powershell
Get-Content ~\.openclaw\openclaw-2026-03-21.log -Tail 20
```

Common issues:
- Port 18789 already in use
- Missing configuration file
- Invalid AI provider credentials

### If You Get "command not found"

You need to restart PowerShell for PATH changes, or use full path:
```powershell
& "$env:USERPROFILE\bin\openclaw.cmd" <command>
```

## Verification Commands

All of these should work after your installation:

```powershell
# 1. Check openclaw version
& "$env:USERPROFILE\bin\openclaw.cmd" --version
# Expected: OpenClaw 2026.3.13 (61d171a)

# 2. Check gateway status
& "$env:USERPROFILE\bin\openclaw.cmd" gateway status
# Expected: Service: Scheduled Task (registered), Runtime: running

# 3. Open dashboard
& "$env:USERPROFILE\bin\openclaw.cmd" dashboard
# Expected: Opens browser to http://127.0.0.1:18789/

# 4. View logs
& "$env:USERPROFILE\bin\openclaw.cmd" logs
# Expected: Shows recent gateway logs
```

## Summary

You now have a **fully functional OpenClaw installation** with:
- ✅ Zero-interaction installer
- ✅ Automatic conflict resolution
- ✅ Gateway service installed and running
- ✅ Dashboard accessible
- ✅ Isolated Node.js v22.16.0
- ✅ Working wrapper with correct NODE_PATH

**To use immediately:** Use the full path with `& "$env:USERPROFILEinileileileileile.cmd"`

**After PowerShell restart:** Can use `openclaw <command>` directly

The system is production-ready! 🚀
