GoClaw is one binary: run with no subcommand it is the gateway, and its subcommands either call the REST API of a running gateway or work on their own (chat, setup, doctor, config). On Linux and macOS it installs itself as a systemd or launchd service.
flowchart TD
subgraph BIN["goclaw (single binary, Cobra subcommand CLI, internal/cli)"]
GW["<b>Gateway Mode (default)</b><br/>HTTP server + channels"]
CLI["<b>CLI Commands</b><br/>Calls REST API of running gateway"]
DIR["<b>Direct Mode (no gateway needed)</b><br/>chat, setup, doctor, config"]
SVC["<b>OS Service & Lock</b><br/>systemd (Linux) / launchd (macOS)<br/>Lock file: ~/.goclaw/gateway.lock (PID + port + time)"]
GW --> SVC
CLI --> SVC
DIR --> SVC
end
OpenClaw has 25+ command groups. GoClaw has one binary with top-level commands and nested subcommands.
| # | Command | Subcommands | Description | Status |
|---|---|---|---|---|
| 3.1 | (default) | — | Start gateway server | Done |
| 3.2 | setup |
— | Interactive setup wizard (provider, API test, channels, summary); --non-interactive writes config.yaml from flags |
Done |
| 3.3 | --debug |
— | Debug mode (structured LLM/tool/gateway logging) | Done |
| 3.4 | status |
— | Query running gateway (GET /api/stats) — provider, model, sessions, uptime, channels |
Done |
| 3.5 | pairing |
approve, list, pending, revoke, link |
Pairing management (reads and writes the pairing files directly; a running gateway sees the change after a restart) | Done |
| 3.6 | config get |
— | Read config value (dot-notation) | Done |
| 3.7 | config set |
— | Write config value (AST-preserving YAML update) | Done |
| 3.8 | config append |
— | Append to config list (e.g. tools.shell.allow) |
Done |
| 3.9 | config remove |
— | Remove from config list | Done |
| 3.10 | doctor |
— | Health checks: config, state/workspace/memory dirs, vault, database, memory schema, integrations (live provider call), gateway, service boot (Linux) | Done |
| 3.11 | message |
[channel] <content> |
Run one agent turn through the running gateway (POST /api/webhook, peer cli, gateway token) and print the reply; nothing is posted to the channel |
Done |
| 3.12 | sessions |
list, inspect |
Session management | Done |
| 3.13 | agents |
list, add, bind, unbind, delete |
Multi-agent CRUD + config save | Done |
| 3.14 | chat |
— | Interactive terminal chat (direct LLM, no gateway, streaming) | Done |
| 3.15 | skills |
list, check, scan, install, add, remove, show (see below) |
Skill management + security | Done |
| 3.16 | tools |
list, exec, bench |
List, execute, and benchmark registered tools | Done |
| 3.17 | service install |
— | Install as OS service (systemd/launchd); --system [--run-as <user>] for a system service run by an unprivileged user |
Done |
| 3.18 | service uninstall |
— | Uninstall OS service | Done |
| 3.19 | service |
start, stop, restart, status |
Control the installed service | Done |
| 3.20 | quickstart |
— | Short setup wizard | Done |
| 3.21 | version |
— | Version, commit and build date | Done |
| 3.22 | config delete |
— | Remove a key, including keys the schema does not know | Done |
| 3.23 | memory |
check, stats, reindex, replay, relearn, revise, revisions, prune, dedupe, forget, clear, clear-user, backfill-metadata, notes, migrate, export, import |
Memory maintenance through the running gateway (/api/memory/*); check and migrate open the database directly |
Done |
| 3.24 | graph |
migrate, reindex, check, stats, cleanup |
Knowledge graph (kg.sqlite) maintenance |
Done |
| 3.25 | db |
export, import, inspect |
.gclaw database snapshots |
Done |
| 3.26 | secret |
gen, set, get, list, delete |
Encrypted vault | Done |
| 3.27 | genpass |
— | Print strong random passwords (aliases gp, password) |
Done |
| 3.28 | gitlab hook |
setup, list, test, remove |
GitLab webhook wizard and helpers | Done |
| 3.29 | teams |
setup, package |
Teams setup wizard and app package (.zip) | Done |
| 3.30 | transcribe |
— | Transcribe an audio or video file | Done |
| 3.31 | sbom |
— | SBOM: summary, CycloneDX, SPDX, JSON | Done |
| 3.32 | update |
— | Download, verify and install a release; restart the service | Done |
| 3.33 | completion |
bash, zsh, fish, powershell |
Shell completion scripts | Done |
The user-facing reference for every command is CLI Reference.
| Subcommand | Description |
|---|---|
list |
List all loaded skills with tags, status, source |
check |
Check skill binary dependencies (pure Go detection) |
check <name> |
Compatibility report for one skill |
scan |
Security scan all skills (prompt-injection, data-exfiltration and dangerous-code rules) |
scan <name> |
Security scan a specific skill |
install <URL> |
Install from URL (HTTP/HTTPS); the response is saved as the SKILL.md |
install github:<ref> |
Install from GitHub (single file from main, or repo clone) |
install <path> |
Install from local path (file or directory) |
install ... --force |
Install even when the compatibility check says FAIL |
add github:<user>/<repo> |
Clone a repository and pick its skills interactively (--force as for install) |
remove <name> |
Remove user-installed skill |
show <name> |
Show skill content + metadata |
Post-install security scan: After every install, skills are automatically scanned. Critical findings = blocked + auto-removed.
| # | Check | Description |
|---|---|---|
| 1 | Config file | <state dir>/config.yaml exists (state dir: GOCLAW_STATE_DIR, default ~/.goclaw) |
| 2 | State directory | ~/.goclaw/ exists |
| 3 | Workspace | ~/.goclaw/workspace/ exists |
| 4 | Memory directory | ~/.goclaw/workspace/memory/ exists |
| 5 | Config and vault | Config loads; the secrets vault opens (with a note when GOCLAW_SECRET_KEY is unset); ${secret:…} references resolved for the checks below |
| 6 | Database | database.path (default ~/.goclaw/gc_state.sqlite) exists or will be created |
| 7 | Memory health | Schema migrations and critical findings, as goclaw memory check reports them |
| 8 | Integrations | doctor.RunSystemChecks: datasources, Zabbix/Uptrace/Grafana per agent, GitLab, SonarQube, MCP servers, enabled channels, SMTP/IMAP, and a live call to the AI provider |
| 9 | Gateway | Running gateway reachable + PID |
| 10 | Service boot | Linux only: an installed service starts at boot (lingering, WantedBy target) |
OpenClaw runs as a background daemon with CLI-to-gateway IPC. GoClaw uses HTTP REST for CLI→Gateway communication.
| # | Feature | OpenClaw | GoClaw | Status |
|---|---|---|---|---|
| 3b.1 | Foreground server | HTTP/WS server | gateway.Claim takes the state directory and listens on its ports before anything starts; httpSrv.Serve on the claimed listener |
Done |
| 3b.2 | Graceful shutdown | SIGINT/SIGTERM | SIGINT/SIGTERM handler | Done |
| 3b.3 | Lock file (PID) | gateway.<hash>.lock with stale detection |
<state dir>/gateway.lock (PID+port+timestamp, stale detection: process alive and /health answers). A second gateway on the same state dir exits with "another GoClaw gateway is already running" |
Done |
| 3b.4 | CLI → Gateway IPC | WebSocket JSON-RPC | HTTP REST (simpler, reuses API routes) | Done |
| 3b.5 | OS service install | launchd / systemd / schtasks | goclaw service install for systemd + launchd |
Done |
| 3b.6 | OS service uninstall | Platform-specific | goclaw service uninstall |
Done |
| 3b.7 | SIGUSR1 restart | Hot restart without downtime | — | TODO |
| 3b.8 | Bind modes | loopback / lan / tailnet / auto / custom | loopback / lan / all / custom IP | Done |
| 3b.9 | Gateway auth | Token/password + challenge handshake | Token auth (X-GoClaw-Token / Bearer) | Done |
| 3b.10 | Rate limiting | AuthRateLimiter |
Per-IP token bucket (configurable req/min) | Done |
| 3b.11 | Remote gateway | OPENCLAW_GATEWAY_URL |
— | TODO |
| 3b.12 | Public ingress | External tunnel/proxy | gateway.ingress (type ngrok or proxy, url, authtoken, allow list, optional dedicated port/bind); the deprecated gateway.ngrok and channels.msteams.ngrok are mapped onto it when gateway.ingress.type is unset |
Done |
flowchart TD
DAEMON["<b>goclaw (daemon — foreground or OS service)</b><br/>• Lock file: ~/.goclaw/gateway.lock (PID + port)<br/>• HTTP server (bind: loopback / lan / all / custom)<br/>• Middleware: rate limit → token auth → router<br/>• SIGINT/SIGTERM → graceful stop<br/>• OS service: systemd (Linux) / launchd (macOS)"]
subgraph REST["Gateway HTTP REST + OpenAI-compat Endpoints"]
R1["<b>goclaw status</b> → GET /api/stats"]
R2["<b>goclaw sessions list</b> → GET /api/sessions"]
R3["<b>goclaw memory …</b> → /api/memory/*"]
R4["<b>goclaw message</b> → POST /api/webhook (agent turn)"]
R5["<b>POST /v1/chat/completions</b> → OpenAI-compatible API"]
R6["<b>GET /health</b> → health probe"]
end
subgraph LOCAL["Direct CLI Operations (no gateway required)"]
L1["<b>goclaw chat</b> → direct LLM chat"]
L2["<b>goclaw agents / skills / tools</b> → local CRUD & inventory"]
L3["<b>goclaw config get / set</b> → AST-preserving YAML"]
L4["<b>goclaw doctor</b> → health checks"]
end
DAEMON <-->|"HTTP REST + OpenAI-compat"| REST
| Aspect | OpenClaw | GoClaw |
|---|---|---|
| CLI style | Command groups (openclaw gateway run) |
Single binary with subcommands (goclaw status) |
| Commands | 25+ command groups | Top-level commands + nested config, memory, graph, db, secret, skills, tools, service, pairing, teams, gitlab groups |
| IPC | WebSocket JSON-RPC | HTTP REST (reuses API routes) |
| Config management | CLI config set/get | get/set/append/remove/delete with AST-preserving YAML |
| Skill management | npm/Clawhub | list/check/scan/install/add/remove/show |
| Install sources | npm | 3 sources: URL, GitHub, local |
| Post-install scan | — | ✅ Auto security scan, critical → blocked |
| Tools CLI | — | goclaw tools list, goclaw tools exec, goclaw tools bench |
| Doctor | openclaw doctor |
goclaw doctor (local files, vault, database, integrations, gateway, service boot) |
| OS service | launchd/systemd/schtasks | systemd + launchd |
| Self-update | openclaw update |
goclaw update (checksum-verified, restarts the service) |
Not implemented: SIGUSR1 hot restart (3b.7) and a remote gateway for the CLI (3b.11; goclaw setup --mode remote has no effect).