🏠 Home ← Docs Index
Open Beta 📖 Interactive Reader Raw .md llms.txt

Minimal Dependency Strategy

GoClaw is designed to run as a single binary with no runtime to install — from a full Linux workstation to a headless Raspberry Pi.

The Linux release binaries are built with cgo (SQLite and tree-sitter are C libraries) and link glibc dynamically: they need glibc 2.34 or later (Ubuntu 22.04, Debian 12 / Raspberry Pi OS Bookworm, RHEL 9 and up). On a musl system such as Alpine, run the Docker image, which is built for it.

Design Philosophy

flowchart TD
    subgraph BIN["goclaw binary"]
        direction LR
        LLM["<b>LLM API</b><br/>net/http"]
        TOOLS["<b>Tools</b><br/>pure Go"]
        SKILLS["<b>Skills System</b><br/>auto-detect deps"]
        MEM["<b>Memory</b><br/>SQLite"]
        SESS["<b>Sessions</b><br/>SQLite"]
        HOOKS["<b>Hooks + Plugins</b><br/>Go interfaces"]
        CACHE["<b>Caching</b><br/>SQLite"]
        CFG["<b>Config</b><br/>YAML"]
        GW["<b>Gateway / Auth</b><br/>net/http mux"]
    end

    BIN --> BUILD["<b>go build (cgo)</b> → single binary"]
    BUILD --> DEPLOY["<b>scp to device → run</b>"]

Why?

Problem (OpenClaw) Solution (GoClaw)
Node.js 22+ runtime required Go compiles to native binary
npm install pulls 500+ packages Zero runtime dependencies
200MB+ disk footprint One binary, about 110–155 MB depending on the platform
RAM: 200-500MB idle One native process, no language runtime to load
curl, jq, etc. expected by tools All built-in as Go tools
Breaks on minimal/embedded OS Runs on glibc 2.34+ Linux, macOS and Windows; Docker image for musl systems

Target Environments

Environment CPU RAM OS Status
Linux workstation x86_64 4GB+ Ubuntu/Arch/Fedora Fully supported
macOS arm64/x86 4GB+ macOS 13+ Fully supported
Windows x86_64 4GB+ Windows 10+ Fully supported
Raspberry Pi 4/5 arm64 / armv7 2GB+ Raspberry Pi OS Lite (Bookworm or later) Target (minimal)
Raspberry Pi Zero 2W arm64 / armv7 512MB Raspberry Pi OS Lite (Bookworm or later) Target (ultra-minimal)
Docker (Alpine) any 256MB+ Alpine Linux Fully supported
Cloud VM (cheap) any 512MB+ Linux with glibc 2.34+ Fully supported
NAS (Synology/QNAP) arm64/x86 1GB+ DSM/QTS Target

Release binaries are published for linux-amd64, linux-arm64, linux-armv7, darwin-arm64, darwin-amd64 and windows-amd64. There is no MIPS build, and an OpenWrt router (musl, no bash) cannot run the release binaries.

Tool Dependency Matrix

Pure Go (zero external dependencies)

These tools work with just the GoClaw binary:

Tool Go Library External Binary Raspberry Pi
file_read os None Yes
file_write os None Yes
file_edit os None Yes
http_request net/http None Yes
web_fetch net/http None Yes
web_search net/http (API) None Yes
calc go/ast None Yes
datetime time None Yes
text_utils crypto, encoding None Yes
memory_get SQLite (GORM) None Yes
memory_write SQLite (GORM) None Yes
memory_search SQLite (GORM) + embeddings API None Yes
memory_consolidate SQLite (GORM) None Yes
image os + net/http None Yes
pdf built-in parser (uses pdftotext instead when it is installed) None Yes
sessions_list SQLite None Yes
sessions_history SQLite None Yes
db_query Go SQL drivers None Yes
mongo_query Go driver None Yes
cron robfig/cron None Yes
message net/http None Yes

The archive (archive_search, archive_get) and wiki (wiki_read, wiki_write) tools work the same way, on the database.

OS-Level (usually present)

Tool External Binary Fallback Notes
shell_exec bash (PowerShell on Windows) None: there is no sh fallback Present on most Linux distributions and macOS. A busybox-only system (Alpine without bash, OpenWrt) needs bash installed; the Docker image includes it
process OS process API Always present Core OS component

Optional Enhancement (graceful degradation)

Tool External Binary Without It Severity
git git Returns "git binary not found on this system" Low — install with apt install git
browser Chrome/Chromium Returns "failed to start browser: …" Low — niche use case
pdf pdftotext (poppler-utils) Uses the built-in parser Low — layout may be poorer
analyze_pcap tshark, else tcpdump With only tcpdump, the summary view only; with neither, returns install instructions Low
run_code_linter golangci-lint, ruff, dart Returns " not found" Low — developer hosts only
run_sast_scanner gosec, bandit Returns " not found" Low — developer hosts only
clipboard pbcopy/pbpaste (macOS), xclip (Linux), PowerShell (Windows) Returns the command's error Low — desktop hosts only

