ghostnet-openclaw/AGENT_INSTRUCTIONS.md

Stand: 01.06.2026

📋 Handover & Context Prompt for the Next AI Agent

Context: We are developing a fully local, containerized AI agent workspace called ghostnet-openclaw on CachyOS (Arch Linux). The stack runs entirely inside unprivileged, rootless Podman containers using a modular, multi-vendor GPU setup managed via podman-compose (the native Python parser). Current Architecture Stack:

1. LLM Engine (ollama): Running on the official ollama/ollama:rocm base image (built via custom Containerfile and an advanced entrypoint.sh boot-script that auto-polls and pulls models defined in MODEL_LIST). It features successful full AMD ROCm GPU Passthrough (Navi 31) with privileged: true and explicit host mapping for /dev/dri, /dev/kfd, and system render groups (44, 109).
2. Core Agent (openclaw-agent): Running OpenClaw v2026.5.28 in local gateway mode with password authentication. It utilizes userns_mode: "keep-id" to synchronize config file edits with the host alongside :Z,U volume flags to allow rootless Node.js writing to local host workspaces without permission degradation.
3. Network Tunnel Sidecar (openclaw-ollama-bridge): Running an offline-ready alpine/socat:latest image mapping directly into the network namespace of the agent (network_mode: "service:agent"). This tunnels local 127.0.0.1:11434 calls directly to ollama:11434 inside the closed bridge, bypassing a strict OpenClaw TUI bug where the embedded chat utility ignores global container environment variables.

Current Repository State:

• Fully dynamic variables outsourced to a root .env file (supporting SHM_SIZE, MODEL_LIST, OPENCLAW_PASSWORD, DNS servers, and absolute host system paths).
• Split monolithic configurations for various GPU vendors ready to go (compose.amd.yaml, compose.nvidia.yaml, compose.intel.yaml).
• Successfully tested and running gemma4:e4b at 100% GPU (VRAM) streaming tokens fluidly inside the native chat terminal without system freezes or context window pollution.
• Clean operational cycle verified: podman-compose -f compose.amd.yaml up -d --build runs without faults, and podman exec -it openclaw-agent openclaw chat opens the TUI flawlessly.

Next Task / Where to Continue: The core infrastructure is now solid, secure, and fully GPU-accelerated. The user wants to expand the project from here. Please analyze this setup and offer actionable next steps, such as:

1. Integrating external search indexers (like a local SearXNG service into the networks block).
2. Setting up explicit messenger interfaces or multi-account policies within the openclaw.json channels structure.
3. Building automated helper utilities (like a start.sh wrapper script to let users dynamically choose their vendor profile upon booting).

Stand: 03.06.2026

📋 Handover & Context Prompt for the Next AI Agent

Context: Wir entwickeln eine lokale, containerisierte AI-Workspace-Infrastruktur namens ghostnet-openclaw auf CachyOS. Der Stack nutzt unprivilegierte Podman-Container und eine Multi-Vendor GPU-Strategie.

Current Architecture Stack:

1. LLM Engine (ollama): Läuft auf ollama/ollama:rocm. Voller GPU-Passthrough für AMD Radeon RX 7900 XTX (Navi 31). Ein Entrypoint-Script automatisiert das Pulling der Modelle via MODEL_LIST.
2. Core Agent (openclaw-agent): OpenClaw v2026.5.28 im Local Gateway Mode. Nutzt keep-id und :Z,U für persistente Host-Workspaces ohne Permission-Issues.
3. Socat Bridge: Tunnelt 127.0.0.1:11434 (Agent) zu ollama:11434 (Engine), um den TUI-Loopback-Bug zu umgehen.
4. MCP Infrastructure (The Router): Ein dedizierter ghostnet-router (Python/FastAPI) dient als zentrales Tool-Gateway. Er integriert Skills via Model Context Protocol (MCP).
5. Search Skill: Ein tool-searchfetch Container (Bridge), der über den Router Suchanfragen an einen lokalen searxng Dienst delegiert.

Current Repository State:

• Networking: Alle Services kommunizieren über ein isoliertes Bridge-Netzwerk. DNS-Auflösung für externe Registeries (Ollama) muss im Podman-Netzwerk stabilisiert werden.
• Stability: Die maintain_connection-Logik im Router wurde erfolgreich implementiert; der CancelledError bei SSE-Handshakes ist behoben.
• Verification: End-to-End Test (Client -> Router -> Search-Bridge -> SearXNG) war erfolgreich. Tools wie searxng_web_search werden korrekt propagiert.

Next Tasks / Where to Continue:

