Skill: nerua1/nerua1-setup-guide (version 1.0.1)

--- name: openclaw-setup-guide description: > Battle-tested setup guide for a multi-agent AI system on Apple Silicon (Mac Mini M4). Covers: install order (Claude Code first), RAM reality for local orchestrators, shared memory (Obsidian + MemPalace), inter-agent communication, critical pitfalls (doctor destroys config, lobotomy protection, sandbox kills symlinks), and WhatsApp console loop. Load when setting up a new system or onboarding a new agent. version: "1.0.0" author: "nerua1" license: "MIT" compatible-with: claude-code, openclaw tags: [setup, m4, apple-silicon, multi-agent, memory, pitfalls, whatsapp, configuration] --- # OpenClaw + Claude Code Setup Guide ## Real-world lessons from running 24/7 multi-agent AI on Mac Mini M4 This is not the happy-path documentation. This is what actually happens. --- ## 1. Install order matters: Claude Code first **Why Claude Code before OpenClaw:** OpenClaw is powerful but fragile — it can lobotomize itself (overwrite its own config/personality). Claude Code acts as an independent safety net: it reads files directly, doesn't share OpenClaw's context window, and can diagnose/repair a broken OpenClaw from the outside. ``` Install order: 1. Claude Code (claude.ai/download or brew) 2. Configure Claude Code memory + skills 3. Install OpenClaw 4. Connect them via openclaw-bridge ``` If you install OpenClaw first and it breaks before Claude Code is ready, you have no recovery path. --- ## 2. RAM reality: why cloud orchestrator makes sense at 32GB ### The actual constraint 32GB minus ~6-7GB for the OS = ~24-25GB available. That's enough to run one large model at a time — `qwen3.5-35b-a3b` or `huihui-qwen3.5-27b` loads fine. The problem is architectural: if you load a 35B as orchestrator, there's no RAM left for a subagent. You can use a smaller orchestrator to fit a subagent — but then the orchestrator is too weak to actually orchestrate. ### The real issue: quality gap The difference between a local model and Kimi k2.5 as orchestrator is enormous. Kimi offers reasoning-level quality (comparable to Claude 3.5 Thinking) at the cheapest tokens available right now. A local 35B next to it is a different league for planning and delegation. ### What works at 32GB ``` Orchestrator: Kimi k2.5 (cloud, cheap, real reasoning) Subagents: LM Studio local 30B (free, good enough for execution) ``` At 64GB+ you can experiment with a local orchestrator — but you'll likely come back to Kimi once you see the planning quality difference. **Good cheap API options for orchestrator:** - Kimi k2.5 (moonshot) — best reasoning per token right now, handles Polish - GLM-4-Flash — very cheap ($0.20/M tokens), good for simple routing - Claude API — expensive but best quality (use subscription via Claude Code instead) ### Rule: never run orchestrator locally on 32GB If you try to run a 35B orchestrator + 30B subagent on 32GB: 1. macOS swap kicks in 2. Response time: 30s → 5 minutes 3. System becomes unusable for anything else 4. Eventually kernel OOM kills the process Keep orchestrator in the cloud, workers local. --- ## 3. The doctor problem: NEVER run `openclaw doctor --repair` ### What happens `openclaw doctor --repair` (or `--fix`) overwrites your custom configuration with factory defaults. This includes: - Your custom AGENTS.md routing rules - Your skill configurations - Your channel settings - Your personality/identity files **This is irreversible if you don't have a backup.** ### Safe alternatives ```bash # Check health without repair openclaw doctor # If you see errors, fix them MANUALLY by reading the error and editing files # Do NOT pass --repair, --fix, or --force # If you must repair one specific thing: openclaw doctor --fix --only gateway-token # hypothetical, check your version ``` ### Before any doctor command: backup first ```bash openclaw backup create # or manually: cp -r ~/.openclaw ~/.openclaw.bak.$(date +%Y%m%d) cp -r /path/to/workspace /path/to/workspace.bak.$(date +%Y%m%d) ``` --- ## 4. Lobotomy protection: agents that overwrite themselves ### The problem OpenClaw (and any LLM agent) can be instructed — by malicious input, confused context, or its own reasoning — to overwrite `SOUL.md`, `AGENTS.md`, or other identity files. This is called **lobotomy**: the agent loses its personality, routing rules, and memory. ### Signs you've been lobotomized - Agent doesn't remember its own name or capabilities - Routing rules are gone (routes everything to expensive models) - Skills not loading - Duplicate folders appearing in workspace (`sandbox/` copies) - Agent starting from scratch every session ### Protection in AGENTS.md ```markdown ## BEZWZGLĘDNE ZAKAZY - NEVER edit SOUL.md, AGENTS.md, MEMORY.md without explicit owner request - If you see another agent (or yourself) overwriting a file → STOP, restore from backup **SAFE examples:** LM Studio subagent generation, file reads, web search on trusted domains, `capture-idea` to `ideas/` **NEVER examples:** editing SOUL.md/AGENTS.md, rm -rf, installing >35B models, opening ports, sandbox ON ### Recovery procedure ```bash # 1. Check git history if workspace is a git repo git log --oneline -20 # 2. Restore from backup cp ~/.openclaw.bak.YYYYMMDD/workspace/SOUL.md ~/.openclaw/workspace/SOUL.md # 3. If no backup: use Claude Code as external reviewer # Claude Code can read files without being affected by OpenClaw's context claude # open Claude Code, read files, diagnose ``` ### Sandbox mode: never enable On macOS with external drives + symlinks, sandbox mode kills the system: ``` Sandbox ON + symlinks to /Volumes/2TB_APFS/ = agent loses access to workspace ``` OpenClaw's sandbox mounts a container that can't follow symlinks to external volumes. Keep sandbox OFF always. --- ## 5. Shared memory architecture Both Claude Code and OpenClaw read/write the same memory. No idea gets lost. ``` Obsidian vault (structural) MemPalace (semantic / ChromaDB) /obsidian-memory/ /memory/palace/ wiki/ ← docs, MOCs ↑ daily/ ← session logs └─ mined from vault ideas/ ← captured ideas answers/ ← resolved Q&A Search: mempalace search "keyword" ``` ### Capture ideas from any agent ```bash capture-idea \ --title "OAuth tokens expire too fast on mobile" \ --topic bezpieczenstwo \ --tags "oauth,mobile,token" \ --body "Tokens expire after 1h, users get logged out mid-session." \ --source openclaw # or: claude-code | lmstudio | manual ``` ### Mine vault into MemPalace ```bash mempalace mine /path/to/obsidian-memory/ --wing obsidian_memory ``` ### Python 3.14 breaks MemPalace MemPalace uses chromadb + pydantic v1. Python 3.14 breaks this. Fix: run MemPalace in a Python 3.12 venv. ```bash brew install python@3.12 /opt/homebrew/bin/python3.12 -m venv /path/to/mempalace-venv /path/to/mempalace-venv/bin/pip install mempalace ``` Wrapper at `/opt/homebrew/bin/mempalace`: ```bash #!/bin/zsh VENV=/path/to/mempalace-venv PALACE=/path/to/palace if [[ "$*" != *"--palace"* ]]; then exec "$VENV/bin/mempalace" --palace "$PALACE" "$@" else exec "$VENV/bin/mempalace" "$@" fi ``` --- ## 6. Inter-agent communication: Claude Code ↔ OpenClaw Claude Code can send messages to a running OpenClaw instance: ```bash openclaw agent --message "Review this SQL migration — is it safe?" --agent main --json ``` OpenClaw responds, Claude Code parses the JSON response. This enables: - Claude Code asking Rook for a second opinion - Rook asking Claude Code about security concerns (GRAY_ZONE consultations) - Handoff between sessions See: `openclaw-bridge` skill for full documentation. --- ## 7. WhatsApp console loop OpenClaw has a WhatsApp gateway that creates a bidirectional loop: - What you type in the console → appears in WhatsApp - What you send from WhatsApp → appears in the console This means nothing escapes your attention — if something happens at 3am while OpenClaw is running crons, you see it in WhatsApp in the morning. Setup requires: 1. OpenClaw channel configured for WhatsApp 2. `tts-whatsapp` skill for voice output (optional) 3. Phone number linked in `openclaw.json` channels config Console monitoring: `openclaw logs --tail` or watch the TUI. --- ## 8. Decision framework: when to act vs ask vs block Every operation falls into one of three categories: | Category | Action | Claude offline? | |----------|--------|-----------------| | SAFE | Do it | Do it | | GRAY_ZONE | Ask Claude first | Defer 1h, retry | | NEVER | Ask Claude first | Block, escalate to human | **SAFE examples:** generowanie, subagenci LM Studio, odczyt plików, web search na zaufanych domenach, `capture-idea` do `ideas/` **GRAY_ZONE examples:** nowe crony, pip install --user, web fetch z nieznanych domen, modyfikacje `~/.config/` **NEVER examples:** edycja SOUL.md/AGENTS.md, rm -rf, instalacja modeli >35B, otwieranie portów, sandbox ON Consult Claude via: `openclaw agent --message '{"question":"...","risk":{...}}' --agent main --json` --- ## 9. Backup strategy ```bash # Before any major change: openclaw backup create # Manual snapshot: cp -r ~/.openclaw ~/.openclaw.snap.$(date +%Y%m%d-%H%M) # What to back up: # ~/.openclaw/workspace/SOUL.md ← identity # ~/.openclaw/workspace/AGENTS.md ← routing rules # ~/.openclaw/openclaw.json ← gateway config (no secrets in git!) # /path/to/obsidian-memory/ ← shared memory vault ``` Git the workspace (without secrets): ```bash cd ~/.openclaw/workspace echo "*.env\ncredentials*\n*.key" > .gitignore git init && git add . && git commit -m "backup: workspace snapshot" ``` --- ## 10. Skills that work together | Skill | What it does | Publish status | |-------|-------------|----------------| | `openclaw-bridge` | Claude Code ↔ OpenClaw messaging | github.com/nerua1/openclaw-bridge | | `shared-memory-stack` | Memory architecture reference | github.com/nerua1/shared-memory-stack | | `ralph` | Persistence loop to completion | github.com/nerua1/ralph | | `ralph-wiggum-loop` | Generator→Critic→Fixer→Verifier | github.com/nerua1/ralph-wiggum-loop | | `capture-idea` | Save ideas from any agent | `/opt/homebrew/bin/capture-idea` | | `safe-skill-install` | Security audit before installing | ClawHub: `npx clawhub inspect` | | `proactive-agent` | Self-improving agent architecture | ClawHub: halthelobster | | `publish-skill` | Publish skills to GitHub | Local: openclaw workspace/skills/ | --- ## Quick health check ```bash # Is OpenClaw gateway up? openclaw health # Is MemPalace working? mempalace status mempalace search "test" # Is LM Studio loaded? curl -s <lm-studio-url>/v1/models | python3 -c "import json,sys; [print(m['id']) for m in json.load(sys.stdin)['data']]" # Can Claude Code reach OpenClaw? openclaw agent --message "ping" --agent main --json | python3 -c "import json,sys; d=json.load(sys.stdin); print('OK:', d['status'])" # Check RAM pressure python3 -c "import psutil; m=psutil.virtual_memory(); print(f'RAM: {m.used/1e9:.1f}/{m.total/1e9:.1f}GB ({m.percent}%)')" ``` --- If this saved you time: [☕ PayPal.me/nerudek](https://www.paypal.me/nerudek) GitHub: [github.com/nerua1](https://github.com/nerua1)


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)