OpenClaw Configuration

OpenClaw Configuration

Skillful-Alhazen is designed to run as a persistent agent via OpenClaw — a daemon that gives Claude Code always-on connectivity to messaging platforms (Telegram, Discord, etc.), scheduled tasks, and background processing.

This guide covers setting up OpenClaw to work with skillful-alhazen, including remote access to dashboards via Tailscale.

Prerequisites

1. OpenClaw installed (npm install -g openclaw)
2. Tailscale installed and configured (for remote dashboard access)
3. Skillful-alhazen already set up per Getting Started

Installing OpenClaw

npm install -g openclaw

Verify installation:

openclaw --version
openclaw status

Gateway Configuration

The OpenClaw gateway is the always-on daemon that manages sessions, messaging, cron jobs, and heartbeats.

Start the Gateway

openclaw gateway start

Key Configuration

Use openclaw gateway config to set up:

• Channel: Connect to Telegram, Discord, Signal, etc.
• Workspace: Point to your skillful-alhazen workspace directory
• Model: Set your preferred Claude model
• Heartbeat: Configure periodic check-in interval

# View current config
openclaw gateway config get

# Example: set workspace
openclaw gateway config set workspace /path/to/skillful-alhazen

Refer to the OpenClaw docs for the full configuration reference.

Agent Setup

OpenClaw agents are configured under ~/.openclaw/agents/. The key files:

File	Purpose
AGENTS.md	Agent behavior and conventions
SOUL.md	Personality and identity
USER.md	Information about the user
MEMORY.md	Long-term memory (curated)
HEARTBEAT.md	Periodic task checklist
TOOLS.md	Environment-specific notes (devices, SSH hosts, etc.)

These files live in the OpenClaw workspace (~/.openclaw/workspace/) and are injected into every session.

Cron Jobs

OpenClaw supports scheduled tasks via cron jobs. Skillful-alhazen uses these for automated workflows like the job forager.

Example: Nightly Job Forager

The jobhunt skill's forager pipeline runs nightly to discover new job postings:

Schedule: 0 0 * * * (midnight PST)
Type: agentTurn (isolated session)
Task: Run the full forager pipeline — search sources, triage candidates, report relevant finds

Cron jobs can be managed through the OpenClaw gateway or via the agent's cron tool during a session.

Heartbeats vs Cron

Use Case	Mechanism
Batch periodic checks (email, calendar)	Heartbeat
Exact timing ("9 AM every Monday")	Cron
One-shot reminders	Cron (at schedule)
Tasks needing isolation from main session	Cron (isolated session)

Remote Access with Tailscale

Skillful-alhazen runs Docker services (TypeDB, dashboards, hub) bound to 127.0.0.1 for security. To access these remotely (e.g., from your phone or laptop), use Tailscale Serve to proxy local ports over your Tailnet with authentication.

Why Tailscale Serve (Not Port Binding)

Binding ports to 0.0.0.0 exposes services to the entire network without authentication. Tailscale Serve keeps services on localhost and proxies them through your authenticated Tailnet — only your devices can reach them.

Setup

1. Install Tailscale and join your Tailnet:

# macOS: Install from App Store or download from tailscale.com
# Verify connection
tailscale status

2. Enable HTTPS (required for Tailscale Serve):

tailscale cert <your-machine-name>.<tailnet-name>.ts.net

3. Serve the dashboard hub (port 8080):

tailscale serve --https=8080 http://127.0.0.1:8080

4. Serve the job hunt dashboard (port 3001):

tailscale serve --https=3001 http://127.0.0.1:3001

5. Verify from any device on your Tailnet:

https://<your-machine-name>.<tailnet-name>.ts.net:8080/
https://<your-machine-name>.<tailnet-name>.ts.net:3001/

Checking Serve Status

tailscale serve status

Persistence Across Reboots

Tailscale Serve configs persist, but Tailscale itself must be running. To ensure it starts on boot:

• macOS: Add Tailscale.app to System Settings → General → Login Items
• Linux: sudo systemctl enable tailscaled

If dashboards become unreachable after a reboot, check:

# Is Tailscale running?
tailscale status

# If stopped:
tailscale up

# Verify serve config is still there:
tailscale serve status

Docker Compose Port Bindings

The docker-compose.yml intentionally binds to 127.0.0.1:

services:
  hub:
    ports:
      - "127.0.0.1:8080:80"    # Only localhost — Tailscale proxies this
  jobhunt-dashboard:
    ports:
      - "127.0.0.1:3001:3000"  # Only localhost — Tailscale proxies this
  typedb:
    ports:
      - "127.0.0.1:1729:1729"  # Only localhost

Do not change these to 0.0.0.0 — that bypasses Tailscale's authentication layer.

Troubleshooting

Symptom	Cause	Fix
Dashboard returns 404 remotely	Tailscale stopped	tailscale up
tailscale serve fails	Tailscale not running	tailscale up first
Services unreachable after reboot	Tailscale not in Login Items	Add to Login Items
Gateway not responding	Gateway daemon stopped	openclaw gateway start
Cron jobs not firing	Gateway down or job disabled	openclaw gateway status, check job config

Architecture Overview

┌─────────────────────────────────────────────────────┐
│                   Your Devices                       │
│              (phone, laptop, etc.)                    │
└──────────────────────┬──────────────────────────────┘
                       │ Tailscale (encrypted, authenticated)
                       ▼
┌─────────────────────────────────────────────────────┐
│                  Mac Mini / Server                    │
│                                                      │
│  ┌──────────┐  ┌───────────┐  ┌──────────────────┐  │
│  │ OpenClaw │  │ Tailscale │  │ Docker            │  │
│  │ Gateway  │  │  Serve    │  │                   │  │
│  │          │  │           │  │ ┌──────────────┐  │  │
│  │ Telegram │  │ :8080 ──▶─│──│─│ Hub (nginx)  │  │  │
│  │ Cron     │  │ :3001 ──▶─│──│─│ Dashboard    │  │  │
│  │ Sessions │  │           │  │ │ TypeDB :1729 │  │  │
│  └──────────┘  └───────────┘  │ └──────────────┘  │  │
│                               └──────────────────┘  │
└─────────────────────────────────────────────────────┘