1. OpenClaw Integration: Die openclaw.json muss so konfiguriert werden, dass der Agent den ghostnet-router (SSE-Endpunkt) als primäre Tool-Quelle nutzt.
2. Modell-Management: DNS-Problematik in der Ollama-Container-Registry beheben (Registry-Auflösung schlägt aktuell fehl).
3. Skill Expansion: Entwicklung weiterer MCP-Bridges (z.B. für lokales Filesystem-Management oder Datenbank-Abfragen), die einfach am Router "angepluggt" werden können.
4. UX-Automation: Ein ghostnet.sh Wrapper, der die Vendor-Erkennung automatisiert und den Stack konsistent hochfährt.

Stand: 17.06.2026

📋 Handover & Context Prompt for the Next AI Agent

Context: Das Repo hat inzwischen mehrere betriebliche Verbesserungen erhalten, die nicht nur die Laufzeit des Stacks, sondern auch Modellprofilierung und Benchmarking betreffen. OpenClaw laeuft weiterhin containerisiert gegen den lokalen Ollama-Stack und den MCP-Router, aber Konfiguration und Benchmark-Ausgaben sind jetzt deutlich sauberer organisiert.

Current Architecture & Operational Notes:

1. Default-Modellsteuerung: agents.defaults.model in openclaw/config/openclaw.json nutzt ${OPENCLAW_DEFAULT_MODEL}. OpenClaw expandiert ${VAR} direkt in Config-Strings zur Laufzeit. Compose setzt deshalb einen Fallback, damit fehlende Variablen den Config-Load nicht brechen.
2. Default-Modellprofil: Das generelle OpenClaw-Defaultprofil ist jetzt ollama/qwen3-general. Das bestehende qwen3-coding-Profil bleibt fuer codinglastige Workflows erhalten.
3. Custom-Modelfiles: Ollama baut alle Dateien unter ollama/modelfiles/*.modelfile automatisch beim Containerstart; der Modellname entspricht jeweils dem Dateinamen ohne Endung.
4. Benchmark-Artefakte: Laufzeitdaten liegen unter .cache/benchmarks/existing-suite/runs/$RUN_ID, waehrend kuratierte Ergebnisse unter docs/benchmarks/existing-suite/$RUN_ID landen.
5. Benchmark-Reports: Per-Model werden report.html und RESULTS.md erzeugt, fuer Suites zusaetzlich SUITE_COMPARISON.html. Die Erzeugung laeuft ueber scripts/lib/report-generator.sh.

Benchmarking State:

• scripts/benchmark-stack.sh und scripts/benchmark-model-suite.sh verwenden jetzt 600s Timeout fuer robustere lokale Modelllaeufe.
• scripts/benchmark-codeneedle-suite.sh bleibt bei 600s und dient als separater Recall-Benchmark gegen denselben Ollama-Endpunkt.
• Fuer stabile Vergleichslaeufe ist die Ollama-Konfiguration auf OLLAMA_KEEP_ALIVE=-1, OLLAMA_KV_CACHE_TYPE=q8_0, OLLAMA_MAX_LOADED_MODELS=1, OLLAMA_NUM_PARALLEL=1 und SHM_SIZE=16gb ausgerichtet.
• Die Benchmark-Skripte trennen jetzt konsequent zwischen Temp-Artefakten und finaler Ergebnisdoku, damit docs/ nicht mehr mit Rohlogs zugemuellt wird.

Current Repository State:

• Model Routing: OpenClaw-Defaultmodell ist per .env und Compose ueberschreibbar, ohne JSON manuell anzupassen.
• Profiles: qwen3-general ist das allgemeine Defaultprofil fuer Chats; qwen3-coding, qwen25-coding und deepseek-coding bleiben spezialisierte Profile.
• Benchmark Presentation: Benchmark-Ergebnisse stehen jetzt als HTML-Dashboard, Markdown-Lab-Notiz und Suite-Vergleich bereit.
• Operational Validation: Compose-Render und OpenClaw-Config-Expansion fuer OPENCLAW_DEFAULT_MODEL wurden direkt gegen das Upstream-Image verifiziert.

Next Tasks / Where to Continue:

1. DNS/Ollama Registry: Die externe Modellauflosung fuer Registry-Pulls im Containernetz weiter haerten.
2. Additional Profiles: Weitere nicht-codinglastige oder domänenspezifische Modelfiles auf Basis bestehender Profile ergänzen.
3. Benchmark Evolution: Adaptive Timeouts, Warm-up-Runs und historische Vergleichsreports sind sinnvolle naechste Ausbaustufen.
4. OpenClaw Tooling: Weitere MCP-Bridges und agentenspezifische Tool-Profile sauber in die bestehende Router-Struktur integrieren.