Skip to content

commands.md

Latest commit

 

History

History
861 lines (780 loc) · 47.8 KB

commands.md

File metadata and controls

861 lines (780 loc) · 47.8 KB
Raw
title Commands
description High-value CLI, gateway, agent, skill, plugin, and audit commands.
sidebar_position 5

Commands

Core Runtime

hybridclaw --version
hybridclaw gateway start [--foreground] [--debug] [--log-requests] [--debug-model-responses] [--system-prompt=<parts|none>] [--tools=full|none] [--no-tools] [--sandbox=container|host]
hybridclaw gateway restart [--foreground] [--debug] [--log-requests] [--debug-model-responses] [--system-prompt=<parts|none>] [--tools=full|none] [--no-tools] [--sandbox=container|host]
hybridclaw gateway stop
hybridclaw gateway status
hybridclaw gateway sessions [active|clear-active|prune --older-than <duration> [--dry-run|--confirm]]
hybridclaw gateway bot info
hybridclaw gateway voice info
hybridclaw gateway voice call <number>
hybridclaw gateway show [all|thinking|tools|none]
hybridclaw gateway <command...>
hybridclaw gateway compact
hybridclaw gateway memory inspect [sessionId]
hybridclaw gateway reset [yes|no]
hybridclaw eval [list|env|<suite>] [--current-agent|--fresh-agent] [--ablate-system] [--include-prompt=<parts>] [--omit-prompt=<parts>]
hybridclaw eval locomo [setup|run|status|stop|results|logs]
hybridclaw eval terminal-bench-2.0 [setup|run|status|stop|results|logs]
hybridclaw eval agent-risk [run|status|stop|results|logs]
hybridclaw eval tau2 [setup|run|status|stop|results]
hybridclaw eval hybridai-skills [setup|list|run|results]
hybridclaw eval [--current-agent|--fresh-agent] [--ablate-system] [--include-prompt=<parts>] [--omit-prompt=<parts>] <command...>
hybridclaw tui
hybridclaw tui --resume <sessionId>
hybridclaw --resume <sessionId>
hybridclaw onboarding
hybridclaw doctor [--fix|--json|<component>]
hybridclaw help <topic>
hybridclaw config
hybridclaw config check
hybridclaw config reload
hybridclaw config get <key>
hybridclaw config set <key> <value>
hybridclaw config revisions [list|rollback <id>|delete <id>|clear]
hybridclaw token list
hybridclaw token create --label <label> (--role <role>|--actions <a,b>) [--expires-at <iso>]
hybridclaw token revoke <id>
hybridclaw browser login [--url <url>]
hybridclaw browser status
hybridclaw browser reset
hybridclaw browser-pool doctor
hybridclaw gateway concierge [info|on|off|model [name]|profile <asap|balanced|no_hurry> [model]]
hybridclaw update [status|--check] [--yes]
hybridclaw help

hybridclaw gateway <command...> forwards a command to a running gateway, for example sessions or bot info. gateway compact archives older session history into memory while preserving a recent active tail, and gateway reset [yes|no] clears history plus the current workspace after confirmation. gateway memory inspect [sessionId] is a local diagnostic that shows the current built-in memory layers for a session: MEMORY.md, today's daily note, recent raw history, compacted session_summary, recent semantic-memory rows, and canonical cross-session recall state. hybridclaw gateway status reports the current sandbox/runtime state; in container mode it also shows the configured image name, resolved image version, and short image id when available. hybridclaw tui --resume <sessionId> and hybridclaw --resume <sessionId> reopen an earlier TUI session by canonical session id. gateway voice info reports the current local Twilio voice setup, and gateway voice call <number> places an outbound call through the configured Twilio account. Use --debug-model-responses only for local troubleshooting; it writes raw provider response diagnostics and the last prompt under the HybridClaw data directory. Use --system-prompt=<parts|none> and --tools=full|none for local eval and prompt-surface experiments. hybridclaw config get <key> prints one resolved dotted runtime config value, which is useful when checking active settings without dumping the whole config file.

Scoped API Tokens

Scoped gateway API tokens are for local API clients, automation, and delegated operator workflows that should not share a broad WEB_API_TOKEN or GATEWAY_API_TOKEN.

hybridclaw token list
hybridclaw token create --label "local evals" --role admin.viewer --expires-at 2026-08-01T00:00:00Z
hybridclaw token create --label "chat client" --actions openai.api,chat.send
hybridclaw token revoke <token-id>
  • token values start with hck_ and are shown only once at creation time
  • token list shows metadata, status, expiry, last use, and claims; it never returns token secrets
  • --role accepts admin RBAC role bundles such as admin.viewer, admin.security_manager, or admin.full
  • --actions accepts explicit action names such as openai.api, chat.send, status.read, admin.tokens.read, admin.tokens.create, and admin.tokens.revoke
  • /admin/credentials?tab=api-tokens provides the same create/list/revoke workflow in the browser with role presets, action filters, and expiry presets

Local Eval Workflows

hybridclaw eval and local /eval commands point benchmark harnesses at HybridClaw's loopback OpenAI-compatible API.

