Referência da CLI
Esta página descreve o comportamento atual da CLI. Se os comandos mudarem, atualize este documento.Páginas de comandos
setuponboardconfigureconfigdoctordashboardresetuninstallupdatemessageagentagentsacpstatushealthsessionsgatewaylogssystemmodelsmemorynodesdevicesnodeapprovalssandboxtuibrowsercrondnsdocshookswebhookspairingplugins(comandos de plugin)channelssecurityskillsvoicecall(plugin; se instalado)
Flags globais
--dev: isola o estado em~/.openclaw-deve desloca as portas padrão.--profile <name>: isola o estado em~/.openclaw-<name>.--no-color: desativa cores ANSI.--update: atalho paraopenclaw update(apenas instalações a partir do código-fonte).-V,--version,-v: imprime a versão e sai.
Estilo de saída
- Cores ANSI e indicadores de progresso só são renderizados em sessões TTY.
- Hiperlinks OSC-8 são renderizados como links clicáveis em terminais compatíveis; caso contrário, usamos URLs simples.
--json(e--plainquando suportado) desativa a estilização para uma saída limpa.--no-colordesativa a estilização ANSI;NO_COLOR=1também é respeitado.- Comandos de longa duração mostram um indicador de progresso (OSC 9;4 quando suportado).
Paleta de cores
O OpenClaw usa uma paleta “lobster” para a saída da CLI.accent(#FF5A2D): títulos, rótulos, destaques primários.accentBright(#FF7A3D): nomes de comandos, ênfase.accentDim(#D14A22): texto de destaque secundário.info(#FF8A5B): valores informativos.success(#2FBF71): estados de sucesso.warn(#FFB020): avisos, alternativas, atenção.error(#E23D2D): erros, falhas.muted(#8B7F77): desênfase, metadados.
src/terminal/palette.ts (também conhecido como “lobster seam”).
Árvore de comandos
openclaw voicecall).
Segurança
openclaw security audit— audita a configuração + estado local em busca de armadilhas comuns de segurança.openclaw security audit --deep— sondagem ao vivo do Gateway com melhor esforço.openclaw security audit --fix— reforça padrões seguros e aplica chmod ao estado/configuração.
Plugins
Gerencie extensões e suas configurações:openclaw plugins list— descobrir plugins (use--jsonpara saída de máquina).openclaw plugins info <id>— mostrar detalhes de um plugin.openclaw plugins install <path|.tgz|npm-spec>— instalar um plugin (ou adicionar um caminho de plugin aplugins.load.paths).openclaw plugins enable <id>/disable <id>— alternarplugins.entries.<id>.enabled.openclaw plugins doctor— relatar erros de carregamento de plugins.
Memória
Busca vetorial emMEMORY.md + memory/*.md:
openclaw memory status— mostrar estatísticas do índice.openclaw memory index— reindexar arquivos de memória.openclaw memory search "<query>"— busca semântica na memória.
Comandos de barra do chat
Mensagens de chat suportam comandos/... (texto e nativos). Veja /tools/slash-commands.
Destaques:
/statuspara diagnósticos rápidos./configpara mudanças persistidas de configuração./debugpara substituições de configuração apenas em tempo de execução (memória, não disco; requercommands.debug: true).
Configuração + integração inicial
setup
Inicializa configuração + workspace.
Opções:
--workspace <dir>: caminho do workspace do agente (padrão~/.openclaw/workspace).--wizard: executar o assistente de integração inicial.--non-interactive: executar o assistente sem prompts.--mode <local|remote>: modo do assistente.--remote-url <url>: URL remota do Gateway.--remote-token <token>: token remoto do Gateway.
--non-interactive, --mode, --remote-url, --remote-token).
onboard
Assistente interativo para configurar gateway, workspace e skills.
Opções:
--workspace <dir>--reset(redefine configuração + credenciais + sessões + workspace antes do assistente)--non-interactive--mode <local|remote>--flow <quickstart|advanced|manual>(manual é um alias para avançado)--auth-choice <setup-token|token|chutes|openai-codex|openai-api-key|openrouter-api-key|ai-gateway-api-key|moonshot-api-key|moonshot-api-key-cn|kimi-code-api-key|synthetic-api-key|venice-api-key|gemini-api-key|zai-api-key|apiKey|minimax-api|minimax-api-lightning|opencode-zen|skip>--token-provider <id>(não interativo; usado com--auth-choice token)--token <token>(não interativo; usado com--auth-choice token)--token-profile-id <id>(não interativo; padrão:<provider>:manual)--token-expires-in <duration>(não interativo; ex.:365d,12h)--anthropic-api-key <key>--openai-api-key <key>--openrouter-api-key <key>--ai-gateway-api-key <key>--moonshot-api-key <key>--kimi-code-api-key <key>--gemini-api-key <key>--zai-api-key <key>--minimax-api-key <key>--opencode-zen-api-key <key>--custom-base-url <url>(não interativo; usado com--auth-choice custom-api-key)--custom-model-id <id>(não interativo; usado com--auth-choice custom-api-key)--custom-api-key <key>(não interativo; opcional; usado com--auth-choice custom-api-key; usaCUSTOM_API_KEYcomo fallback quando omitido)--custom-provider-id <id>(não interativo; opcional; id personalizado do provedor)--custom-compatibility <openai|anthropic>(não interativo; opcional; padrãoopenai)--gateway-port <port>--gateway-bind <loopback|lan|tailnet|auto|custom>--gateway-auth <token|password>--gateway-token <token>--gateway-password <password>--remote-url <url>--remote-token <token>--tailscale <off|serve|funnel>--tailscale-reset-on-exit--install-daemon--no-install-daemon(alias:--skip-daemon)--daemon-runtime <node|bun>--skip-channels--skip-skills--skip-health--skip-ui--node-manager <npm|pnpm|bun>(pnpm recomendado; bun não é recomendado para o runtime do Gateway)--json
configure
Assistente interativo de configuração (modelos, canais, skills, gateway).
config
Auxiliares de configuração não interativos (get/set/unset). Executar openclaw config sem
subcomando inicia o assistente.
Subcomandos:
config get <path>: imprimir um valor de configuração (caminho com ponto/colchetes).config set <path> <value>: definir um valor (JSON5 ou string bruta).config unset <path>: remover um valor.
doctor
Verificações de saúde + correções rápidas (configuração + gateway + serviços legados).
Opções:
--no-workspace-suggestions: desativar dicas de memória do workspace.--yes: aceitar padrões sem prompt (headless).--non-interactive: pular prompts; aplicar apenas migrações seguras.--deep: escanear serviços do sistema por instalações extras do gateway.
Auxiliares de canais
channels
Gerenciar contas de canais de chat (WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/MS Teams).
Subcomandos:
channels list: mostrar canais configurados e perfis de autenticação.channels status: verificar alcançabilidade do gateway e saúde do canal (--probeexecuta verificações extras; useopenclaw healthouopenclaw status --deeppara sondagens de saúde do gateway).- Dica:
channels statusimprime avisos com correções sugeridas quando consegue detectar configurações incorretas comuns (e então aponta paraopenclaw doctor). channels logs: mostrar logs recentes de canais a partir do arquivo de log do gateway.channels add: configuração no estilo assistente quando nenhuma flag é passada; flags mudam para modo não interativo.channels remove: desativado por padrão; passe--deletepara remover entradas de configuração sem prompts.channels login: login interativo do canal (apenas WhatsApp Web).channels logout: sair de uma sessão de canal (se suportado).
--channel <name>:whatsapp|telegram|discord|googlechat|slack|mattermost|signal|imessage|msteams--account <id>: id da conta do canal (padrãodefault)--name <label>: nome de exibição da conta
channels login:
--channel <channel>(padrãowhatsapp; suportawhatsapp/web)--account <id>--verbose
channels logout:
--channel <channel>(padrãowhatsapp)--account <id>
channels list:
--no-usage: pular snapshots de uso/cota do provedor de modelos (apenas OAuth/API).--json: saída em JSON (inclui uso, a menos que--no-usageesteja definido).
channels logs:
--channel <name|all>(padrãoall)--lines <n>(padrão200)--json
skills
Listar e inspecionar skills disponíveis, além de informações de prontidão.
Subcomandos:
skills list: listar skills (padrão quando não há subcomando).skills info <name>: mostrar detalhes de uma skill.skills check: resumo de requisitos prontos vs ausentes.
--eligible: mostrar apenas skills prontas.--json: saída em JSON (sem estilização).-v,--verbose: incluir detalhes de requisitos ausentes.
npx clawhub para pesquisar, instalar e sincronizar skills.
pairing
Aprovar solicitações de pareamento por DM entre canais.
Subcomandos:
pairing list <channel> [--json]pairing approve <channel> <code> [--notify]
webhooks gmail
Configuração + executor de hook do Gmail Pub/Sub. Veja /automation/gmail-pubsub.
Subcomandos:
webhooks gmail setup(requer--account <email>; suporta--project,--topic,--subscription,--label,--hook-url,--hook-token,--push-token,--bind,--port,--path,--include-body,--max-bytes,--renew-minutes,--tailscale,--tailscale-path,--tailscale-target,--push-endpoint,--json)webhooks gmail run(substituições em tempo de execução para as mesmas flags)
dns setup
Auxiliar de DNS para descoberta em grande área (CoreDNS + Tailscale). Veja /gateway/discovery.
Opções:
--apply: instalar/atualizar configuração do CoreDNS (requer sudo; apenas macOS).
Mensagens + agente
message
Mensageria unificada de saída + ações de canal.
Veja: /cli/message
Subcomandos:
message send|poll|react|reactions|read|edit|delete|pin|unpin|pins|permissions|search|timeout|kick|banmessage thread <create|list|reply>message emoji <list|upload>message sticker <send|upload>message role <info|add|remove>message channel <info|list>message member infomessage voice statusmessage event <list|create>
openclaw message send --target +15555550123 --message "Hi"openclaw message poll --channel discord --target channel:123 --poll-question "Snack?" --poll-option Pizza --poll-option Sushi
agent
Executar uma rodada de agente via o Gateway (ou --local incorporado).
Obrigatório:
--message <text>
--to <dest>(para chave de sessão e entrega opcional)--session-id <id>--thinking <off|minimal|low|medium|high|xhigh>(apenas modelos GPT-5.2 + Codex)--verbose <on|full|off>--channel <whatsapp|telegram|discord|slack|mattermost|signal|imessage|msteams>--local--deliver--json--timeout <seconds>
agents
Gerenciar agentes isolados (workspaces + autenticação + roteamento).
agents list
Listar agentes configurados.
Opções:
--json--bindings
agents add [name]
Adicionar um novo agente isolado. Executa o assistente guiado a menos que flags (ou --non-interactive) sejam passadas; --workspace é obrigatório no modo não interativo.
Opções:
--workspace <dir>--model <id>--agent-dir <dir>--bind <channel[:accountId]>(repetível)--non-interactive--json
channel[:accountId]. Quando accountId é omitido para WhatsApp, o id de conta padrão é usado.
agents delete <id>
Excluir um agente e podar seu workspace + estado.
Opções:
--force--json
acp
Executar a ponte ACP que conecta IDEs ao Gateway.
Veja acp para opções completas e exemplos.
status
Mostrar a saúde da sessão vinculada e destinatários recentes.
Opções:
--json--all(diagnóstico completo; somente leitura, colável)--deep(sondar canais)--usage(mostrar uso/cota do provedor de modelos)--timeout <ms>--verbose--debug(alias para--verbose)
- A visão geral inclui o status do Gateway + serviço do host do nó quando disponível.
Rastreamento de uso
O OpenClaw pode expor uso/cota do provedor quando credenciais OAuth/API estão disponíveis. Superfícies:/status(adiciona uma linha curta de uso do provedor quando disponível)openclaw status --usage(imprime o detalhamento completo do provedor)- Barra de menus do macOS (seção Uso em Context)
- Os dados vêm diretamente dos endpoints de uso dos provedores (sem estimativas).
- Provedores: Anthropic, GitHub Copilot, OpenAI Codex OAuth, além de Gemini CLI/Antigravity quando esses plugins de provedor estão habilitados.
- Se não existirem credenciais correspondentes, o uso fica oculto.
- Detalhes: veja Rastreamento de uso.
health
Buscar a saúde do Gateway em execução.
Opções:
--json--timeout <ms>--verbose
sessions
Listar sessões de conversas armazenadas.
Opções:
--json--verbose--store <path>--active <minutes>
Resetar / Desinstalar
reset
Resetar configuração/estado local (mantém a CLI instalada).
Opções:
--scope <config|config+creds+sessions|full>--yes--non-interactive--dry-run
--non-interactiverequer--scopee--yes.
uninstall
Desinstalar o serviço do gateway + dados locais (a CLI permanece).
Opções:
--service--state--workspace--app--all--yes--non-interactive--dry-run
--non-interactiverequer--yese escopos explícitos (ou--all).
Gateway
gateway
Executar o Gateway WebSocket.
Opções:
--port <port>--bind <loopback|tailnet|lan|auto|custom>--token <token>--auth <token|password>--password <password>--tailscale <off|serve|funnel>--tailscale-reset-on-exit--allow-unconfigured--dev--reset(redefinir configuração de dev + credenciais + sessões + workspace)--force(matar listener existente na porta)--verbose--claude-cli-logs--ws-log <auto|full|compact>--compact(alias para--ws-log compact)--raw-stream--raw-stream-path <path>
gateway service
Gerenciar o serviço do Gateway (launchd/systemd/schtasks).
Subcomandos:
gateway status(sonda o RPC do Gateway por padrão)gateway install(instalação do serviço)gateway uninstallgateway startgateway stopgateway restart
gateway statussonda o RPC do Gateway por padrão usando a porta/configuração resolvida do serviço (substitua com--url/--token/--password).gateway statussuporta--no-probe,--deepe--jsonpara scripting.gateway statustambém expõe serviços de gateway legados ou extras quando consegue detectá-los (--deepadiciona varreduras em nível de sistema). Serviços OpenClaw nomeados por perfil são tratados como de primeira classe e não são sinalizados como “extras”.gateway statusimprime qual caminho de configuração a CLI usa vs qual configuração o serviço provavelmente usa (env do serviço), além da URL de sondagem resolvida.gateway install|uninstall|start|stop|restartsuporta--jsonpara scripting (a saída padrão permanece amigável para humanos).gateway installusa o runtime Node por padrão; bun não é recomendado (bugs no WhatsApp/Telegram).- Opções de
gateway install:--port,--runtime,--token,--force,--json.
logs
Acompanhar logs de arquivos do Gateway via RPC.
Notas:
- Sessões TTY renderizam uma visualização estruturada com cores; não TTY recua para texto simples.
--jsonemite JSON delimitado por linhas (um evento de log por linha).
gateway <subcommand>
Auxiliares da CLI do Gateway (use --url, --token, --password, --timeout, --expect-final para subcomandos RPC).
Ao passar --url, a CLI não aplica automaticamente configuração ou credenciais de ambiente.
Inclua --token ou --password explicitamente. A ausência de credenciais explícitas é um erro.
Subcomandos:
gateway call <method> [--params <json>]gateway healthgateway statusgateway probegateway discovergateway install|uninstall|start|stop|restartgateway run
config.apply(validar + gravar configuração + reiniciar + acordar)config.patch(mesclar uma atualização parcial + reiniciar + acordar)update.run(executar atualização + reiniciar + acordar)
config.set/config.apply/config.patch diretamente, passe baseHash de
config.get se uma configuração já existir.
Modelos
Veja /concepts/models para comportamento de fallback e estratégia de varredura. Autenticação Anthropic preferida (setup-token):models (raiz)
openclaw models é um alias para models status.
Opções da raiz:
--status-json(alias paramodels status --json)--status-plain(alias paramodels status --plain)
models list
Opções:
--all--local--provider <name>--json--plain
models status
Opções:
--json--plain--check(sair 1=expirado/ausente, 2=expirando)--probe(sondagem ao vivo dos perfis de autenticação configurados)--probe-provider <name>--probe-profile <id>(repetível ou separado por vírgulas)--probe-timeout <ms>--probe-concurrency <n>--probe-max-tokens <n>
--probe executa requisições ao vivo (pode consumir tokens e acionar limites de taxa).
--probe executa solicitações ao vivo (pode consumir tokens e acionar limites de taxa de ativação).
models set <model>
Definir agents.defaults.model.primary.
models set-image <model>
Definir agents.defaults.imageModel.primary.
models aliases list|add|remove
Opções:
list:--json,--plainadd <alias> <model>remove <alias>
models fallbacks list|add|remove|clear
Opções:
list:--json,--plainadd <model>remove <model>clear
models image-fallbacks list|add|remove|clear
Opções:
list:--json,--plainadd <model>remove <model>clear
models scan
Opções:
--min-params <b>--max-age-days <days>--provider <name>--max-candidates <n>--timeout <ms>--concurrency <n>--no-probe--yes--no-input--set-default--set-image--json
models auth add|setup-token|paste-token
Opções:
add: auxiliar interativo de autenticaçãosetup-token:--provider <name>(padrãoanthropic),--yespaste-token:--provider <name>,--profile-id <id>,--expires-in <duration>
models auth order get|set|clear
Opções:
get:--provider <name>,--agent <id>,--jsonset:--provider <name>,--agent <id>,<profileIds...>clear:--provider <name>,--agent <id>
Sistema
system event
Enfileirar um evento do sistema e opcionalmente acionar um heartbeat (RPC do Gateway).
Obrigatório:
--text <text>
--mode <now|next-heartbeat>--json--url,--token,--timeout,--expect-final
system heartbeat last|enable|disable
Controles de heartbeat (RPC do Gateway).
Opções:
--json--url,--token,--timeout,--expect-final
system presence
Listar entradas de presença do sistema (RPC do Gateway).
Opções:
--json--url,--token,--timeout,--expect-final
Cron
Gerenciar tarefas agendadas (RPC do Gateway). Veja /automation/cron-jobs. Subcomandos:cron status [--json]cron list [--all] [--json](saída em tabela por padrão; use--jsonpara bruto)cron add(alias:create; requer--namee exatamente um de--at|--every|--cron, e exatamente um payload de--system-event|--message)cron edit <id>(patch de campos)cron rm <id>(aliases:remove,delete)cron enable <id>cron disable <id>cron runs --id <id> [--limit <n>]cron run <id> [--force]
cron aceitam --url, --token, --timeout, --expect-final.
Host de nó
node executa um host de nó headless ou o gerencia como um serviço em segundo plano. Veja
openclaw node.
Subcomandos:
node run --host <gateway-host> --port 18789node statusnode install [--host <gateway-host>] [--port <port>] [--tls] [--tls-fingerprint <sha256>] [--node-id <id>] [--display-name <name>] [--runtime <node|bun>] [--force]node uninstallnode stopnode restart
Nodes
nodes se comunica com o Gateway e direciona nós pareados. Veja /nodes.
Opções comuns:
--url,--token,--timeout,--json
nodes status [--connected] [--last-connected <duration>]nodes describe --node <id|name|ip>nodes list [--connected] [--last-connected <duration>]nodes pendingnodes approve <requestId>nodes reject <requestId>nodes rename --node <id|name|ip> --name <displayName>nodes invoke --node <id|name|ip> --command <command> [--params <json>] [--invoke-timeout <ms>] [--idempotency-key <key>]nodes run --node <id|name|ip> [--cwd <path>] [--env KEY=VAL] [--command-timeout <ms>] [--needs-screen-recording] [--invoke-timeout <ms>] <command...>(nó mac ou host de nó headless)nodes notify --node <id|name|ip> [--title <text>] [--body <text>] [--sound <name>] [--priority <passive|active|timeSensitive>] [--delivery <system|overlay|auto>] [--invoke-timeout <ms>](apenas mac)
nodes camera list --node <id|name|ip>nodes camera snap --node <id|name|ip> [--facing front|back|both] [--device-id <id>] [--max-width <px>] [--quality <0-1>] [--delay-ms <ms>] [--invoke-timeout <ms>]nodes camera clip --node <id|name|ip> [--facing front|back] [--device-id <id>] [--duration <ms|10s|1m>] [--no-audio] [--invoke-timeout <ms>]
nodes canvas snapshot --node <id|name|ip> [--format png|jpg|jpeg] [--max-width <px>] [--quality <0-1>] [--invoke-timeout <ms>]nodes canvas present --node <id|name|ip> [--target <urlOrPath>] [--x <px>] [--y <px>] [--width <px>] [--height <px>] [--invoke-timeout <ms>]nodes canvas hide --node <id|name|ip> [--invoke-timeout <ms>]nodes canvas navigate <url> --node <id|name|ip> [--invoke-timeout <ms>]nodes canvas eval [<js>] --node <id|name|ip> [--js <code>] [--invoke-timeout <ms>]nodes canvas a2ui push --node <id|name|ip> (--jsonl <path> | --text <text>) [--invoke-timeout <ms>]nodes canvas a2ui reset --node <id|name|ip> [--invoke-timeout <ms>]nodes screen record --node <id|name|ip> [--screen <index>] [--duration <ms|10s>] [--fps <n>] [--no-audio] [--out <path>] [--invoke-timeout <ms>]
nodes location get --node <id|name|ip> [--max-age <ms>] [--accuracy <coarse|balanced|precise>] [--location-timeout <ms>] [--invoke-timeout <ms>]
Navegador
CLI de controle do navegador (Chrome/Brave/Edge/Chromium dedicados). Vejaopenclaw browser e a Ferramenta de navegador.
Opções comuns:
--url,--token,--timeout,--json--browser-profile <name>
browser statusbrowser startbrowser stopbrowser reset-profilebrowser tabsbrowser open <url>browser focus <targetId>browser close [targetId]browser profilesbrowser create-profile --name <name> [--color <hex>] [--cdp-url <url>]browser delete-profile --name <name>
browser screenshot [targetId] [--full-page] [--ref <ref>] [--element <selector>] [--type png|jpeg]browser snapshot [--format aria|ai] [--target-id <id>] [--limit <n>] [--interactive] [--compact] [--depth <n>] [--selector <sel>] [--out <path>]
browser navigate <url> [--target-id <id>]browser resize <width> <height> [--target-id <id>]browser click <ref> [--double] [--button <left|right|middle>] [--modifiers <csv>] [--target-id <id>]browser type <ref> <text> [--submit] [--slowly] [--target-id <id>]browser press <key> [--target-id <id>]browser hover <ref> [--target-id <id>]browser drag <startRef> <endRef> [--target-id <id>]browser select <ref> <values...> [--target-id <id>]browser upload <paths...> [--ref <ref>] [--input-ref <ref>] [--element <selector>] [--target-id <id>] [--timeout-ms <ms>]browser fill [--fields <json>] [--fields-file <path>] [--target-id <id>]browser dialog --accept|--dismiss [--prompt <text>] [--target-id <id>] [--timeout-ms <ms>]browser wait [--time <ms>] [--text <value>] [--text-gone <value>] [--target-id <id>]browser evaluate --fn <code> [--ref <ref>] [--target-id <id>]browser console [--level <error|warn|info>] [--target-id <id>]browser pdf [--target-id <id>]
Busca de documentos
docs [query...]
Pesquisar no índice de documentos ao vivo.
TUI
tui
Abrir a UI de terminal conectada ao Gateway.
Opções:
--url <url>--token <token>--password <password>--session <key>--deliver--thinking <level>--message <text>--timeout-ms <ms>(padrãoagents.defaults.timeoutSeconds)--history-limit <n>