services/openclaw/overview.md

Table of Contents

OpenClaw / Clawdbot Usage Guide

Personal AI assistant (Max) running on OpenClaw framework. This folder covers setup, configuration, and usage patterns. See sibling files for proposed agents and workspaces, CLI/skills, MCP/browser, integrations, troubleshooting, and meeting plugins.

šŸŒ Web Interface

Access the Control UI / webchat at: http://localhost:18789 (the Gateway port) ā€” remotely at https://max.dph.am

šŸ”Œ Connected Channels

  • Telegram: connected ā€” @dpham_clawd_bot, Dominick Pham (id: 1662354361)
  • Webchat / Control UI: http://localhost:18789 (remote: https://max.dph.am)
  • WhatsApp: enabled (as of 2026-10-12), Max's own number (Google Voice). Group "Phamily" is bound to the family-planner agent with requireMention: true; see troubleshooting.md "Group bot answers everything".

Current Status

  • Version: 2026.9.5
  • Default Model: GPT-5.6 Terra (openai/gpt-5.6-terra) ā€” the configured default
  • Session model: DeepSeek V4 Flash (deepseek/deepseek-v4-flash) ā€” what dashboard/webchat sessions run; 1,000,000-token context
  • Previous default: Anthropic Claude Sonnet 4.5 ā†’ DeepSeek Chat

šŸ¤– Model Providers

DeepSeek (current default)

  • Added May 2026 via OpenAI-compatible completions API
  • Base URL: https://api.deepseek.com
  • Models:
    • deepseek/deepseek-v4-flash ā€” default, 1M ctx, w/ reasoning ($0.14/M in, $0.28/M out)
    • deepseek/deepseek-v4-pro ā€” 1M ctx, w/ reasoning ($1.74/M in, $3.48/M out)
    • deepseek/deepseek-chat ā€” 128k ctx, legacy ($0.28/M in, $0.42/M out)
    • deepseek/deepseek-reasoner ā€” 128k ctx, legacy R1 ($0.28/M in, $0.42/M out)
  • API key: sk-d5cā€¦d24f

Local Ollama

  • Windows host Ollama is reachable on the LAN at http://192.168.1.153:11434; Mac 127.0.0.1:11434 does not listen (checked 2026-09-29).
  • HTTPS endpoint: https://ollama.dph.am (public DNS 108.56.68.112) proxies from Mac nginx to the Windows host. nginx requires an exact Authorization: Bearer <key> header on all proxied paths and strips it before forwarding to Ollama; the key lives in /opt/homebrew/etc/nginx/sites-enabled/ollama.dph.am.conf (not duplicated in notes). After the privileged nginx reload on 2026-09-29, /api/tags returned 401 with no or incorrect key, and 200 with the configured key; qwen3:8b appeared in the authorized model list. The public proxy was unauthenticated before this change.
  • Example API call: curl -H 'Authorization: Bearer <key-from-nginx-config>' https://ollama.dph.am/api/tags. The same authentication applies to generation routes such as /api/generate.
  • Available models checked 2026-09-29: qwen3:8b, qwen3-coder:30b, nqduc/mixsura:mixsura-q2_K. Use qwen3:8b for faster everyday tasks; a benign generation over LAN succeeded in 13.75 seconds, possibly including a cold load.
  • qwen3:8b can think. For simple organizing tasks, put /no_think in the prompt or a system message such as Answer directly, no thinking. to encourage faster, terser responses. When the client supports Ollama's think parameter, think: false is a more explicit way to suppress thinking. Prompt wording alone is not a guaranteed control.
  • OpenClaw's models.providers.ollama still points to http://localhost:11434 and registers only the absent qwen3.5:35b-a3b-coding-nvfp4 model with OpenAI-compatible API mode. OpenClaw is not currently configured to use the working Windows model.
  • For sensitive local-only work, use the LAN endpoint rather than the public nginx URL, register the actual model, and verify the runtime's provider and fallback policy before passing secrets. The nginx bearer check does not protect direct access to Windows port 11434; the short demonstration key should not be treated as strong protection against guessing. A local Ollama host does not by itself make a cloud-mediated agent conversation private.

OpenAI ChatGPT OAuth and Talk

  • OpenClaw has a managed OpenAI ChatGPT OAuth profile; OPENAI_API_KEY is not set in the Gateway environment.
  • Android Talk is configured with the OpenAI GPT-Live model gpt-realtime-2.1 (currently using the alloy speaker voice).
  • GPT-Live is OpenClaw's supported subscription-backed realtime route and can use ChatGPT OAuth. It is separate from general OpenAI Platform Realtime API access.
  • A Platform API key is required for OpenAI GA Realtime and unlisted realtime routes. GPT-Live instead follows the ChatGPT subscription's availability and limits.

šŸ“‚ File Structure

~/.openclaw/
ā”œā”€ā”€ openclaw.json          # Main config
ā”œā”€ā”€ workspace/             # Working directory
ā”‚   ā”œā”€ā”€ AGENTS.md          # Agent behavior guide
ā”‚   ā”œā”€ā”€ SOUL.md            # Personality/vibe
ā”‚   ā”œā”€ā”€ USER.md            # User info
ā”‚   ā”œā”€ā”€ IDENTITY.md        # Agent identity
ā”‚   ā”œā”€ā”€ TOOLS.md           # Local tool notes
ā”‚   ā”œā”€ā”€ MEMORY.md          # Long-term memory
ā”‚   ā”œā”€ā”€ HEARTBEAT.md       # Periodic task checklist
ā”‚   ā””ā”€ā”€ memory/            # Daily logs (YYYY-MM-DD.md)
ā””ā”€ā”€ skills/                # Custom skills (if any)

ā° Cron Jobs

Scheduled work runs through OpenClaw's own scheduler (Automations), not the system crontab ā€” crontab -l is empty for dominick. Inspect via the Control UI ā†’ Automations page (or the automations tool).

Currently registered:

  • Heartbeat (main) ā€” every 30 min (heartbeat:main)
  • Daily exec health guard ā€” daily 9:00 AM ET; probes the exec tool and DMs Telegram only if it breaks

The previously-documented 6:30 AM Morning Briefing (weather + BBC + PRs ā†’ Telegram) is no longer registered.

šŸ¦€ Allowed Origins

Control UI accessible from:

šŸ”‘ Gateway Auth

Auth mode: trusted-proxy ā€” delegates auth to nginx reverse proxy

  • bind: "lan" (listens on all interfaces 0.0.0.0:18789)
  • trustedProxies: ["127.0.0.1", "::1"] ā€” only a loopback proxy may supply identity headers
  • trustedProxy.userHeader: "X-Forwarded-User", allowUsers: ["dominick"], allowLoopback: true
  • port: 18789
  • nginx stamps X-Forwarded-User: dominick ā€” gateway trusts it

Token (fallback for direct LAN access):

2e7b62da9967d3cec56b037fe6f55f7280e41883239d7c214d4956312483ea12

Usage:

  • Web UI via nginx (https://max.dph.am): Seamless ā€” nginx auth + header = auto-authed
  • Direct web UI (http://192.168.1.189:18789): Paste token into login prompt
  • Local CLI (openclaw cron list): āŒ Does NOT work.
    • trusted-proxy mode rejects loopback connections before considering password fallback
    • Cron jobs (Daily Briefing) run via OpenClaw's internal scheduler, not the CLI ā€” they are unaffected
    • To run CLI commands, use nix shell with the token or switch to token auth mode

Nginx proxy (192.168.1.185): stamps X-Forwarded-User header from auth_request.

šŸ”— Resources