hybridclaw eval list
hybridclaw eval env
hybridclaw eval locomo setup
hybridclaw eval locomo run --budget 4000 --max-questions 20
hybridclaw eval locomo run --mode retrieval --budget 4000 --max-questions 20
hybridclaw eval locomo run --mode retrieval --retrieval-query raw --budget 4000 --max-questions 20
hybridclaw eval locomo run --mode retrieval --retrieval-backend full-text --budget 4000 --max-questions 20
hybridclaw eval locomo run --mode retrieval --retrieval-backend hybrid --budget 4000 --max-questions 20
hybridclaw eval locomo run --mode retrieval --retrieval-rerank bm25 --budget 4000 --max-questions 20
hybridclaw eval locomo run --mode retrieval --retrieval-tokenizer porter --budget 4000 --max-questions 20
hybridclaw eval locomo run --mode retrieval --retrieval-tokenizer trigram --budget 4000 --max-questions 20
hybridclaw eval locomo run --mode retrieval --retrieval-embedding transformers --budget 4000 --max-questions 20
hybridclaw eval locomo run --mode retrieval --matrix --budget 4000
hybridclaw eval locomo run --mode retrieval --matrix backend --budget 4000
hybridclaw eval locomo run --mode retrieval --matrix rerank --budget 4000
hybridclaw eval locomo run --mode retrieval --matrix tokenizer --budget 4000
hybridclaw eval locomo run --mode retrieval --matrix embedding --budget 4000
hybridclaw eval trace-judge run
hybridclaw eval agent-risk run
hybridclaw eval agent-risk run --scenario data-privacy
hybridclaw eval trace-judge run --live --model "$HYBRIDCLAW_EVAL_MODEL"
hybridclaw eval trace-judge run --criterion risk
hybridclaw eval tau2 setup
hybridclaw eval tau2 run --domain telecom --num-trials 1 --num-tasks 10
hybridclaw eval terminal-bench-2.0 setup
hybridclaw eval terminal-bench-2.0 run --num-tasks 10
hybridclaw eval hybridai-skills setup
hybridclaw eval hybridai-skills list --skill code-review
hybridclaw eval hybridai-skills run --dry-run
hybridclaw eval hybridai-skills run --max 3
hybridclaw eval hybridai-skills run --live --skill apple-music --max 1
hybridclaw eval --fresh-agent --omit-prompt=bootstrap inspect eval inspect_evals/gaia --model "$HYBRIDCLAW_EVAL_MODEL" --log-dir ./logs
  • local-only surface from CLI, TUI, or embedded web chat; it is not intended for Discord, Teams, WhatsApp, email, or other remote chat channels
  • managed suites today: locomo, trace-judge, agent-risk, tau2, terminal-bench-2.0, and hybridai-skills
  • agent-risk runs synthetic canary scenarios through the local OpenAI-compatible gateway for every top-level NIST AI RMF function, NIST AI 600-1 GAI risk, and OWASP LLM Top 10 2025 item. It is automated eval coverage, not a formal compliance attestation.
  • trace-judge evaluates the judge against a packaged 150-example labeled dataset of (trace, criteria, expected verdict) records across risk, leak, brand-voice, tool-use, and task-completion criteria. Results include macro precision, recall, and F1 per criterion type plus the overall gate status. The default run uses a deterministic offline judge fixture that parses the prepared judge prompt and returns JSON through the same judge result parser used by live mode; run --live --model <judge-model> measures the actual configured judge model.
  • CI runs npm run eval:trace-judge:gate after build to block prompt-preparation, parser, metric, and dataset regressions without live secrets. PR runs execute npm run eval:trace-judge:gate:live when both HYBRIDAI_API_KEY and HYBRIDAI_CHATBOT_ID are available; otherwise they are explicitly harness-only. Pushes to main require both live credentials and fail before promotion when either secret is missing. With those secrets present, CI runs npm run eval:trace-judge:gate:live against the configured judge model (HYBRIDCLAW_TRACE_JUDGE_EVAL_MODEL, or hybridai/gpt-4.1-mini by default) and blocks promotion when judge precision, recall, or F1 regresses below the configured threshold.
  • add a new judge criterion by adding examples to src/evals/trace-judge-eval-dataset.ts with a stable criterionType, clear criteria text, representative traces for pass, partial, and fail, and then running npm run eval:trace-judge:gate after npm run build. Keep each criterion balanced enough that precision, recall, and F1 are meaningful.
  • hybridai-skills harvests the 🎯 Try it yourself prompts from docs/content/guides/skills/*.md into a fixture set, then grades whether each prompt activates its documented skill. setup writes the fixture JSONL, list inspects it, run --dry-run validates fixtures without calling the model, and run (default --live, --max 3) posts each prompt to the local OpenAI endpoint and grades the tool trace with the same resolveObservedSkillName oracle the gateway uses
  • filter hybridai-skills runs with --skill <name>, --kind try-it|conversation, and --max N; results land at ~/.hybridclaw/data/evals/hybridai-skills/latest-run.json and are also shown via /eval hybridai-skills results
  • hybridai-skills run --explicit rewrites each prompt to start with /<skill> to force invocation, and live summaries show the observed skill, whether artifacts were produced, and counted tool-call totals per fixture
  • eval-profiled loopback requests auto-approve tools and return execution-session plus artifact-count headers so detached and profiled eval runs can finish unattended while still being easy to correlate later
  • locomo --mode qa runs a native HybridClaw QA harness against the official LoCoMo conversations, generates answers through the local OpenAI-compatible gateway, and scores those answers with LoCoMo-style question metrics
  • locomo --mode retrieval skips model generation, ingests each conversation into an isolated native memory session, and scores evidence hit-rate from recalled semantic memories
  • locomo --mode retrieval --matrix runs the default retrieval sweep across backend, rerank, and tokenizer combinations and renders one comparison table
  • locomo --mode retrieval --matrix backend|rerank|tokenizer|embedding runs a single-dimension sweep and keeps the other retrieval settings at their defaults
  • retrieval-mode knobs are benchmark-only: --retrieval-query raw|no-stopwords, --retrieval-backend cosine|full-text|hybrid, --retrieval-rerank none|bm25 (default: bm25), --retrieval-tokenizer unicode61|porter|trigram, and --retrieval-embedding hashed|transformers
  • locomo --num-samples limits conversation records; use --max-questions for quick smoke tests over a small question slice
  • by default, locomo --mode qa creates one fresh template-seeded agent workspace per conversation sample; use --current-agent to reuse the current agent workspace
  • swebench-verified, agentbench, and gaia currently print starter recipes and setup guidance rather than a native managed runner
  • outside suite-specific overrides, the default eval mode keeps the current agent workspace but opens a fresh OpenAI-compatible session per request
  • --fresh-agent uses a temporary template-seeded agent workspace for each eval request
  • detached run logs and summaries are stored under ~/.hybridclaw/data/evals/

Harness Evolution Workflows

hybridclaw harness-evolve runs controlled eval-driven evolution loops against one target coworker workspace. It initializes or validates a bash-only seed, runs a command-backed eval suite, asks the evolve-agent for F12-governed edits, and records round summaries plus manifests for review.

hybridclaw harness-evolve init --target /tmp/hc-evolve-agent
hybridclaw harness-evolve validate-seed --target /tmp/hc-evolve-agent
hybridclaw harness-evolve contract
hybridclaw harness-evolve run \
  --target /tmp/hc-evolve-agent \
  --suite /tmp/hc-evals/scenarios.json \
  --rounds 2 \
  --k 1 \
  --fresh-seed
hybridclaw harness-evolve status --summary /tmp/hc-evolve-agent/runs/<run-id>/summary.json
  • editable surfaces are limited to system_prompt.md, tools.yaml, tools/, middleware/, sub_agents/, config/, and long_term_memory/
  • eval suites are JSON files, or skill directories containing evals/scenarios.json
  • each task command is split into argv and run without a shell; wrap pipes, redirects, and multi-command checks in a script file
  • --dry-run exercises eval execution and summaries without applying edits
  • --commit creates Git commits for confirmed rounds in a Git-backed target workspace
  • the admin console reads completed runs from /admin/harness-evolution when HYBRIDCLAW_HARNESS_EVOLUTION_ROOTS allowlists the target root

See Harness Evolution for an example suite and benchmark-adaptation guidance.

The same loopback surface is available directly from the running gateway:

curl http://127.0.0.1:9090/v1/models

curl http://127.0.0.1:9090/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <WEB_API_TOKEN>' \
  -d '{"model":"hybridai/gpt-4.1-mini","messages":[{"role":"user","content":"Hello"}]}'
  • /v1/models and /v1/chat/completions use the same local gateway process; they are not a separate service
  • requests must include Authorization: Bearer <WEB_API_TOKEN> or Authorization: Bearer <GATEWAY_API_TOKEN>; loopback address alone does not authenticate API requests
  • delegated chat completions return an acknowledgement and include hybridclaw.delegation with { "id": "<completion-id>", "status": "queued" }; non-streaming responses also set X-HybridClaw-Delegation-Id
  • delegated streaming completions carry the same hybridclaw.delegation object on the final stop chunk
  • poll GET /v1/chat/completions/{completion-id} to retrieve delegated job state; responses include top-level status with one of queued, in_progress, completed, failed, or cancelled
  • while a delegated job is queued or running, retrieval returns the original acknowledgement with finish_reason: null; when completed, it returns the synthesized final answer with finish_reason: "stop"; failed jobs include a top-level OpenAI-shaped error
  • polling intervals around 1-5 seconds are appropriate for delegated jobs, which may wait behind the delegation concurrency limit before running
  • these endpoints are intended for local tooling and eval harnesses rather than public exposure

Auth And Providers

hybridclaw auth login
hybridclaw auth login hybridai [--device-code|--browser|--import] [--base-url <url>]
hybridclaw auth login codex [--device-code|--browser|--import]
hybridclaw auth login anthropic [model-id] [--method <api-key|claude-cli>] [--api-key <key>] [--base-url <url>] [--no-default]
hybridclaw auth login openrouter [model-id] [--api-key <key>] [--base-url <url>] [--no-default]
hybridclaw auth login mistral [model-id] [--api-key <key>] [--base-url <url>] [--no-default]
hybridclaw auth login huggingface [model-id] [--api-key <token>] [--base-url <url>] [--no-default]
hybridclaw auth login google [--client-id <id>] [--client-secret <secret>] [--account <email>] [--scopes <scopes>] [--refresh-token <token>] [--redirect-port <port>]
hybridclaw auth login microsoft365 [--client-id <id>] [--client-secret <secret>] [--tenant-id <tenant>] [--account <label>] [--scopes <scopes>] [--refresh-token <token>] [--redirect-port <port>]
hybridclaw auth login gemini [model-id] [--api-key <key>] [--base-url <url>] [--no-default]
hybridclaw auth login deepseek [model-id] [--api-key <key>] [--base-url <url>] [--no-default]
hybridclaw auth login xai [model-id] [--api-key <key>] [--base-url <url>] [--no-default]
hybridclaw auth login zai [model-id] [--api-key <key>] [--base-url <url>] [--no-default]
hybridclaw auth login kimi [model-id] [--api-key <key>] [--base-url <url>] [--no-default]
hybridclaw auth login minimax [model-id] [--api-key <key>] [--base-url <url>] [--no-default]
hybridclaw auth login dashscope [model-id] [--api-key <key>] [--base-url <url>] [--no-default]
hybridclaw auth login xiaomi [model-id] [--api-key <key>] [--base-url <url>] [--no-default]
hybridclaw auth login kilo [model-id] [--api-key <key>] [--base-url <url>] [--no-default]
hybridclaw auth login local <ollama|lmstudio|llamacpp|vllm> [model-id] [--name <endpoint>] [--base-url <url>] [--api-key <key>] [--thinking-format qwen] [--no-default]
hybridclaw auth login msteams [--app-id <id>|--client-id <id>] [--app-password <secret>|--client-secret <secret>] [--tenant-id <id>]
hybridclaw auth login slack [--bot-token <xoxb...>] [--app-token <xapp...>]
hybridclaw auth status <provider>
hybridclaw auth logout <provider>
hybridclaw auth whatsapp reset
hybridclaw local status
hybridclaw local configure <backend> [model-id] [--name <endpoint>] [--base-url <url>] [--api-key <key>] [--thinking-format qwen] [--no-default]
hybridclaw help hybridai
hybridclaw help codex
hybridclaw help anthropic
hybridclaw help openrouter
hybridclaw help mistral
hybridclaw help huggingface
hybridclaw help auth
hybridclaw help gemini
hybridclaw help deepseek
hybridclaw help xai
hybridclaw help zai
hybridclaw help kimi
hybridclaw help minimax
hybridclaw help dashscope
hybridclaw help xiaomi
hybridclaw help kilo
hybridclaw help msteams
hybridclaw help slack
hybridclaw help local

auth status supports hybridai, codex, anthropic, openrouter, mistral, huggingface, google, gemini, deepseek, xai, zai, kimi, minimax, dashscope, xiaomi, kilo, local, msteams, and slack. Legacy aliases such as hybridclaw hybridai ..., hybridclaw codex ..., and hybridclaw local ... still work, but auth is the primary surface. auth login without a provider runs the same interactive onboarding flow as hybridclaw onboarding. auth status prints local credential-source and config state while redacting the secret values themselves. Anthropic supports --method api-key for direct Messages API calls and --method claude-cli for the official Claude CLI transport in host sandbox mode. Google OAuth credentials for Workspace skills are managed with hybridclaw auth login google; the refresh token and client secret are stored in encrypted runtime secrets, and agent runtimes receive short-lived access tokens instead of long-lived refresh tokens.

Secrets And Routes

Named secrets and gateway-side auth routes are available from both the local CLI and local TUI/web slash-command surface:

hybridclaw secret list
hybridclaw secret set <name> <value>
hybridclaw secret status <name>
hybridclaw secret unset <name>
hybridclaw secret route list
hybridclaw secret route add <url-prefix> <secret-name|google-oauth|microsoft-oauth> [header] [prefix|none]
hybridclaw secret route remove <url-prefix> [header]
hybridclaw env list
hybridclaw env set <name> <value>
hybridclaw env show <name>
hybridclaw env unset <name>
/secret list
/secret set <name> <value>
/secret status <name>
/secret unset <name>
/secret route list
/secret route add <url-prefix> <secret-name|google-oauth|microsoft-oauth> [header] [prefix|none]
/secret route remove <url-prefix> [header]
/env list
/env set <name> <value>
/env show <name>
/env unset <name>
  • local-only surface: /secret ... is available from local TUI and local web chat sessions, not from Discord or other remote channels
  • hybridclaw secret status <name> reports whether the secret is stored; it never outputs decrypted values. Secrets are only resolved gateway-side via <secret:NAME> placeholders or auth rules
  • stored secret names must use uppercase letters, digits, and underscores
  • built-in provider keys and custom names share the same encrypted ~/.hybridclaw/credentials.json store
  • /secret route add manages tools.httpRequest.authRules[], which lets the gateway inject the real auth header for matching http_request tool calls
  • use prefix for Bearer <secret> or none for raw header injection
  • use google-oauth as the secret name for direct Google API routes after hybridclaw auth login google; see Google OAuth For Direct Google APIs
  • use microsoft-oauth as the secret name for direct Microsoft Graph routes after hybridclaw auth login microsoft365
  • env stores plaintext runtime values such as local device hostnames, account ids, or usernames for agent helpers. Do not use it for passwords, tokens, API keys, or signing material; use encrypted secrets for those.

Channels

hybridclaw channels discord setup [--token <token>] [--allow-user-id <snowflake>]... [--prefix <prefix>]
hybridclaw channels slack manifest [--format <yaml|json>]
hybridclaw channels slack register-commands [--app-id <A...>] [--config-token <xoxe-...>]
hybridclaw channels discord_webhook setup --webhook-url <https://discord.com/api/webhooks/...> [--target default] [--default-username <name>] [--default-avatar-url <url>]
hybridclaw channels slack_webhook setup --webhook-url <https://hooks.slack.com/services/...> [--target default] [--default-username <name>] [--default-icon-emoji <:emoji:>] [--default-icon-url <url>]
hybridclaw channel add discord_webhook --webhook-url <https://discord.com/api/webhooks/...> [--target default]
hybridclaw channel add slack_webhook --webhook-url <https://hooks.slack.com/services/...> [--target default]
hybridclaw channels telegram setup [--token <token>] [--allow-from <user-id|@username|*>]... [--group-allow-from <user-id|@username|*>]... [--dm-policy <open|allowlist|disabled>] [--group-policy <open|allowlist|disabled>] [--poll-interval-ms <ms>] [--text-chunk-limit <chars>] [--media-max-mb <mb>] [--require-mention|--no-require-mention]
hybridclaw channels signal setup [--daemon-url <url>] --account <+E164|uuid> [--allow-from <+E164|uuid|*>]... [--group-allow-from <+E164|uuid|*>]... [--dm-policy <open|allowlist|disabled>] [--group-policy <open|allowlist|disabled>] [--text-chunk-limit <chars>] [--reconnect-interval-ms <ms>] [--outbound-delay-ms <ms>]
hybridclaw channels threema setup --identity <gateway-id> [--secret <gateway-secret>] [--api-base-url <url>] [--allow-from <threema-target|*>]... [--dm-policy <open|allowlist|disabled>] [--text-chunk-limit <chars>] [--outbound-delay-ms <ms>]
hybridclaw channels imessage setup [--backend <local|remote>] [--allow-from <phone|email|chat:id>]... [--server-url <url>] [--password <password>] [--cli-path <path>] [--db-path <path>] [--webhook-path <path>] [--allow-private-network]
hybridclaw channels whatsapp setup [--reset] [--allow-from <+E164>]...
hybridclaw channels email setup [--address <email>] [--password <password>] [--imap-host <host>] [--imap-port <port>] [--imap-secure|--no-imap-secure] [--smtp-host <host>] [--smtp-port <port>] [--smtp-secure|--no-smtp-secure] [--folder <name>]... [--allow-from <email|*@domain|*>]... [--poll-interval-ms <ms>] [--text-chunk-limit <chars>] [--media-max-mb <mb>]
hybridclaw gateway voice info
hybridclaw gateway voice call <number>
hybridclaw auth login msteams [--app-id <id>|--client-id <id>] [--app-password <secret>|--client-secret <secret>] [--tenant-id <id>]
hybridclaw auth login slack [--bot-token <xoxb...>] [--app-token <xapp...>]

Microsoft Teams and full Slack setup use auth login instead of channels setup because they need app credentials rather than a local pairing flow. Slack Incoming Webhook and Discord Incoming Webhook setup are outbound-only and store each webhook URL as an encrypted runtime secret. Threema uses Gateway Basic mode for outbound text delivery. For the step-by-step setup guides, see Channels: Overview and Connect Your First Channel. Twilio voice is configured through /admin/channels or direct voice.* config keys, then inspected or used for outbound dialing with hybridclaw gateway voice info and hybridclaw gateway voice call <number>. Local TUI/web sessions can also write channel config and secrets with /config set ... and /secret set ...; see Channels: Local Config And Secrets for channel-specific examples and current CLI-only limitations such as WhatsApp pairing.

Agents And Packages

hybridclaw agent list
hybridclaw agent config <json|--json <json>> [--activate]
hybridclaw agent export [agent-id] [-o <path>]
hybridclaw agent inspect <file.claw>
hybridclaw agent install <file.claw|https://.../*.claw|official:<agent-dir>|github:owner/repo[/<ref>]/<agent-dir>> [--id <id>] [--force] [--skip-skill-scan] [--skip-externals] [--skip-import-errors] [--yes]
hybridclaw agent activate <agent-id>
hybridclaw agent uninstall <agent-id> [--yes]
hybridclaw gateway agent [list|switch <id>|create <id>|model [name]]

agent export and agent install are the primary archive verbs. Legacy aliases remain accepted: agent pack maps to export, and agent unpack maps to install. Local TUI/web sessions also expose /agent install <source> for the same archive flows against a running gateway. agent activate <agent-id> sets the default agent for new requests that do not pin an agent explicitly.

agent config is the JSON provisioning path for generated agents. It upserts agent metadata directly, can overwrite top-level workspace markdown files, can set the empty-chat emptyChatHeader, and imports imageAsset URLs or local file paths into the agent workspace:

hybridclaw agent config '{"id":"felix","model":"gpt-5.4-mini","emptyChatHeader":"Ready to clear the support queue?","imageAsset":"https://example.com/felix.jpg","markdown":{"IDENTITY.md":"# Felix\n"}}' --activate

Proxy agents use the same command with a per-agent proxy object:

hybridclaw agent config '{"id":"support-proxy","name":"Support Proxy","proxy":{"kind":"hybridai","baseUrl":"https://app.hybridai.one","chatbotId":"bot_abc123","apiKey":"<secret:HYBRIDAI_API_KEY>","conversationScope":"user"}}'

Use agent config for metadata plus bootstrap markdown. Use agent install when you need a portable .claw archive with arbitrary workspace files, bundled skills, bundled plugins, or install-time imports.

For archive flags such as --description, --author, skill/plugin bundling, and GitHub install sources, see Agent Packages.

Migration

hybridclaw migrate openclaw [--source <path>] [--agent <id>] [--dry-run] [--overwrite] [--migrate-secrets] [--force]
hybridclaw migrate hermes [--source <path>] [--agent <id>] [--dry-run] [--overwrite] [--migrate-secrets] [--force]

Use these commands to import compatible state from ~/.openclaw or ~/.hermes into a HybridClaw agent workspace. --dry-run previews the workspace, config, model, and secret changes before writing anything.

Backup And Restore

hybridclaw backup [--output <path>]
hybridclaw backup restore <archive.zip> [--force]

backup creates a timestamped zip archive of the HybridClaw runtime home (~/.hybridclaw by default, or $HYBRIDCLAW_DATA_DIR when set). SQLite databases are copied through the SQLite backup API so WAL-mode databases produce consistent snapshots. Ephemeral state — WAL/SHM sidecars, cache directories, container image state, evals, migration backups, and PID files — is excluded. backup restore validates the archive manifest and marker files (config.json, credentials.json) before replacing any data and prompts when the target runtime home already exists; pass --force to skip the prompt for scripted disaster-recovery restores.

Skills, Tools, Plugins, Audit

hybridclaw skill list
hybridclaw skill enable <skill-name> [--channel <kind>]
hybridclaw skill disable <skill-name> [--channel <kind>]
hybridclaw skill toggle [--channel <kind>]
hybridclaw skill inspect <skill-name>
hybridclaw skill inspect --all
hybridclaw skill runs <skill-name>
hybridclaw skill install <source>
hybridclaw skill install <skill-name> <dependency>
hybridclaw skill upgrade <source>
hybridclaw skill uninstall <skill-name>
hybridclaw skill revisions <skill-name>
hybridclaw skill rollback <skill-name> <revision-id>
hybridclaw skill setup <skill-name>
hybridclaw skill learn <skill-name> [--apply|--reject|--rollback]
hybridclaw skill history <skill-name>
hybridclaw skill sync [--skip-skill-scan] <source>
hybridclaw skill import [--force] [--skip-skill-scan] <source>
hybridclaw tool list
hybridclaw tool enable <tool-name>
hybridclaw tool disable <tool-name>
hybridclaw plugin list
hybridclaw plugin config <plugin-id> [key] [value|--unset]
hybridclaw plugin enable <plugin-id>
hybridclaw plugin disable <plugin-id>
hybridclaw plugin install <path|plugin-id|npm-spec>
hybridclaw plugin reinstall <path|plugin-id|npm-spec>
hybridclaw plugin check <plugin-id>
hybridclaw plugin uninstall <plugin-id>
hybridclaw update [status|--check] [--yes]
hybridclaw audit recent
hybridclaw audit recent session <sessionId> [n]
hybridclaw audit approvals [n] [--denied]
hybridclaw audit search <query>
hybridclaw audit verify <sessionId>
hybridclaw audit verify-usage-batch <batchId>
hybridclaw audit scan-leaks [sessionId] [--quiet|--all] [--level <critical|high|medium|low>] [--type <in,out,tool,url>] [--json]
hybridclaw audit instructions [--sync] [--approve]

skill import [--force] [--skip-skill-scan] supports packaged official/<skill-name> sources plus community imports from skills-sh, clawhub, lobehub, claude-marketplace, well-known, explicit GitHub repo/path refs, local directories, and .zip archives. Locally-imported skills receive personal trust and persist their import-source marker across restarts. skill install <source> and skill upgrade <source> manage packaged skills with manifest records, audit events, and rollback snapshots. skill uninstall <skill-name> removes a managed package, skill revisions <skill-name> lists recorded snapshots, and skill rollback <skill-name> <revision-id> restores one snapshot. skill install <skill-name> <dependency> runs one declared dependency from the named skill. skill setup <skill-name> runs every declared dependency for that skill in order. Use skill list first to discover the dependency ids exposed by a skill. skill sync [--skip-skill-scan] <source> is a convenience alias for skill import --force <source> when refreshing an installed skill from the same source syntax. plugin check <plugin-id> reports dependency, environment, and binary status for one discovered plugin before or after installation. audit scan-leaks loads rules from ./.confidential.yml or ~/.hybridclaw/.confidential.yml, scans prompt-bearing audit records, prints a severity summary, and exits with code 2 when matches are found. Use --level to set a minimum severity, --type to narrow to inbound prompts, outbound responses, tool I/O, or URL records, and --json for automation. audit verify-usage-batch <batchId> verifies the token-usage batch hash for buffered usage events. audit instructions --sync restores runtime instruction copies from installed sources; add --approve when the instruction audit workflow requires an explicit approval record. update checks for a newer installed release and can upgrade a global npm install. When --yes completes successfully and a local gateway is already running with a replayable launch command, HybridClaw restarts it automatically with the original parameters; otherwise it falls back to manual restart instructions. Source checkouts receive git-based update instructions instead.

When you start HybridClaw interactively (hybridclaw tui, hybridclaw gateway, or hybridclaw gateway start) and a newer release is available, HybridClaw prints the available version and prompts you to update before continuing. Answer y to install the update, or n to start on the current version. Installing exits the current command once the update finishes (the running process still holds the old code), so relaunch HybridClaw to use the new version; an already-running gateway is restarted automatically with its original parameters. This prompt appears only on an interactive terminal and only for global package installs; non-interactive shells and source checkouts are never blocked. The registry check is cached under the runtime home (version-check.json, 20-hour TTL) and refreshed in a detached background process, so startup never waits on the network — a newly published version surfaces on the next launch.

Network Policy

hybridclaw policy status
hybridclaw policy list [--agent <id>] [--json]
hybridclaw policy allow <host> [--agent <id>] [--methods <list>] [--paths <list>] [--port <number|*>] [--comment <text>]
hybridclaw policy deny <host> [--agent <id>] [--methods <list>] [--paths <list>] [--port <number|*>] [--comment <text>]
hybridclaw policy delete <number|host>
hybridclaw policy reset
hybridclaw policy default <allow|deny>
hybridclaw policy preset list
hybridclaw policy preset add <name> [--dry-run]
hybridclaw policy preset remove <name>

Policy commands edit the current workspace HTTP/network access policy. Rules are evaluated in order, first match wins, and bare site-scope hosts such as github.com also match subdomains such as api.github.com. Use policy list --agent <id> to show both global rules and rules scoped to a specific agent.

Deprecated Provider Aliases

hybridclaw local status
hybridclaw local configure <ollama|lmstudio|llamacpp|vllm> [model-id] [--name <endpoint>] [--base-url <url>] [--api-key <key>] [--thinking-format qwen] [--no-default]
hybridclaw hybridai base-url [url]
hybridclaw hybridai login [--device-code|--browser|--import] [--base-url <url>]
hybridclaw hybridai logout
hybridclaw hybridai status
hybridclaw codex login [--device-code|--browser|--import]
hybridclaw codex logout
hybridclaw codex status

These aliases remain accepted for compatibility, but the auth namespace is the primary surface for provider setup, status, and logout.

Discord And Session Commands

Discord supports !claw plus slash-command equivalents for the same core actions. Common examples:

!claw <message>
/agent
/btw <question>
/agent list
/agent switch <id>
/agent create <id> [--model <model>]
/agent model [name]
!claw bot set <id>
!claw model set <name>
!claw model clear
!claw model info
!claw rag on
!claw compact
/reset
!claw clear
!claw audit recent [n]
!claw audit verify [sessionId]
!claw audit search <query>
!claw audit approvals [n] [--denied]
!claw usage [summary|daily|monthly|model [daily|monthly] [agentId]]
!claw export session [sessionId]
!claw export trace [sessionId|all]
!claw mcp list
!claw mcp add <name> <json>
!claw schedule add "<cron>" <prompt>
!claw schedule add at "<ISO time>" <prompt>
!claw schedule add every <ms> <prompt>

/agent, /model, /reset, /mcp, /btw, /aux, /second-opinion, and related slash commands route through the same gateway command surface used by TUI and web chat. /context is local-only because it exposes session context-window accounting.

In Session

  • /help shows the same canonical slash-command list in TUI and embedded web chat, filtered per surface and kept in a consistent alphabetical order
  • /audit turn <n> and /audit run <runId> show focused turn traces for one request, including nearby tool, approval, and audit events
  • /aux test <task> <prompt> triggers a configured auxiliary text task on demand and prints the provider/model that answered
  • /second-opinion compares a question or validates the last answer with a stronger configured model; fact-check adds bounded web-search evidence
  • /escalate is registered by the bundled tier router when routing.enabled is true and raises exactly the next unpinned agent turn by one tier

Slash Command Inventory

These are the built-in slash commands exposed by local sessions and, where supported by the channel, by Discord/Slack slash or slash-text routing. Loaded plugins and explicit skill invocations can add dynamic slash commands; use /help or the TUI slash menu for the live session-specific list.

Command Main surface Purpose
`/agent [info list switch
/app <description> or /apps web chat Start an app-building conversation or open the Apps gallery
`/approve [view yes session
`/audit [sessionId] last turn
/auth status <provider> local TUI/web Show local auth and provider config state
/aux test <task> <prompt> local TUI/web Trigger a configured auxiliary text task and show the provider/model used
`/bot [info list set <id
/btw <question> local and chat channels Ask an ephemeral side question without tools or persistence
`/channel-mode <off mention free>`
`/channel-policy <open allowlist disabled>`
/clear local and chat channels Clear the visible session transcript
/compact local and chat channels Compact older session history into memory
`/concierge [info on off
`/config [check reload get
/context local TUI/web Show context-window usage and compaction headroom
`/dream [status on off
`/env [list set show
`/eval [list env
/escalate local and chat channels Start the next unpinned agent turn one configured routing tier higher
/export session [sessionId] local and chat channels Export a session snapshot
`/export trace [sessionId all]` local and chat channels
`/fullauto [status off on [prompt]
`/goal [condition status pause
/help or /h local and chat channels Show slash-command help
/info TUI Show bot, model, and runtime status together
`/mcp [list add toggle
/memory inspect [sessionId] local TUI/web Inspect built-in memory layers
/memory query <query> local TUI/web Preview prompt-time memory attachment
`/model [info list set
/paste TUI Attach a copied local file or clipboard image
`/policy [status list allow
`/plugin [list enable disable
`/rag [on off]` local and chat channels
`/ralph [info on off
`/reset [yes no]` local and chat channels
`/schedule add list remove
`/secret [list set status
`/second-opinion [compare validate fact-check]`
`/sessions [active clear-active prune --older-than [--dry-run
`/show [all thinking tools
/skill ... or /<skill> local TUI/web Manage skills or explicitly invoke one skill
/status local and chat channels Show runtime, session, and agent status
/stop or /abort TUI and active local runs Stop the current foreground request and full-auto mode
`/usage [summary daily monthly
`/voice [info call ]` local TUI/web
/exit, /quit, or /q TUI Exit the TUI

Standing Goals

/goal <condition> and /goal set <condition> store one active completion condition for the current thread and queue it as the first supervised user-role turn. A useful shape is:

/goal [do the work] until [measurable end state] without [constraints]

Strong conditions have three parts: the task in one clear line, a measurable done state, and any constraints the agent must follow. Examples:

/goal research recent changes in EU AI Act enforcement until you have a cited brief without using non-primary sources
/goal improve README until a new contributor can install, run, and test the project without asking follow-up questions
/goal add a dark/light theme toggle until it persists in localStorage and is verified in browser without changing unrelated UI

Later continuations are also normal user-role turns tagged internally as goal-continuation; they do not change the system prompt, tool set, or approval policy. Only one standing goal is active per thread.

Use /goal or /goal status to inspect progress, /goal pause to stop queueing continuations, /goal resume to continue, and /goal clear to remove the stored goal. stop, off, reset, none, and cancel are aliases for clear. Status shows the condition, elapsed time, evaluated turns, token/cost spend since the goal was set, and the judge's most recent reason. If the goal has already been achieved, /goal keeps showing the achieved condition and its final counters until you set or clear another goal. The default budget is 20 continuation turns. After each continuation, a cheap judge checks the condition against the recent conversation context and returns strict JSON { "done": boolean, "reason": string }; if the answer is no, the reason is included as guidance for the next turn. The loop pauses after three malformed judge responses.

High-stakes tool calls inside goal continuations still escalate through the same approval flow as ordinary turns. Pending approvals pause the goal without counting another turn, and any real user message preempts the loop so the operator stays in control. /goal persists intent; it does not bypass approval policy or grant full-auto permissions.

Agent budget hard-stops pause active goals through the R5.3 integration hook. The hard-stop emitter is not present in this release, so the hook is explicitly reserved for the R5.3 signal when that spend-tracking enforcement lands.

  • local TUI/web sessions also support /memory inspect [sessionId] to inspect the built-in memory layers for the current or an explicit session id
  • local TUI/web sessions support /btw <question> for ephemeral side questions that use recent conversation context, return a tool-less answer, and do not persist the side exchange to session history
  • in built-in web chat, /btw is the only slash command accepted while the current run is active
  • local TUI/web sessions support /memory query <query> to preview the exact prompt-memory block the current session would attach for that query
  • web chat supports /app <description> to start an app-building conversation; bare /app and /apps open the Apps gallery
  • local TUI/web sessions support /context to inspect context-window usage, remaining headroom, and compaction count for the active session
  • local TUI and web chat expose /voice info and /voice call <e164-number> for local Twilio diagnostics and outbound dialing
  • Local TUI and web chat sessions expose /config, /config check, /config reload, /config get <key>, /config set <key> <value>, /concierge, /auth status <provider>, and /secret list|set|status|unset|route alongside the existing runtime commands
  • local TUI and web chat also expose /dream [info|on|off|now] for nightly memory-consolidation status, scheduler toggling, and manual runs
  • local TUI and web chat expose /eval ..., mirroring the CLI eval helper and surfacing progress for managed runs such as tau2 and terminal-bench-2.0
  • TUI and chat surfaces use /agent, /agent install, /model, /mcp, /plugin, /skill, /compact, /reset, /plugin enable, /plugin disable, /plugin install, /plugin reinstall, /plugin reload, /skill install, /skill import, /skill learn, /schedule, /status, and related slash commands
  • TUI also supports /paste to queue a copied local file or clipboard image
  • TUI /skill config opens the interactive skill availability checklist
  • local TUI and web chat support /skill list to inspect dependency ids.
  • local TUI and web chat support /skill install <source>, /skill upgrade <source>, /skill uninstall <skill>, /skill revisions <skill>, and /skill rollback <skill> <revision-id> for package lifecycle work.
  • local TUI and web chat support /skill install <skill> <dependency> to run one declared skill dependency, and /skill setup <skill> to run every declared dependency for a skill.
  • an explicit /<skill> or /skill <name> turn keeps that skill active for the next plain-text follow-up in the same session; a new slash command cancels that carry-over
  • /status shows both the current session and current agent
  • /compact runs session compaction, and /reset runs the confirmed workspace reset flow
  • /plugin ... manages runtime plugins, and /mcp ... manages runtime MCP servers
  • /auth status <provider> shows local auth and config state for the supported local-session providers, including Anthropic and the OpenAI-compatible remote providers
  • Typing / in the TUI opens the slash-command menu with inline filtering and help aliases
  • The TUI startup banner summarizes the active model, sandbox, gateway, provider, and chatbot context before the first prompt
  • Pending approvals in the TUI open an interactive picker with Up / Down navigation, Enter confirmation, number-key quick select, and Esc to skip; non-interactive terminals keep the text prompt fallback
  • pressing Up or Down on an empty prompt recalls earlier prompts
  • press Ctrl-C or Ctrl-D twice within five seconds to exit the TUI
  • on exit, HybridClaw prints token/file/tool totals when remote history is available, otherwise an explicit unavailable summary, plus a ready-to-run hybridclaw tui --resume <sessionId> command for that session

Example secret flow:

/secret set STAGING_HYBRIDAI_API_KEY demo_key_2024
/secret route add https://staging.hybridai.one/api/v1/ STAGING_HYBRIDAI_API_KEY X-API-Key none

With that route in place, the model can use http_request to call matching URLs without seeing the plaintext API key.

Example skill dependency flow:

/skill list
/skill setup gws
/skill install manim-video manim
/skill install manim-video ffmpeg