forked from Selig/openclaw-skill
Selig
4c966a3ad2
6 custom skills (assign-task, dispatch-webhook, daily-briefing, task-capture, qmd-brain, tts-voice) with technical documentation. Compatible with Claude Code, OpenClaw, Codex CLI, and OpenCode.
155 lines
4.3 KiB
Markdown
155 lines
4.3 KiB
Markdown
# 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.
|