Advanced Topics

This section covers advanced configuration, deployment, and troubleshooting for GoClaw.

Topics

Deployment

Operations

Security

Supervisor Mode

GoClaw can run as a supervised daemon with automatic restart:

goclaw start

Features:

• Process monitoring — Spawns and monitors gateway subprocess
• Crash recovery — Exponential backoff restart (1s → 5min max)
• State persistence — Saves PID, crash count to supervisor.json
• Output capture — Circular buffer for crash diagnostics

Commands

# Start supervised gateway (daemon)
goclaw start

# Stop supervised gateway
goclaw stop

# View status
goclaw status

Configuration

Supervisor reads from goclaw.json:

{
  "gateway": {
    "pidFile": "goclaw.pid",
    "logFile": "goclaw.log"
  }
}

Debug Logging

Enable verbose logging for troubleshooting:

# Debug level (-d)
./goclaw gateway -d

# Trace level (-t) - very verbose
./goclaw gateway -t

# Via make
make debug

Log Levels

Filtering Logs

# Only errors
./goclaw gateway -d 2>&1 | grep -E "ERRO|error"

# Specific component
./goclaw gateway -d 2>&1 | grep compaction

# Exclude noise
./goclaw gateway -d 2>&1 | grep -v "TRAC"

Request Tracing

Enable request dumps for API debugging:

{
  "llm": {
    "providers": {
      "claude": {
        "driver": "anthropic",
        "dumpOnSuccess": true
      }
    }
  }
}

Request dumps are saved to a temp directory with:

• Full request body
• Response body
• Timing information

Database Management

Location

SQLite database: ~/.goclaw/sessions.db

Inspection

# List tables
sqlite3 ~/.goclaw/sessions.db ".tables"

# Check integrity
sqlite3 ~/.goclaw/sessions.db "PRAGMA integrity_check"

# View session keys
sqlite3 ~/.goclaw/sessions.db "SELECT DISTINCT session_key FROM messages"

Backup

cp ~/.goclaw/sessions.db ~/.goclaw/sessions.db.bak

Recovery

If database is corrupted:

mv ~/.goclaw/sessions.db ~/.goclaw/sessions.db.corrupted
# GoClaw will create fresh database on restart

OpenClaw Compatibility

GoClaw can run alongside OpenClaw with shared resources:

Session Inheritance

{
  "session": {
    "inherit": true,
    "inheritPath": "~/.openclaw/agents/main/sessions",
    "inheritFrom": "main"
  }
}

Session Watcher

When inheritance is enabled, GoClaw monitors the OpenClaw session file for changes and injects new messages in real-time.

Shared Directories

Performance Tuning

Compaction

Aggressive compaction for constrained environments:

{
  "session": {
    "summarization": {
      "compaction": {
        "reserveTokens": 20000,
        "maxMessages": 200,
        "keepPercent": 30
      }
    }
  }
}

Prompt Cache

Reduce disk I/O with longer cache intervals:

{
  "promptCache": {
    "pollInterval": 300
  }
}

Embedding Model

Use faster embedding model for quick searches:

{
  "memory": {
    "query": {
      "minScore": 0.4
    }
  }
}

Extension Points

Custom Tools

Tools are registered via the tool registry at startup. See internal/tools/ for implementation examples.

Custom Channels

Channels implement the channel interface. See internal/telegram/ and internal/http/ for examples.

Skills

Add domain-specific capabilities via skills without code changes. See Skills .

See Also

• Deployment — Production setup
• ACP Sessions — Cursor ACP attachment and steering
• Troubleshooting — Common issues
• Sandbox — Execution isolation
• Architecture — System internals