clawctl

clawctl — openclaw client wrapper

A kubectl-style wrapper around the openclaw gateway. One binary, no dependencies beyond what's already on your machine, and a strong opinion that gateway interactions should be safe by default, traceable, and secret-redacted at the boundary.

Install

curl -fsSL https://raw.githubusercontent.com/tomstagl/clawctl/main/install/install.sh | bash

The installer detects your OS + architecture, downloads the matching binary from the latest GitHub release, verifies the checksum, and installs to /usr/local/bin/clawctl (configurable via CLAWCTL_INSTALL_DIR).

Quickstart

clawctl init                       # detect platform + print setup snippets; --check to verify config
clawctl health                     # gateway liveness
clawctl msg <agent> "hello"        # one-shot chat with any registered openclaw agent

Setup

Create a local config file that holds all environment-specific values — this file stays on your machine only, never in version control:

mkdir -p ~/.config/clawctl
cat > ~/.config/clawctl/env <<'EOF'
# clawctl configuration — NOT for version control
export CLAWCTL_HOST="http://your-openclaw-host:18789"
export CLAWCTL_SSH_HOST="user@your-openclaw-host"   # only needed for `clawctl cli`
export CLAWCTL_JAEGER_UI="http://your-jaeger-host:16686"  # only needed for `clawctl trace`
EOF

Then source it from ~/.zshrc (or ~/.bash_profile):

echo 'source ~/.config/clawctl/env' >> ~/.zshrc

Run clawctl init at any time to detect your platform and print setup snippets you can paste into the file. Use clawctl init --check to verify the current configuration.

Store the bearer token in Keychain once (the binary reads it from there, never from env):

security add-generic-password \
  -s openclaw-gateway-token \
  -a "$USER" \
  -w "<your-bearer-token>"

On Linux, set CLAWCTL_TOKEN_CMD to any command that prints the token (see docs/auth.md for secret-tool and pass recipes).

Optional knobs — sensible defaults exist:

Variable	Default	Purpose
CLAWCTL_HOST	required	Gateway URL
CLAWCTL_SSH_HOST	unset	SSH target for clawctl cli
CLAWCTL_REMOTE_PATH	~/.local/bin/clawctl-remote	Install path for clawctl-remote on the gateway host; ~ expands on the remote
CLAWCTL_TOKEN_CMD	unset	Shell command that prints the bearer token
CLAWCTL_KEYCHAIN_SERVICE	openclaw-gateway-token	Credential-store entry name (macOS Keychain / Linux secret-tool service)
CLAWCTL_TIMEOUT	60	Per-call timeout (seconds)
CLAWCTL_CACHE_DIR	~/.cache/clawctl	Models cache + redaction audit
CLAWCTL_MODELS_TTL	60	clawctl models cache TTL (seconds)
CLAWCTL_MAX_RESPONSE_BYTES	10485760 (10 MiB)	Max HTTP response body buffered in memory; oversize → exit 22
CLAWCTL_NO_REDACT	0	Set to 1 to bypass redaction (debug only)
CLAWCTL_JAEGER_UI	unset	Used by clawctl trace to print a working UI link

Surface

Command	Purpose
clawctl health	Gateway liveness (no auth)
clawctl models	List registered agents (60s cached)
clawctl msg [-s SESSION] AGENT [TEXT]	One-shot chat; stdin if TEXT omitted
clawctl stream [-s SESSION] AGENT [TEXT]	Same, SSE-buffered + redacted
clawctl raw METHOD PATH [curl-args]	Arbitrary /v1/... call with auth + traceparent
clawctl cli SUBCOMMAND...	Run openclaw … over SSH on the gateway host
clawctl verify KIND ARGS	Claim verification — commit, pr, issue, file
clawctl trace TRACE-ID	Print Jaeger UI link + first 30 spans for a trace
clawctl init [--check]	Print platform setup snippets; verify config with --check

Exit codes: see docs/cli-contract.md.

Use from agents