# OpenClaw Experience And Suggestions

This memo is based on your current deployment (`oclaw.nature.edu.kg` + local `cliproxyapi`) and real incidents we fixed.

## 1) What Matters Most In Production

### 1.1 Gateway auth and reverse proxy
- Keep OpenClaw gateway bound to loopback (`127.0.0.1`).
- Put Nginx in front with HTTPS + Basic Auth.
- Configure trusted proxy in `~/.openclaw/openclaw.json`:
```json
"gateway": {
  "bind": "loopback",
  "trustedProxies": ["127.0.0.1", "::1", "::ffff:127.0.0.1"]
}
```
- Without `trustedProxies`, you get repeated remote-auth issues behind reverse proxy.

### 1.2 Device pairing is per browser identity
- New browser profile/device = new pairing.
- Same browser profile usually does not need re-pair.
- If you travel (home/office) with same laptop + same Chrome profile, usually no re-pair.

### 1.3 Model metadata must be realistic
- OpenClaw blocks too-small context window.
- We hit: `Model context window too small (4096). Minimum is 16000.`
- Fix by setting a larger value (for your current setup, `32000` works):
```json
"contextWindow": 32000
```

### 1.4 Don’t disable device auth for Control UI
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` can cause scope behavior you do not want.
- Better pattern: keep pairing + proper operator scopes.

## 2) Pairing Operations (Fast Path)

You already have this helper:

```bash
/home/Selig/bin/oclaw-approve-pending
```

It auto:
1. approves pending requests
2. rotates token with scopes:
   - `operator.read`
   - `operator.write`
   - `operator.admin`
   - `operator.approvals`
   - `operator.pairing`

Use this whenever a new browser says:
- `disconnected (1008): pairing required`

## 3) Why You Saw Internal Tool Logs In Chat

Root cause is usually workspace prompt policy (AGENTS/skill rules), not gateway failure.

Good policy:
- keep memory read/write enabled
- keep tool operations hidden by default
- show tool details only when user asks or when debugging failure

This gives:
- natural chat UX
- still keeps durable memory behavior

## 4) Recommended OpenClaw Skill Design

For your environment, split into 3 focused skills:

1. `openclaw-ops`
- Pairing approve flow
- Gateway restart/status/log triage
- Scope fixes and common 1008 errors

2. `openclaw-llm-provider`
- Provider config validation (`baseUrl`, `apiKey`, `api`, `models`)
- Context window sanity checks
- Smoke test checklist

3. `openclaw-chat-behavior`
- “No internal logs in normal reply” policy
- Memory strategy (daily note + long-term memory)
- Verbose/debug toggles

## 5) Suggested Skill Folder Template

```text
openclaw-ops/
├── SKILL.md
├── references/
│   ├── pairing.md
│   ├── auth-and-scopes.md
│   └── troubleshooting.md
└── scripts/
    ├── approve_pending.sh
    └── check_gateway_health.sh
```

## 6) Minimal `SKILL.md` Starter (Example)

```md
---
name: openclaw-ops
description: Operate OpenClaw gateway behind reverse proxy, including pairing approval, device scope repair, and common 1008 auth/pairing troubleshooting.
---

# OpenClaw Ops

## Trigger
Use this skill when user reports:
- pairing required
- unauthorized/token missing
- disconnected 1008
- gateway not responding

## Workflow
1. Check gateway service status and last 100 log lines.
2. Check pending pairings; approve and rotate scopes.
3. Verify `gateway.trustedProxies`.
4. Confirm model context window is >= 16000.
5. Re-test via one CLI message.

## Commands
- `systemctl --user status openclaw-gateway`
- `journalctl --user -u openclaw-gateway -n 100 --no-pager`
- `/home/Selig/bin/oclaw-approve-pending`
```

## 7) Operational Guardrails I Recommend

- Keep gateway token out of chat logs when possible.
- Rotate Basic Auth password periodically.
- Add a tiny health script and run it by cron every 5-10 minutes:
  - gateway active?
  - websocket accepts connect?
  - one lightweight model call works?
- Keep a single source-of-truth runbook with:
  - URLs
  - restart commands
  - pairing command
  - known-good config snippet

## 8) Your Current “Known Good” Baseline

- OpenClaw gateway running as user service.
- Nginx + TLS active for `oclaw.nature.edu.kg`.
- Trusted proxies configured.
- Helper approve script available.
- Model context window updated to a valid size.

If this baseline is kept, day-to-day stability should be good.