openclaw-webui/README.md

# OpenClaw WebUI

A modern, OpenWebUI-compatible chat interface for OpenClaw with LDAP SSO support.

## Features

- **Modern Chat Interface** - Clean, responsive UI inspired by OpenWebUI
- **Multi-file Upload** - Attach files with content included in context
- **Code Canvas** - Side panel for code editing and viewing
- **Chat History** - Persistent conversation storage
- **Streaming Responses** - Real-time token streaming
- **LDAP SSO** - Enterprise authentication via LDAP
- **Model Selection** - Switch between OpenClaw agents
- **Dark Theme** - Easy on the eyes

## Quick Start

```bash
# Clone
git clone https://git.theta42.com/nova/openclaw-webui.git
cd openclaw-webui

# Install
npm install

# Development (hot reload)
npm run dev

# Production build
npm run build

# Production server
NODE_ENV=production npm start
```

## Configuration

Uses JSON config files in `conf/` directory:

```
conf/
├── base.json           # Base config (all environments)
├── development.json    # Dev overrides (auth disabled)
├── production.json     # Production overrides
├── secrets.json        # Secrets (gitignored!)
└── secrets.example.json # Template
```

### Load Order

Files merge in order: `base.json` → `[environment].json` → `secrets.json`

### Example Configs

**conf/base.json:**
```json
{
  "server": { "port": 8089 },
  "gateway": { "url": "http://127.0.0.1:18789" },
  "auth": {
    "disabled": false,
    "ldap": {
      "enabled": true,
      "url": "ldap://10.1.0.55:389",
      "baseDN": "dc=example,dc=com",
      "searchFilter": "(uid={{username}})"
    }
  }
}
```

**conf/secrets.json:**
```json
{
  "gateway": { "token": "your-openclaw-token" },
  "session": { "secret": "random-session-secret" },
  "auth": {
    "ldap": {
      "bindDN": "cn=service,ou=people,dc=example,dc=com",
      "bindPassword": "ldap-password"
    }
  }
}
```

### Environment Variables

Can override config at runtime:

- `PORT` - Server port
- `OPENCLAW_GATEWAY` - Gateway URL
- `OPENCLAW_TOKEN` - Gateway auth token
- `SESSION_SECRET` - Session signing secret
- `LDAP_ENABLED` - Enable LDAP auth

## LDAP Authentication

Supports standard LDAP servers (OpenLDAP, Active Directory):

1. Service binds with `bindDN` + `bindPassword`
2. Searches for user with `searchFilter`
3. Binds as user to verify password

**Search Filter:**
Use `{{username}}` as placeholder:
```
(&(memberof=cn=app_access,ou=groups,dc=example,dc=com)(uid={{username}}))
```

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                     OpenClaw WebUI                       │
├─────────────────────────────────────────────────────────┤
│  Frontend (Vanilla JS + Vite)                           │
│  ├── Chat Interface                                      │
│  ├── File Upload (content included)                      │
│  ├── Code Canvas                                         │
│  └── History Sidebar                                     │
├─────────────────────────────────────────────────────────┤
│  Backend (Express.js)                                    │
│  ├── LDAP SSO Authentication                             │
│  ├── Session Management                                  │
│  ├── Chat History Persistence                            │
│  └── /v1/chat/completions Proxy                          │
├─────────────────────────────────────────────────────────┤
│  OpenClaw Gateway (port 18789)                           │
└─────────────────────────────────────────────────────────┘
```

## API Endpoints

### Authentication
- `GET /api/auth/status` - Check auth status
- `POST /api/auth/login` - Login
- `POST /api/auth/logout` - Logout

### Conversations
- `GET /api/conversations` - List conversations
- `POST /api/conversations` - Create conversation
- `PUT /api/conversations/:id` - Update conversation
- `DELETE /api/conversations/:id` - Delete conversation
- `GET /api/conversations/:id/messages` - Get messages

### OpenAI-Compatible
- `POST /v1/chat/completions` - Chat (proxied to OpenClaw)
- `GET /v1/models` - List models

## Production Deployment

**Systemd Service:**
```bash
# Create service file
mkdir -p ~/.config/systemd/user
cp openclaw-webui.service ~/.config/systemd/user/

# Enable and start
systemctl --user enable openclaw-webui
systemctl --user start openclaw-webui

# View logs
journalctl --user -u openclaw-webui -f
```

**Requirements:**
- OpenClaw Gateway running on port 18789
- Enable HTTP chat completions in gateway config:
```json
{
  "gateway": {
    "http": {
      "endpoints": { "chatCompletions": { "enabled": true } }
    }
  }
}
```

## Development

```bash
npm run dev
# Frontend: http://localhost:5173 (Vite HMR)
# Backend: http://localhost:3000 (auto-restart)
```

## License

MIT