openclaw-skill/openclaw-knowhow-skill/openclaw-experience-and-suggestions.md

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:

"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):

"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:

/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

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)

---
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.