GoClaw CLI Skill
Lets Claude invoke the goclaw binary via Bash to interact with a GoClaw Gateway server. Single source of truth = the CLI; this skill teaches Claude the ergonomics.
Conventions (always apply)
- Always append
--output json to every goclaw call. Rely on JSON parsing, not table output.
- Read auth from
~/.goclaw/config.yaml — do NOT accept token via prompt; user must have run goclaw auth login beforehand.
- Destructive ops require user confirm. Any command with
--yes flag or verbs delete, reset, revoke, unpublish, clear, rotate, deny, execute-merge → ask user to confirm before adding --yes.
- Streaming commands are NOT Bash-friendly. Refuse to run:
chat interactive mode, logs tail, auth pair, approvals watch. Suggest polling or user-run-manually alternative.
- Exit code 1 after auth error → suggest
goclaw auth login, do not retry-loop.
- Never hardcode server URL, tenant ID, agent ID, user ID — use placeholders in examples, actual values from user context.
Hero use case — execute shell on server
Tool exec registered as builtin on GoClaw Gateway. Claude invokes via:
goclaw tools invoke exec --param command="ls -la /workspace" --output json
# with working directory:
goclaw tools invoke exec --param command="npm test" --param working_dir="/workspace/app" --output json
Approval flow when server deems command sensitive (package installs, deny-patterns): call hits approvals queue. Handle via references/exec-workflow.md.
Navigation — load relevant reference on demand
Claude: when user's intent matches, Read the listed reference file before constructing commands.
| Intent signal |
Reference |
| exec / run shell / remote command / approvals |
references/exec-workflow.md |
| login / token / profile / tenant switch / credentials / api-keys |
references/auth-and-config.md |
| agent list/get/create/delete, agent files, instances, wake |
references/agents-core.md |
| agent share, link, delegate, regenerate |
references/agents-advanced.md |
| chat with agent, session list/preview/delete |
references/chat-sessions.md |
| health, status, logs, traces, usage, metrics |
references/monitoring-ops.md |
| knowledge graph, entity dedup, memory |
references/knowledge-memory.md |
| teams, members, team tasks, workspace files |
references/teams-collaboration.md |
| channels, contacts, pending messages, writers |
references/channels-messaging.md |
| export / import / storage (workspace files) |
references/data-movement.md |
| providers, skills, built-in tools list/config, packages |
references/providers-skills-tools.md |
| cron, heartbeat, device pairing |
references/automation-scheduling.md |
| MCP servers, grants, requests |
references/mcp-integration.md |
| tenants, system-config, audit activity, TTS |
references/admin-system.md |
| media upload/download |
references/media.md |
| API documentation browsing |
references/docs-api.md |
Compatibility
Tested against goclaw CLI ≥ 0.3.0. Run goclaw version to check. Schema drift caught by check-drift.sh in CI.
Prerequisites
Troubleshooting
- Command returns 401 → token expired, run
goclaw auth login
- Command returns 403 → user lacks role for resource; check
goclaw whoami --output json
- Command hangs → likely streaming op — Claude should refuse, see convention #4
1---2name: goclaw3description: Manage GoClaw AI agent gateway servers from Claude Code. Use this skill when the user mentions "goclaw", "gateway server", "AI agent platform", or wants to execute shell commands remotely on a server, manage AI agents, approve agent actions, inspect chat sessions, or administer multi-tenant AI infrastructure. Wraps the `goclaw` CLI to call REST + WebSocket APIs of GoClaw Gateway.4---56# GoClaw CLI Skill78Lets Claude invoke the `goclaw` binary via Bash to interact with a GoClaw Gateway server. Single source of truth = the CLI; this skill teaches Claude the ergonomics.910## Conventions (always apply)11121. **Always append `--output json`** to every goclaw call. Rely on JSON parsing, not table output.132. **Read auth from `~/.goclaw/config.yaml`** — do NOT accept token via prompt; user must have run `goclaw auth login` beforehand.143. **Destructive ops require user confirm.** Any command with `--yes` flag or verbs `delete`, `reset`, `revoke`, `unpublish`, `clear`, `rotate`, `deny`, `execute-merge` → ask user to confirm *before* adding `--yes`.154. **Streaming commands are NOT Bash-friendly.** Refuse to run: `chat` interactive mode, `logs tail`, `auth pair`, `approvals watch`. Suggest polling or user-run-manually alternative.165. **Exit code 1 after auth error** → suggest `goclaw auth login`, do not retry-loop.176. **Never hardcode** server URL, tenant ID, agent ID, user ID — use placeholders in examples, actual values from user context.1819## Hero use case — execute shell on server2021Tool `exec` registered as builtin on GoClaw Gateway. Claude invokes via:2223```bash24goclaw tools invoke exec --param command="ls -la /workspace" --output json25# with working directory:26goclaw tools invoke exec --param command="npm test" --param working_dir="/workspace/app" --output json27```2829Approval flow when server deems command sensitive (package installs, deny-patterns): call hits `approvals` queue. Handle via `references/exec-workflow.md`.3031## Navigation — load relevant reference on demand3233Claude: when user's intent matches, `Read` the listed reference file before constructing commands.3435| Intent signal | Reference |36|---------------|-----------|37| exec / run shell / remote command / approvals | [references/exec-workflow.md](references/exec-workflow.md) |38| login / token / profile / tenant switch / credentials / api-keys | [references/auth-and-config.md](references/auth-and-config.md) |39| agent list/get/create/delete, agent files, instances, wake | [references/agents-core.md](references/agents-core.md) |40| agent share, link, delegate, regenerate | [references/agents-advanced.md](references/agents-advanced.md) |41| chat with agent, session list/preview/delete | [references/chat-sessions.md](references/chat-sessions.md) |42| health, status, logs, traces, usage, metrics | [references/monitoring-ops.md](references/monitoring-ops.md) |43| knowledge graph, entity dedup, memory | [references/knowledge-memory.md](references/knowledge-memory.md) |44| teams, members, team tasks, workspace files | [references/teams-collaboration.md](references/teams-collaboration.md) |45| channels, contacts, pending messages, writers | [references/channels-messaging.md](references/channels-messaging.md) |46| export / import / storage (workspace files) | [references/data-movement.md](references/data-movement.md) |47| providers, skills, built-in tools list/config, packages | [references/providers-skills-tools.md](references/providers-skills-tools.md) |48| cron, heartbeat, device pairing | [references/automation-scheduling.md](references/automation-scheduling.md) |49| MCP servers, grants, requests | [references/mcp-integration.md](references/mcp-integration.md) |50| tenants, system-config, audit activity, TTS | [references/admin-system.md](references/admin-system.md) |51| media upload/download | [references/media.md](references/media.md) |52| API documentation browsing | [references/docs-api.md](references/docs-api.md) |5354## Compatibility5556Tested against `goclaw` CLI ≥ 0.3.0. Run `goclaw version` to check. Schema drift caught by `check-drift.sh` in CI.5758## Prerequisites5960- `goclaw` binary in PATH (download from https://github.com/nextlevelbuilder/goclaw-cli/releases)61- Authenticated: `goclaw auth login` or paired via `goclaw auth pair`62- Permissions granted in `~/.claude/settings.json` (see install.sh)6364## Troubleshooting6566- Command returns 401 → token expired, run `goclaw auth login`67- Command returns 403 → user lacks role for resource; check `goclaw whoami --output json`68- Command hangs → likely streaming op — Claude should refuse, see convention #4
NextLevelBuilder