Skill Auto-Detection

Skills with bins in frontmatter are checked when skills are loaded; a skill is available when at least one of its listed binaries is on the PATH. Among the built-in skills only github (gh), tmux (tmux) and gh-issues (gh, git) list any. On a host without gh and tmux:

$ goclaw skills check

Skill Dependency Check:

  [ok] git                  (no external deps — pure Go)
  [ok] web-search           (no external deps — pure Go)
  …
  [--] github               (missing: gh)
  [--] tmux                 (missing: tmux)
  [ok] weather              (no external deps — pure Go)
  [ok] gh-issues            (found: git)
  …
  [ok] mcp                  (no external deps — pure Go)
  …

Summary: <n> ready, 2 unavailable, <n> pure Go (no deps)

Unavailable skills are auto-skipped at runtime.
Install missing binaries to enable them.

Unavailable skills are silently excluded from the system prompt. The LLM never receives instructions for tools that don't exist — no confusion, no wasted tokens.

Build Targets

GoClaw needs cgo: mattn/go-sqlite3 and go-tree-sitter are C code, and a CGO_ENABLED=0 build does not compile. Cross-compiling therefore needs a C cross-compiler for the target, given as CC. The release workflow builds the Linux and Windows binaries this way on Ubuntu:

# Native build (the host's own OS and architecture)
CGO_ENABLED=1 CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" go build -o goclaw ./cmd/gateway/

# Linux ARM64 (64-bit Raspberry Pi OS), from Debian/Ubuntu x86_64
sudo apt-get install gcc-aarch64-linux-gnu
CGO_ENABLED=1 CC=aarch64-linux-gnu-gcc CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" \
  GOOS=linux GOARCH=arm64 go build -o goclaw ./cmd/gateway/

# Linux ARMv7 (32-bit Raspberry Pi OS)
sudo apt-get install gcc-arm-linux-gnueabihf
CGO_ENABLED=1 CC=arm-linux-gnueabihf-gcc CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" \
  GOOS=linux GOARCH=arm GOARM=7 go build -o goclaw ./cmd/gateway/

# Windows x86_64
sudo apt-get install mingw-w64
CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" \
  GOOS=windows GOARCH=amd64 go build -o goclaw.exe ./cmd/gateway/

# macOS: build on a Mac (the releases are built natively on macOS runners)
CGO_ENABLED=1 CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" GOARCH=arm64 go build -o goclaw ./cmd/gateway/

# Alpine Linux (musl): build the Docker image, which compiles inside golang:alpine
docker build -t goclaw .

A binary links the glibc of the machine that built it, so build on a system at least as old as the oldest one it has to run on.

Raspberry Pi Quick Start

Use a release binary rather than building one: goclaw-linux-arm64 for 64-bit Raspberry Pi OS, goclaw-linux-armv7 for 32-bit. The install script picks the right one, checks it against the release's checksums.json and installs it:

# On the Pi (Raspberry Pi OS Bookworm or later)
curl -fsSL https://goclaw.ulab.mn/install.sh | sh
goclaw setup             # interactive setup
goclaw                   # start gateway

# Optional: install as service
goclaw service install

To use a binary you built yourself (see Build Targets), copy it over with scp goclaw pi@raspberrypi:~/ and run it from there.

Requirements: Network connection (for LLM API calls). That's it.

Comparison with OpenClaw

Aspect OpenClaw GoClaw
Runtime Node.js 22+ None (native binary)
Install npm i -g openclaw (500+ deps) Copy single binary
Disk ~200MB ~110–155 MB (one binary)
Process Node.js runtime One native process
Startup 2-5 seconds <1 second
curl needed By many skills Never (http_request)
Python needed Optional tools Only for optional tools (bandit)
Minimum OS Full Linux/macOS Linux with glibc 2.34+ (or Docker), macOS, Windows; bash for shell_exec
Cross-compile N/A (needs Node per arch) cgo with a C cross-compiler (see Build Targets)

Rules for Contributors

  1. Never add an external binary dependency to a core tool. If you need HTTP, use net/http. If you need JSON, use encoding/json. If you need crypto, use crypto/.

  2. Skills can reference external binaries (via bins field) — these are auto-detected and gracefully skipped if not present.

  3. Tools must degrade gracefully when optional binaries are missing. Return a clear error message suggesting install, don't crash.

  4. Prefer Go standard library over third-party packages. Only use third-party for complex domains (SQL drivers, WebSocket, Discord API).

  5. Keep binary size small. Avoid importing large packages for minor features.

  6. Test on minimal environments. The CI should include a Raspberry Pi-like build target (linux/arm64, no extras).