OpenClaw CLI 활용 가이드: 터미널에서 효율적으로 작업하기

명령어 페이지

글로벌 플래그

--dev: 상태를 ~/.openclaw-dev 아래로 격리하고 기본 포트를 변경해요.
--profile <name>: 상태를 ~/.openclaw-<name> 아래로 격리해요.
--container <name>: 실행 대상으로 지정할 컨테이너 이름을 설정해요.
--no-color: ANSI 컬러를 비활성화해요.
--update: openclaw update의 약칭이에요 (소스 설치 시에만 해당).
-V, --version, -v: 버전을 출력하고 종료해요.

출력 스타일링

ANSI 컬러와 진행 표시기는 TTY 세션에서만 렌더링돼요.
지원되는 터미널에서는 OSC-8 하이퍼링크가 클릭 가능한 링크로 표시되며, 그렇지 않은 경우에는 일반 URL로 표시돼요.
--json (및 지원되는 경우 --plain) 플래그를 사용하면 깔끔한 출력을 위해 스타일링을 비활성화해요.
--no-color는 ANSI 스타일링을 비활성화하며, NO_COLOR=1 환경 변수 설정도 적용돼요.
실행 시간이 긴 명령어는 진행 표시기를 보여줘요 (지원되는 경우 OSC 9;4 사용).

컬러 팔레트

OpenClaw는 CLI 출력에 ‘lobster’ 팔레트를 사용해요.

accent (#FF5A2D): 제목, 레이블, 주요 하이라이트.
accentBright (#FF7A3D): 명령어 이름, 강조.
accentDim (#D14A22): 보조 하이라이트 텍스트.
info (#FF8A5B): 정보성 값.
success (#2FBF71): 성공 상태.
warn (#FFB020): 경고, 폴백(fallback), 주의 사항.
error (#E23D2D): 에러, 실패.
muted (#8B7F77): 강조 해제, 메타데이터.

팔레트의 기준 소스는 src/terminal/palette.ts (“lobster palette”) 파일이에요.

명령 트리 (Command tree)

openclaw [--dev] [--profile <name>] <command>
  setup
  onboard
  configure
  config
    get
    set
    unset
    file
    schema
    validate
  completion
  doctor
  dashboard
  backup
    create
    verify
  security
    audit
  secrets
    reload
    audit
    configure
    apply
  reset
  uninstall
  update
    wizard
    status
  channels
    list
    status
    capabilities
    resolve
    logs
    add
    remove
    login
    logout
  directory
    self
    peers list
    groups list|members
  skills
    search
    install
    update
    list
    info
    check
  plugins
    list
    inspect
    install
    uninstall
    update
    enable
    disable
    doctor
    marketplace list
  memory
    status
    index
    search
  wiki
    status
    doctor
    init
    ingest
    compile
    lint
    search
    get
    apply
    bridge import
    unsafe-local import
    obsidian status|search|open|command|daily
  message
    send
    broadcast
    poll
    react
    reactions
    read
    edit
    delete
    pin
    unpin
    pins
    permissions
    search
    thread create|list|reply
    emoji list|upload
    sticker send|upload
    role info|add|remove
    channel info|list
    member info
    voice status
    event list|create
    timeout
    kick
    ban
  agent
  agents
    list
    add
    delete
    bindings
    bind
    unbind
    set-identity
  acp
  mcp
    serve
    list
    show
    set
    unset
  status
  health
  sessions
    cleanup
  tasks
    list
    audit
    maintenance
    show
    notify
    cancel
    flow list|show|cancel
  gateway
    call
    usage-cost
    health
    status
    probe
    discover
    install
    uninstall
    start
    stop
    restart
    run
  daemon
    status
    install
    uninstall
    start
    stop
    restart
  logs
  system
    event
    heartbeat last|enable|disable
    presence
  models
    list
    status
    set
    set-image
    aliases list|add|remove
    fallbacks list|add|remove|clear
    image-fallbacks list|add|remove|clear
    scan
  infer (alias: capability)
    list
    inspect
    model run|list|inspect|providers|auth login|logout|status
    image generate|edit|describe|describe-many|providers
    audio transcribe|providers
    tts convert|voices|providers|status|enable|disable|set-provider
    video generate|describe|providers
    web search|fetch|providers
    embedding create|providers
    auth add|login|login-github-copilot|setup-token|paste-token
    auth order get|set|clear
  sandbox
    list
    recreate
    explain
  cron
    status
    list
    add
    edit
    rm
    enable
    disable
    runs
    run
  nodes
    status
    describe
    list
    pending
    approve
    reject
    rename
    invoke
    notify
    push
    canvas snapshot|present|hide|navigate|eval
    canvas a2ui push|reset
    camera list|snap|clip
    screen record
    location get
  devices
    list
    remove
    clear
    approve
    reject
    rotate
    revoke
  node
    run
    status
    install
    uninstall
    stop
    restart
  approvals
    get
    set
    allowlist add|remove
  browser
    status
    start
    stop
    reset-profile
    tabs
    open
    focus
    close
    profiles
    create-profile
    delete-profile
    screenshot
    snapshot
    navigate
    resize
    click
    type
    press
    hover
    drag
    select
    upload
    fill
    dialog
    wait
    evaluate
    console
    pdf
  hooks
    list
    info
    check
    enable
    disable
    install
    update
  webhooks
    gmail setup|run
  pairing
    list
    approve
  qr
  clawbot
    qr
  docs
  dns
    setup
  tui

참고: plugins를 통해 openclaw voicecall 같은 최상위 명령어를 추가할 수도 있어요.

보안 (Security)

openclaw security audit — 일반적인 보안 실수를 방지하기 위해 config와 로컬 상태를 점검해요.
openclaw security audit --deep — Gateway를 실시간으로 조사해서 최대한 꼼꼼하게 확인해요.
openclaw security audit --fix — 안전한 기본 설정을 적용하고 상태나 config 권한을 더 엄격하게 관리해요.

비밀 정보 (Secrets)

`secrets`

SecretRefs와 관련된 런타임 및 config 위생 상태를 관리해요.

하위 명령어:

secrets reload
secrets audit
secrets configure
secrets apply --from <path>

secrets reload 옵션:

--url, --token, --timeout, --expect-final, --json

secrets audit 옵션:

--check
--allow-exec
--json

secrets configure 옵션:

--apply
--yes
--providers-only
--skip-provider-setup
--agent <id>
--allow-exec
--plan-out <path>
--json

secrets apply --from <path> 옵션:

--dry-run
--allow-exec
--json

참고 사항:

reload는 Gateway RPC이며, 해결에 실패하더라도 마지막으로 확인된 정상적인 런타임 스냅샷을 유지해요.
audit --check는 발견 사항이 있으면 0이 아닌 코드를 반환해요. 해결되지 않은 참조는 더 높은 우선순위의 코드를 사용하죠.
Dry-run 실행 체크는 기본적으로 건너뛰지만, --allow-exec를 사용하면 직접 선택해서 확인할 수 있어요.

플러그인 (Plugins)

확장 기능과 관련 설정을 관리하는 방법이에요:

openclaw plugins list — 설치된 플러그인을 확인해요 (기계용 출력이 필요하면 --json을 사용하세요).
openclaw plugins inspect <id> — 플러그인의 상세 정보를 보여줘요 (info 명령어도 똑같이 동작해요).
openclaw plugins install <path|.tgz|npm-spec|plugin@marketplace> — 플러그인을 설치해요 (또는 plugins.load.paths에 경로를 추가해요. 이미 설치된 대상을 덮어쓰려면 --force를 사용하세요).
openclaw plugins marketplace list <marketplace> — 설치하기 전에 마켓플레이스 항목들을 살펴봐요.
openclaw plugins enable <id> / disable <id> — plugins.entries.<id>.enabled 설정을 켜거나 꺼요.
openclaw plugins doctor — 플러그인 로드 오류를 보고해요.

대부분의 플러그인 변경 사항은 Gateway를 다시 시작해야 적용돼요. 자세한 내용은 /plugin 문서를 참고해 보세요.

메모리

MEMORY.md와 memory/*.md 파일들을 대상으로 Vector search를 수행할 수 있어요.

openclaw memory status — 인덱스 통계를 보여줘요. Vector와 Embedding의 준비 상태를 확인하려면 --deep을, 오래된 recall이나 promotion 아티팩트를 수리하려면 --fix를 사용하세요.
openclaw memory index — 메모리 파일들을 다시 인덱싱해요.
openclaw memory search "<query>" (또는 --query "<query>") — 메모리에 대해 시맨틱 검색을 수행해요.
openclaw memory promote — 단기 recall의 순위를 매기고, 선택적으로 상위 항목을 MEMORY.md에 추가해요.

샌드박스

격리된 Agent 실행을 위한 Sandbox 런타임을 관리해요. 자세한 내용은 /cli/sandbox를 확인해 보세요.

서브 명령어:

sandbox list [--browser] [--json]
sandbox recreate [--all] [--session <key>] [--agent <id>] [--browser] [--force]
sandbox explain [--session <key>] [--agent <id>] [--json]

참고 사항:

sandbox recreate는 기존 런타임을 제거하므로, 다음 사용 시 현재 설정을 기반으로 다시 초기화돼요.
ssh나 OpenShell remote 백엔드의 경우, recreate를 실행하면 선택된 범위의 표준 원격 워크스페이스가 삭제돼요.

채팅 슬래시 명령어

채팅 메시지에서 /... 형태의 명령어(텍스트 및 네이티브)를 지원해요. /tools/slash-commands에서 더 자세한 내용을 볼 수 있어요.

주요 기능:

빠른 진단을 위한 /status.
영구적인 설정 변경을 위한 /config.
런타임 전용 설정 오버라이드를 위한 /debug (디스크가 아닌 메모리에만 적용되며, commands.debug: true 설정이 필요해요).

설정 및 온보딩

`completion`

쉘 완성(shell-completion) 스크립트를 생성하고, 선택적으로 사용 중인 쉘 프로필에 설치해요.

옵션:

-s, --shell <zsh|bash|powershell|fish>
-i, --install
--write-state
-y, --yes

참고 사항:

--install이나 --write-state 없이 실행하면 스크립트를 stdout으로 출력해요.
--install은 쉘 프로필에 OpenClaw Completion 블록을 작성하고 OpenClaw 상태 디렉터리의 캐시된 스크립트를 가리키도록 설정해요.

`setup`

설정과 워크스페이스를 초기화해요.

옵션:

--workspace <dir>: Agent 워크스페이스 경로 (기본값 ~/.openclaw/workspace).
--wizard: 온보딩을 실행해요.
--non-interactive: 프롬프트 없이 온보딩을 실행해요.
--mode <local|remote>: 온보딩 모드예요.
--remote-url <url>: 원격 Gateway URL이에요.
--remote-token <token>: 원격 Gateway 토큰이에요.

온보딩 플래그(--non-interactive, --mode, --remote-url, --remote-token)가 하나라도 있으면 온보딩이 자동으로 실행돼요.

`onboard`

Gateway, 워크스페이스, Skills를 위한 대화형 온보딩이에요.

옵션:

--workspace <dir>
--reset (온보딩 전에 설정, 자격 증명, 세션을 초기화해요)
--reset-scope <config|config+creds+sessions|full> (기본값은 config+creds+sessions이며, 워크스페이스까지 삭제하려면 full을 사용하세요)
--non-interactive
--mode <local|remote>
--flow <quickstart|advanced|manual> (manual은 advanced의 별칭이에요)
--auth-choice <choice>: 여기서 <choice>는 다음 중 하나예요: chutes, deepseek-api-key, openai-codex, openai-api-key, openrouter-api-key, kilocode-api-key, litellm-api-key, ai-gateway-api-key, cloudflare-ai-gateway-api-key, moonshot-api-key, moonshot-api-key-cn, kimi-code-api-key, synthetic-api-key, venice-api-key, together-api-key, huggingface-api-key, apiKey, gemini-api-key, google-gemini-cli, zai-api-key, zai-coding-global, zai-coding-cn, zai-global, zai-cn, xiaomi-api-key, minimax-global-oauth, minimax-global-api, minimax-cn-oauth, minimax-cn-api, opencode-zen, opencode-go, github-copilot, copilot-proxy, xai-api-key, mistral-api-key, volcengine-api-key, byteplus-api-key, qianfan-api-key, qwen-standard-api-key-cn, qwen-standard-api-key, qwen-api-key-cn, qwen-api-key, modelstudio-standard-api-key-cn, modelstudio-standard-api-key, modelstudio-api-key-cn, modelstudio-api-key, custom-api-key, skip
Qwen 관련 참고: qwen-*가 표준 auth-choice 제품군이에요. modelstudio-* ID는 하위 호환성을 위한 별칭으로만 허용돼요.
--secret-input-mode <plaintext|ref> (기본값 plaintext. 일반 텍스트 키 대신 공급자 기본 환경 변수 참조를 저장하려면 ref를 사용하세요)
--anthropic-api-key <key>
--openai-api-key <key>
--mistral-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>
--opencode-go-api-key <key>
--custom-base-url <url> (비대화형 모드; --auth-choice custom-api-key와 함께 사용)
--custom-model-id <id> (비대화형 모드; --auth-choice custom-api-key와 함께 사용)
--custom-api-key <key> (비대화형 모드; 선택 사항; --auth-choice custom-api-key와 함께 사용하며 생략 시 CUSTOM_API_KEY를 사용해요)
--custom-provider-id <id> (비대화형 모드; 선택 사항인 커스텀 공급자 ID예요)
--custom-compatibility <openai|anthropic> (비대화형 모드; 선택 사항; 기본값 openai)
--gateway-port <port>
--gateway-bind <loopback|lan|tailnet|auto|custom>
--gateway-auth <token|password>
--gateway-token <token>
--gateway-token-ref-env <name> (비대화형 모드; gateway.auth.token을 환경 변수 SecretRef로 저장해요. 해당 환경 변수가 설정되어 있어야 하며, --gateway-token과 함께 사용할 수 없어요)
--gateway-password <password>
--remote-url <url>
--remote-token <token>
--tailscale <off|serve|funnel>
--tailscale-reset-on-exit
--install-daemon
--no-install-daemon (별칭: --skip-daemon)
--daemon-runtime <node|bun>
--skip-channels
--skip-skills
--skip-search
--skip-health
--skip-ui
--cloudflare-ai-gateway-account-id <id>
--cloudflare-ai-gateway-gateway-id <id>
--node-manager <npm|pnpm|bun> (Skills를 위한 온보딩 노드 매니저 설정이에요. pnpm을 추천하며 bun도 지원해요)
--json

`configure`

대화형 설정 마법사예요 (모델, 채널, Skills, Gateway).

옵션:

--section <section> (마법사 범위를 특정 섹션으로 제한해요. 여러 번 사용할 수 있어요)

`config`

비대화형 설정 도우미예요 (get/set/unset/file/schema/validate). 서브 명령어 없이 openclaw config를 실행하면 마법사가 시작돼요.

서브 명령어:

config get <path>: 설정 값을 출력해요 (dot/bracket 경로 사용).
config set: 네 가지 할당 모드를 지원해요:
- value 모드: config set <path> <value> (JSON5 또는 문자열 파싱)
- SecretRef 빌더 모드: config set <path> --ref-provider <provider> --ref-source <source> --ref-id <id>
- provider 빌더 모드: config set secrets.providers.<alias> --provider-source <env|file|exec> ...
- 배치 모드: config set --batch-json '<json>' 또는 config set --batch-file <path>
config set --dry-run: openclaw.json에 쓰지 않고 할당 내용을 검증해요 (exec SecretRef 체크는 기본적으로 건너뛰어요).
config set --allow-exec --dry-run: exec SecretRef dry-run 체크를 허용해요 (공급자 명령어가 실행될 수 있어요).
config set --dry-run --json: 기계 읽기 가능한 dry-run 결과를 출력해요 (체크 결과, 작업 내용, 참조 확인 여부, 에러 등).
config set --strict-json: 경로/값 입력 시 JSON5 파싱을 요구해요. --json은 dry-run 출력 모드 이외에서 엄격한 파싱을 위한 레거시 별칭으로 유지돼요.
config unset <path>: 값을 제거해요.
config file: 활성화된 설정 파일 경로를 출력해요.
config schema: openclaw.json을 위해 생성된 JSON 스키마를 출력해요. 중첩된 객체, 와일드카드, 배열 아이템 등에 대한 메타데이터와 플러그인/채널 스키마 메타데이터가 포함돼요.
config validate: Gateway를 시작하지 않고 현재 설정을 스키마에 따라 검증해요.
config validate --json: 기계 읽기 가능한 JSON 결과를 출력해요.

`doctor`

상태 점검 및 빠른 복구 도구예요 (설정, Gateway, 레거시 서비스).

옵션:

--no-workspace-suggestions: 워크스페이스 메모리 힌트를 비활성화해요.
--yes: 프롬프트 없이 기본값을 수락해요 (headless).
--non-interactive: 프롬프트를 건너뛰고 안전한 마이그레이션만 적용해요.
--deep: 추가적인 Gateway 설치 여부를 확인하기 위해 시스템 서비스를 스캔해요.
--repair (별칭: --fix): 감지된 문제에 대해 자동 복구를 시도해요.
--force: 엄격하게 필요하지 않더라도 복구를 강제해요.
--generate-gateway-token: 새로운 Gateway 인증 토큰을 생성해요.

`dashboard`

현재 토큰을 사용하여 Control UI를 열어요.

옵션:

--no-open: URL을 출력하지만 브라우저를 실행하지는 않아요.

참고 사항:

SecretRef로 관리되는 Gateway 토큰의 경우, 터미널 출력이나 브라우저 실행 인자에 비밀 정보가 노출되지 않도록 토큰이 포함되지 않은 URL을 출력하거나 열어요.

`update`

설치된 CLI를 업데이트해요.

루트 옵션:

--json
--no-restart
--dry-run
--channel <stable|beta|dev>
--tag <dist-tag|version|spec>
--timeout <seconds>
--yes

서브 명령어:

update status
update wizard

update status 옵션:

--json
--timeout <seconds>

update wizard 옵션:

--timeout <seconds>

참고 사항:

openclaw --update는 내부적으로 openclaw update로 변경되어 실행돼요.

`backup`

OpenClaw 상태를 위한 로컬 백업 아카이브를 생성하고 검증해요.

서브 명령어:

backup create
backup verify <archive>

backup create 옵션:

--output <path>
--json
--dry-run
--verify
--only-config
--no-include-workspace

backup verify <archive> 옵션:

--json

채널 헬퍼 (Channel helpers)

`channels`

채팅 채널 계정(WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/Microsoft Teams)을 관리해요.

사용 가능한 서브 커맨드는 다음과 같아요:

channels list: 설정된 채널과 인증 프로필을 보여줘요.
channels status: Gateway 연결 상태와 채널 상태를 확인해요. (--probe를 사용하면 Gateway가 연결 가능할 때 계정별로 실시간 프로브/감사 체크를 실행해요. 연결이 안 되면 설정 기반의 채널 요약만 보여줘요. 더 넓은 범위의 Gateway 상태 확인이 필요하다면 openclaw health나 openclaw status --deep을 사용해 보세요.)
팁: channels status는 일반적인 설정 오류가 감지되면 해결 방법이 포함된 경고를 출력하고 openclaw doctor를 안내해 줘요.
channels logs: Gateway 로그 파일에서 최근 채널 로그를 보여줘요.
channels add: 플래그 없이 실행하면 마법사 스타일의 설정을 시작하고, 플래그를 전달하면 비대화형 모드로 전환돼요.
- 단일 계정 상위 설정을 사용하는 채널에 기본값이 아닌 계정을 추가할 때, OpenClaw는 새 계정을 쓰기 전에 계정 범위의 값들을 채널 계정 맵으로 승격시켜요. 대부분의 채널은 accounts.default를 사용하며, Matrix는 기존의 이름이 지정된 타겟이나 기본 타겟을 그대로 유지할 수 있어요.
- 비대화형 channels add는 바인딩을 자동으로 생성하거나 업그레이드하지 않아요. 채널 전용 바인딩은 계속 기본 계정과 매칭돼요.
channels remove: 기본적으로 비활성화되어 있어요. --delete를 전달하면 확인 절차 없이 설정 항목을 삭제해요.
channels login: 대화형 채널 로그인 기능을 제공해요 (WhatsApp Web 전용).
channels logout: 채널 세션에서 로그아웃해요 (지원되는 경우).

공통 옵션:

--channel <name>: whatsapp|telegram|discord|googlechat|slack|mattermost|signal|imessage|msteams
--account <id>: 채널 계정 id (기본값 default)
--name <label>: 계정의 표시 이름

channels login 옵션:

--channel <channel> (기본값 whatsapp, whatsapp/web 지원)
--account <id>
--verbose

channels logout 옵션:

--channel <channel> (기본값 whatsapp)
--account <id>

channels list 옵션:

--no-usage: 모델 프로바이더의 사용량/쿼터 스냅샷을 건너뛰어요 (OAuth/API 기반만 해당).
--json: JSON으로 출력해요 (--no-usage가 설정되지 않으면 사용량 정보가 포함돼요).

channels status 옵션:

--probe
--timeout <ms>
--json

channels capabilities 옵션:

--channel <name>
--account <id> (--channel과 함께 사용)
--target <dest>
--timeout <ms>
--json

channels resolve 옵션:

<entries...>
--channel <name>
--account <id>
--kind <auto|user|group>
--json

channels logs 옵션:

--channel <name|all> (기본값 all)
--lines <n> (기본값 200)
--json

참고 사항:

channels login은 --verbose를 지원해요.
channels capabilities --account는 --channel이 설정된 경우에만 적용돼요.
channels status --probe는 채널 지원 여부에 따라 전송 상태와 함께 works, probe failed, audit ok, audit failed 같은 프로브/감사 결과를 보여줄 수 있어요.

더 자세한 내용: /concepts/oauth

예시:

openclaw channels add --channel telegram --account alerts --name "Alerts Bot" --token $TELEGRAM_BOT_TOKEN
openclaw channels add --channel discord --account work --name "Work Bot" --token $DISCORD_BOT_TOKEN
openclaw channels remove --channel discord --account work --delete
openclaw channels status --probe
openclaw status --deep

`directory`

디렉토리 기능을 제공하는 채널에서 본인, 피어(peer), 그룹 ID를 조회해요. 자세한 내용은 openclaw directory를 참고하세요.

공통 옵션:

--channel <name>
--account <id>
--json

서브 커맨드:

directory self
directory peers list [--query <text>] [--limit <n>]
directory groups list [--query <text>] [--limit <n>]
directory groups members --group-id <id> [--limit <n>]

`skills`

사용 가능한 스킬 목록과 상세 정보, 준비 상태를 확인해요.

서브 커맨드:

skills search [query...]: ClawHub 스킬을 검색해요.
skills search --limit <n> --json: 검색 결과를 제한하거나 기계 읽기 가능한 형식으로 출력해요.
skills install <slug>: ClawHub의 스킬을 활성 워크스페이스에 설치해요.
skills install <slug> --version <version>: 특정 ClawHub 버전을 설치해요.
skills install <slug> --force: 기존 워크스페이스의 스킬 폴더를 덮어써요.
skills update <slug|--all>: 추적 중인 ClawHub 스킬을 업데이트해요.
skills list: 스킬 목록을 보여줘요 (서브 커맨드가 없을 때의 기본값).
skills list --json: 스킬 인벤토리를 JSON 형식으로 출력해요.
skills list --verbose: 누락된 요구 사항을 테이블에 포함해요.
skills info <name>: 특정 스킬의 상세 정보를 보여줘요.
skills info <name> --json: 상세 정보를 JSON 형식으로 출력해요.
skills check: 준비된 요구 사항과 누락된 요구 사항의 요약을 보여줘요.
skills check --json: 준비 상태를 JSON 형식으로 출력해요.

옵션:

--eligible: 준비된 스킬만 보여줘요.
--json: 스타일 없이 JSON으로 출력해요.
-v, --verbose: 누락된 요구 사항의 상세 내용을 포함해요.

팁: ClawHub 기반 스킬에는 openclaw skills search, openclaw skills install, openclaw skills update를 사용하세요.

`pairing`

채널 간의 DM 페어링 요청을 승인해요.

서브 커맨드:

pairing list [channel] [--channel <channel>] [--account <id>] [--json]
pairing approve <channel> <code> [--account <id>] [--notify]
pairing approve --channel <channel> [--account <id>] <code> [--notify]

참고 사항:

페어링이 가능한 채널이 딱 하나만 설정되어 있다면, pairing approve <code> 형식도 가능해요.
list와 approve 모두 다중 계정 채널을 위해 --account <id>를 지원해요.

`devices`

Gateway 디바이스 페어링 항목과 역할별 디바이스 토큰을 관리해요.

서브 커맨드:

devices list [--json]
devices approve [requestId] [--latest]
devices reject <requestId>
devices remove <deviceId>
devices clear --yes [--pending]
devices rotate --device <id> --role <role> [--scope <scope...>]
devices revoke --device <id> --role <role>

참고 사항:

직접 페어링 스코프를 사용할 수 없는 경우, devices list와 devices approve는 로컬 루프백의 로컬 페어링 파일로 대체될 수 있어요.
devices approve는 토큰을 생성하기 전에 명시적인 요청 ID가 필요해요. requestId를 생략하거나 --latest를 전달하면 가장 최근의 대기 중인 요청만 미리 보여줘요.
저장된 토큰으로 재연결할 때는 토큰에 캐시된 승인 스코프를 재사용해요. 명시적으로 devices rotate --scope ...를 실행하면 향후 재연결을 위해 저장된 스코프 세트를 업데이트해요.
devices rotate와 devices revoke는 JSON 페이로드를 반환해요.

`qr`

현재 Gateway 설정에서 모바일 페어링용 QR 코드와 설정 코드를 생성해요. 자세한 내용은 openclaw qr를 참고하세요.

옵션:

--remote
--url <url>
--public-url <url>
--token <token>
--password <password>
--setup-code-only
--no-ascii
--json

참고 사항:

--token과 --password는 동시에 사용할 수 없어요.
설정 코드는 수명이 짧은 부트스트랩 토큰을 포함하며, 공유 Gateway 토큰/비밀번호가 아니에요.
내장된 부트스트랩 핸드오프는 기본 노드 토큰을 scopes: [] 상태로 유지해요.
전달된 모든 운영자(operator) 부트스트랩 토큰은 operator.approvals, operator.read, operator.talk.secrets, operator.write 권한으로 제한돼요.
부트스트랩 스코프 체크는 역할(role) 접두사가 붙으므로, 운영자 허용 목록은 운영자 요청만 충족해요. 운영자가 아닌 역할은 여전히 해당 역할 접두사 아래의 스코프가 필요해요.
--remote는 gateway.remote.url이나 활성화된 Tailscale Serve/Funnel URL을 사용할 수 있어요.
스캔 후에는 openclaw devices list / openclaw devices approve <requestId>로 요청을 승인하세요.

`clawbot`

레거시 별칭 네임스페이스예요. 현재는 openclaw qr로 매핑되는 openclaw clawbot qr을 지원해요.

`hooks`

내부 에이전트 Hook을 관리해요.

서브 커맨드:

hooks list
hooks info <name>
hooks check
hooks enable <name>
hooks disable <name>
hooks install <path-or-spec> (openclaw plugins install의 지원 중단된 별칭)
hooks update [id] (openclaw plugins update의 지원 중단된 별칭)

공통 옵션:

--json
--eligible
-v, --verbose

참고 사항:

플러그인으로 관리되는 Hook은 openclaw hooks를 통해 활성화하거나 비활성화할 수 없어요. 대신 해당 플러그인을 활성화하거나 비활성화하세요.
hooks install과 hooks update는 호환성을 위해 유지되지만, 지원 중단 경고를 출력하고 플러그인 커맨드로 전달돼요.

`webhooks`

Webhook 헬퍼예요. 현재 내장된 기능은 Gmail Pub/Sub 설정 및 러너(runner)예요:

webhooks gmail setup
webhooks gmail run

`webhooks gmail`

Gmail Pub/Sub Hook 설정 및 러너예요. Gmail Pub/Sub을 참고하세요.

서브 커맨드:

webhooks gmail setup (--account <email>이 필요하며, --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 (동일한 플래그들에 대해 런타임 오버라이드를 지원해요)

참고 사항:

setup은 Gmail 감시(watch)와 OpenClaw 방향의 푸시 경로를 설정해요.
run은 선택적인 런타임 오버라이드와 함께 로컬 Gmail 감시/갱신 루프를 시작해요.

`dns`

광역 탐색(Wide-area discovery) DNS 헬퍼(CoreDNS + Tailscale)예요. 현재 내장된 기능은 다음과 같아요:

dns setup [--domain <domain>] [--apply]

`dns setup`

광역 탐색 DNS 헬퍼(CoreDNS + Tailscale)예요. /gateway/discovery를 참고하세요.

옵션:

--domain <domain>
--apply: CoreDNS 설정을 설치/업데이트해요 (sudo 권한이 필요하며 macOS만 지원해요).

참고 사항:

--apply가 없으면 권장되는 OpenClaw + Tailscale DNS 설정을 출력하는 계획 도우미 역할을 해요.
--apply는 현재 Homebrew CoreDNS를 사용하는 macOS만 지원해요.

메시징 + 에이전트 (Messaging + agent)

`message`

통합 아웃바운드 메시징 및 채널 액션 기능이에요.

참고: /cli/message

서브 커맨드:

message send|poll|react|reactions|read|edit|delete|pin|unpin|pins|permissions|search|timeout|kick|ban
message thread <create|list|reply>
message emoji <list|upload>
message sticker <send|upload>
message role <info|add|remove>
message channel <info|list>
message member info
message voice status
message 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`

Gateway를 통해(또는 --local로 내장 실행) 에이전트 턴을 한 번 실행해요.

최소 하나 이상의 세션 선택자(--to, --session-id, --agent 중 하나)를 전달해야 해요.

필수 사항:

-m, --message <text>

옵션:

-t, --to <dest> (세션 키 및 선택적 전송용)
--session-id <id>
--agent <id> (에이전트 id, 라우팅 바인딩을 무시해요)
--thinking <off|minimal|low|medium|high|xhigh> (프로바이더마다 지원 여부가 다르며, CLI 레벨에서 모델별로 제한되지 않아요)
--verbose <on|off>
--channel <channel> (전송 채널, 생략하면 메인 세션 채널을 사용해요)
--reply-to <target> (세션 라우팅과 별개로 전송 타겟을 직접 지정해요)
--reply-channel <channel> (전송 채널 직접 지정)
--reply-account <id> (전송 계정 id 직접 지정)
--local (내장 실행, 플러그인 레지스트리가 먼저 로드돼요)
--deliver
--json
--timeout <seconds>

참고 사항:

Gateway 모드에서 Gateway 요청이 실패하면 내장 에이전트로 대체되어 실행돼요.
--local을 사용해도 플러그인 레지스트리를 미리 로드하므로, 플러그인이 제공하는 프로바이더, 도구, 채널을 내장 실행 중에 계속 사용할 수 있어요.
--channel, --reply-channel, --reply-account는 라우팅이 아닌 답장 전송에 영향을 줘요.

`agents`

격리된 에이전트(워크스페이스 + 인증 + 라우팅)를 관리해요.

서브 커맨드 없이 openclaw agents를 실행하면 openclaw agents list와 동일해요.

`agents list`

설정된 에이전트 목록을 보여줘요.

옵션:

--json
--bindings

`agents add [name]`

새로운 격리된 에이전트를 추가해요. 플래그(또는 --non-interactive)를 전달하지 않으면 안내 마법사가 실행돼요. 비대화형 모드에서는 --workspace가 필수예요.

옵션:

--workspace <dir>
--model <id>
--agent-dir <dir>
--bind <channel[:accountId]> (반복 가능)
--non-interactive
--json

바인딩 사양은 channel[:accountId] 형식을 사용해요. accountId를 생략하면 OpenClaw가 채널 기본값이나 플러그인 Hook을 통해 계정 범위를 결정할 수 있어요. 그렇지 않으면 명시적인 계정 범위가 없는 채널 바인딩이 돼요. 명시적인 추가 플래그를 전달하면 커맨드가 비대화형 경로로 전환돼요. main은 예약된 이름이므로 새 에이전트 id로 사용할 수 없어요.

`agents bindings`

라우팅 바인딩 목록을 보여줘요.

옵션:

--agent <id>
--json

`agents bind`

에이전트에 라우팅 바인딩을 추가해요.

옵션:

--agent <id> (기본값은 현재 기본 에이전트)
--bind <channel[:accountId]> (반복 가능)
--json

`agents unbind`

에이전트의 라우팅 바인딩을 제거해요.

옵션:

--agent <id> (기본값은 현재 기본 에이전트)
--bind <channel[:accountId]> (반복 가능)
--all
--json

--all과 --bind 중 하나만 사용하세요.

`agents delete <id>`

에이전트를 삭제하고 해당 워크스페이스와 상태를 정리해요.

옵션:

--force
--json

참고 사항:

main은 삭제할 수 없어요.
--force가 없으면 대화형 확인 절차가 필요해요.

`agents set-identity`

에이전트의 정체성(이름/테마/이모지/아바타)을 업데이트해요.

옵션:

--agent <id>
--workspace <dir>
--identity-file <path>
--from-identity
--name <name>
--theme <theme>
--emoji <emoji>
--avatar <value>
--json

참고 사항:

--agent나 --workspace를 사용하여 대상 에이전트를 선택할 수 있어요.
명시적인 정체성 필드가 제공되지 않으면 커맨드는 IDENTITY.md 파일을 읽어요.

`acp`

IDE를 Gateway에 연결하는 ACP 브릿지를 실행해요.

루트 옵션:

--url <url>
--token <token>
--token-file <path>
--password <password>
--password-file <path>
--session <key>
--session-label <label>
--require-existing
--reset-session
--no-prefix-cwd
--provenance <off|meta|meta+receipt>
--verbose

`acp client`

브릿지 디버깅을 위한 대화형 ACP 클라이언트예요.

옵션:

--cwd <dir>
--server <command>
--server-args <args...>
--server-verbose
--verbose

전체 동작, 보안 참고 사항 및 예시는 acp를 참고하세요.

`mcp`

저장된 MCP 서버 정의를 관리하고 OpenClaw 채널을 MCP stdio로 노출해요.

`mcp serve`

라우팅된 OpenClaw 채널 대화를 MCP stdio로 노출해요.

옵션:

--url <url>
--token <token>
--token-file <path>
--password <password>
--password-file <path>
--claude-channel-mode <auto|on|off>
--verbose

`mcp list`

저장된 MCP 서버 정의 목록을 보여줘요.

옵션:

--json

`mcp show [name]`

저장된 특정 MCP 서버 정의나 전체 MCP 서버 객체를 보여줘요.

옵션:

--json

`mcp set <name> <value>`

JSON 객체로부터 MCP 서버 정의를 저장해요.

`mcp unset <name>`

저장된 MCP 서버 정의를 제거해요.

`approvals`

실행 승인(exec approvals)을 관리해요. 별칭: exec-approvals.

`approvals get`

실행 승인 스냅샷과 유효한 정책을 가져와요.

옵션:

--node <node>
--gateway
--json
openclaw nodes의 노드 RPC 옵션들

`approvals set`

파일이나 stdin의 JSON으로 실행 승인 설정을 교체해요.

옵션:

--node <node>
--gateway
--file <path>
--stdin
--json
openclaw nodes의 노드 RPC 옵션들

`approvals allowlist add|remove`

에이전트별 실행 허용 목록(allowlist)을 편집해요.

옵션:

--node <node>
--gateway
--agent <id> (기본값 *)
--json
openclaw nodes의 노드 RPC 옵션들

`status`

연결된 세션의 상태와 최근 수신자를 보여줘요.

옵션:

--json
--all (전체 진단, 읽기 전용, 복사 가능)
--deep (Gateway에 실시간 상태 프로브를 요청하며, 지원되는 경우 채널 프로브도 포함해요)
--usage (모델 프로바이더 사용량/쿼터를 보여줘요)
--timeout <ms>
--verbose
--debug (--verbose의 별칭)

참고 사항:

개요에는 가능한 경우 Gateway 및 노드 호스트 서비스 상태가 포함돼요.
--usage는 정규화된 프로바이더 사용량 윈도우를 X% 남음 형식으로 출력해요.

사용량 추적 (Usage tracking)

OpenClaw는 OAuth/API 자격 증명이 있는 경우 프로바이더 사용량/쿼터 정보를 표시할 수 있어요.

표시되는 위치:

/status (가능한 경우 짧은 프로바이더 사용량 라인을 추가해요)
openclaw status --usage (전체 프로바이더 상세 내역을 출력해요)
macOS 메뉴 바 (Context 아래의 Usage 섹션)

참고 사항:

데이터는 프로바이더의 사용량 엔드포인트에서 직접 가져와요 (추정치 아님).
사람이 읽기 쉬운 출력은 모든 프로바이더에 대해 X% 남음으로 정규화돼요.
현재 사용량 윈도우를 지원하는 프로바이더: Anthropic, GitHub Copilot, Gemini CLI, OpenAI Codex, MiniMax, Xiaomi, z.ai.
MiniMax 참고: 원시 usage_percent / usagePercent는 남은 쿼터를 의미하므로 OpenClaw는 이를 반전시켜서 표시해요. 개수 기반 필드가 있으면 그것이 우선순위를 가져요. model_remains 응답은 채팅 모델 항목을 선호하며, 필요한 경우 타임스탬프에서 윈도우 레이블을 도출하고 플랜 레이블에 모델 이름을 포함해요.
사용량 인증은 가능한 경우 프로바이더 전용 Hook에서 가져오며, 그렇지 않으면 인증 프로필, 환경 변수 또는 설정에서 일치하는 OAuth/API 키 자격 증명을 사용해요. 아무것도 확인되지 않으면 사용량 정보는 숨겨져요.
상세 내용: Usage tracking을 참고하세요.

`health`

실행 중인 Gateway에서 상태 정보를 가져와요.

옵션:

--json
--timeout <ms>
--verbose (실시간 프로브를 강제하고 Gateway 연결 상세 정보를 출력해요)
--debug (--verbose의 별칭)

참고 사항:

기본 health는 최신 상태로 캐시된 Gateway 스냅샷을 반환할 수 있어요.
health --verbose는 실시간 프로브를 강제하며, 설정된 모든 계정과 에이전트에 대해 사람이 읽기 쉬운 출력을 확장해서 보여줘요.

`sessions`

저장된 대화 세션 목록을 보여줘요.

옵션:

--json
--verbose
--store <path>
--active <minutes>
--agent <id> (에이전트별로 세션 필터링)
--all-agents (모든 에이전트의 세션을 표시)

서브 커맨드:

sessions cleanup — 만료되거나 고립된 세션을 제거해요.

참고 사항:

sessions cleanup은 대화 기록 파일이 사라진 항목을 정리하기 위한 --fix-missing 옵션도 지원해요.

초기화 및 삭제

`reset`

로컬 설정이나 상태를 초기화해요. CLI 설치 상태는 그대로 유지됩니다.

Options:

--scope <config|config+creds+sessions|full>
--yes
--non-interactive
--dry-run

Notes:

--non-interactive를 사용하려면 --scope와 --yes가 반드시 필요해요.

`uninstall`

Gateway 서비스와 로컬 데이터를 삭제해요. CLI는 삭제되지 않고 남습니다.

Options:

--service
--state
--workspace
--app
--all
--yes
--non-interactive
--dry-run

Notes:

--non-interactive를 사용하려면 --yes와 명시적인 scope(또는 --all)가 필요해요.
--all 옵션은 서비스, 상태, workspace, app을 모두 한꺼번에 삭제합니다.

`tasks`

여러 에이전트에서 실행되는 background task 목록을 확인하고 관리해요.

tasks list — 활성 상태이거나 최근에 실행된 task 목록을 보여줍니다.
tasks show <id> — 특정 task 실행에 대한 상세 정보를 확인해요.
tasks notify <id> — task 실행에 대한 알림 정책을 변경합니다.
tasks cancel <id> — 실행 중인 task를 취소해요.
tasks audit — 운영상의 문제(지연, 유실, 전달 실패 등)를 찾아냅니다.
tasks maintenance [--apply] [--json] — task 및 TaskFlow 정리/조정 작업을 미리 보거나 적용해요. (ACP/subagent 자식 세션, 활성 cron job, 라이브 CLI 실행 등 포함)
tasks flow list — 활성 상태이거나 최근에 실행된 Task Flow 목록을 보여줍니다.
tasks flow show <lookup> — ID나 lookup key로 flow를 조사해요.
tasks flow cancel <lookup> — 실행 중인 flow와 해당 flow의 활성 task들을 취소합니다.

`flows`

레거시 문서용 단축 명령어예요. Flow 관련 명령어는 이제 openclaw tasks flow 아래에 위치합니다.

tasks flow list [--json]
tasks flow show <lookup>
tasks flow cancel <lookup>

Gateway

`gateway`

WebSocket Gateway를 실행해요.

Options:

--port <port>
--bind <loopback|tailnet|lan|auto|custom>
--token <token>
--auth <token|password>
--password <password>
--password-file <path>
--tailscale <off|serve|funnel>
--tailscale-reset-on-exit
--allow-unconfigured
--dev
--reset (개발용 설정 + credentials + sessions + workspace 초기화)
--force (포트에서 실행 중인 기존 listener를 강제 종료)
--verbose
--cli-backend-logs
--ws-log <auto|full|compact>
--compact (--ws-log compact와 동일)
--raw-stream
--raw-stream-path <path>

`gateway service`

Gateway 서비스(launchd/systemd/schtasks)를 관리해요.

Subcommands:

gateway status (기본적으로 Gateway RPC를 조사합니다)
gateway install (서비스 설치)
gateway uninstall
gateway start
gateway stop
gateway restart

Notes:

gateway status는 서비스에 설정된 포트/설정을 사용하여 기본적으로 Gateway RPC를 조사해요. (--url/--token/--password로 덮어쓸 수 있습니다)
gateway status는 스크립트 작업을 위해 --no-probe, --deep, --require-rpc, --json 옵션을 지원해요.
gateway status는 감지 가능한 경우 레거시 또는 추가 Gateway 서비스도 함께 표시합니다. (--deep 옵션 사용 시 시스템 레벨 스캔 추가) Profile 이름이 지정된 OpenClaw 서비스는 기본 서비스로 취급되며 “extra”로 표시되지 않아요.
로컬 CLI 설정이 없거나 유효하지 않은 경우에도 진단을 위해 gateway status를 사용할 수 있습니다.
gateway status는 확인된 로그 파일 경로, CLI와 서비스 간의 설정 경로/유효성 스냅샷, 그리고 조사 대상 URL을 출력해요.
현재 명령어 경로에서 Gateway 인증 SecretRefs가 해결되지 않은 경우, gateway status --json은 조사 연결이나 인증이 실패했을 때만 rpc.authWarning을 보고합니다. (조사에 성공하면 경고가 표시되지 않아요)
Linux systemd 설치 환경에서 status의 token-drift 체크는 Environment=와 EnvironmentFile= 유닛 소스를 모두 포함합니다.
gateway install|uninstall|start|stop|restart 명령어는 스크립트 활용을 위해 --json을 지원해요. (기본 출력은 읽기 편한 형식을 유지합니다)
gateway install은 기본적으로 Node 런타임을 사용해요. bun은 권장하지 않습니다. (WhatsApp/Telegram 버그 발생 가능성)
gateway install 옵션: --port, --runtime, --token, --force, --json.

`daemon`

Gateway 서비스 관리 명령어의 레거시 별칭이에요. /cli/daemon을 참고하세요.

Subcommands:

daemon status
daemon install
daemon uninstall
daemon start
daemon stop
daemon restart

Common options:

status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
install: --port, --runtime <node|bun>, --token, --force, --json
uninstall|start|stop|restart: --json

`logs`

RPC를 통해 Gateway 파일 로그를 실시간으로 확인(tail)해요.

Options:

--limit <n>: 반환할 로그 라인의 최대 개수
--max-bytes <n>: 로그 파일에서 읽어올 최대 바이트 수
--follow: 로그 파일을 계속 추적합니다 (tail -f 방식)
--interval <ms>: 추적 시 폴링 간격(ms)
--local-time: 타임스탬프를 로컬 시간으로 표시
--json: 줄 단위 JSON(line-delimited JSON) 출력
--plain: 구조화된 포맷팅 비활성화
--no-color: ANSI 색상 비활성화
--url <url>: 명시적인 Gateway WebSocket URL
--token <token>: Gateway 토큰
--timeout <ms>: Gateway RPC 타임아웃
--expect-final: 필요한 경우 최종 응답을 기다림

Examples:

openclaw logs --follow
openclaw logs --limit 200
openclaw logs --plain
openclaw logs --json
openclaw logs --no-color

Notes:

--url을 전달하면 CLI가 설정 파일이나 환경 변수의 credentials를 자동으로 적용하지 않아요.
로컬 루프백 페어링에 실패하면 설정된 로컬 로그 파일로 대체되지만, 명시적으로 --url을 지정한 경우에는 대체되지 않습니다.

`gateway <subcommand>`

Gateway CLI 헬퍼 명령어들이에요. (RPC 서브커맨드에는 --url, --token, --password, --timeout, --expect-final을 사용하세요) --url을 전달하면 CLI가 설정 파일이나 환경 변수의 credentials를 자동으로 적용하지 않으므로, --token이나 --password를 명시적으로 포함해야 합니다. 명시적인 credentials가 없으면 에러가 발생해요.

Subcommands:

gateway call <method> [--params <json>] [--url <url>] [--token <token>] [--password <password>] [--timeout <ms>] [--expect-final] [--json]
gateway health
gateway status
gateway probe
gateway discover
gateway install|uninstall|start|stop|restart
gateway run

Notes:

gateway status --deep은 시스템 레벨의 서비스 스캔을 추가합니다. 더 자세한 런타임 조사 내용이 필요하다면 gateway probe, health --verbose, 또는 최상위 레벨의 status --deep을 사용하세요.

Common RPCs:

config.schema.lookup (얕은 스키마 노드, 매칭된 힌트 메타데이터, 직계 자식 요약을 통해 하나의 설정 서브트리를 조사합니다)
config.get (현재 설정 스냅샷과 해시를 읽어옵니다)
config.set (전체 설정을 검증하고 저장합니다. 낙관적 동시성 제어를 위해 baseHash를 사용하세요)
config.apply (설정 검증 및 저장 후 재시작하고 활성화합니다)
config.patch (부분 업데이트를 병합한 후 재시작하고 활성화합니다)
update.run (업데이트 실행 후 재시작하고 활성화합니다)

Tip: config.set/config.apply/config.patch를 직접 호출할 때, 이미 설정이 존재한다면 config.get에서 얻은 baseHash를 전달하세요. Tip: 부분적인 수정을 원한다면 먼저 config.schema.lookup으로 조사한 뒤 config.patch를 사용하는 것이 좋습니다. Tip: 이러한 설정 저장 RPC들은 제출된 설정 페이로드 내의 SecretRef가 실제로 해결 가능한지 미리 확인하며, 활성화된 ref가 해결되지 않으면 저장을 거부합니다. Tip: 소유자 전용인 gateway 런타임 툴은 여전히 tools.exec.ask 또는 tools.exec.security 수정을 거부합니다. 레거시 tools.bash.* 별칭들은 동일한 보호된 exec 경로로 정규화됩니다.

모델

fallback 동작이나 scanning strategy에 대해서는 /concepts/models 문서를 참고해 보세요.

Anthropic 관련 참고 사항: Anthropic 팀에 따르면 OpenClaw 스타일의 Claude CLI 사용이 다시 허용되었다고 해요. 그래서 OpenClaw는 Anthropic이 새로운 정책을 발표하기 전까지 Claude CLI 재사용과 claude -p 사용을 이 통합 환경에서 승인된 방식으로 처리합니다. 프로덕션 환경이라면 Anthropic API key를 사용하거나 OpenAI Codex, Alibaba Cloud Model Studio Coding Plan, MiniMax Coding Plan, Z.AI / GLM Coding Plan 같은 지원되는 구독형 provider를 사용하는 것이 더 좋아요.

Anthropic setup-token 방식도 여전히 지원되는 인증 경로로 남아있지만, 이제 OpenClaw는 가능할 경우 Claude CLI 재사용이나 claude -p 방식을 더 선호합니다.

`models` (root)

openclaw models는 models status의 alias예요.

Root 옵션:

--status-json (models status --json의 alias)
--status-plain (models status --plain의 alias)

`models list`

옵션:

--all
--local
--provider <name>
--json
--plain

`models status`

옵션:

--json
--plain
--check (종료 코드 1=만료/누락, 2=만료 예정)
--probe (설정된 auth profile의 실시간 probe 수행)
--probe-provider <name>
--probe-profile <id> (반복 사용 또는 쉼표로 구분)
--probe-timeout <ms>
--probe-concurrency <n>
--probe-max-tokens <n>
--agent <id>

이 명령어는 항상 auth store에 있는 profile의 인증 개요와 OAuth 만료 상태를 포함합니다. --probe를 사용하면 실제 요청을 실행하므로 token이 소비되거나 rate limit이 발생할 수 있다는 점에 주의하세요. Probe 결과 행은 auth profile, 환경 변수 자격 증명, 또는 models.json에서 가져옵니다. Probe 상태로는 ok, auth, rate_limit, billing, timeout, format, unknown, no_model 등이 표시될 수 있어요. 명시적인 auth.order.<provider> 설정에서 저장된 profile이 누락된 경우, probe는 해당 profile을 조용히 시도하는 대신 excluded_by_auth_order로 보고합니다.

`models set <model>`

agents.defaults.model.primary를 설정합니다.

`models set-image <model>`

agents.defaults.imageModel.primary를 설정합니다.

`models aliases list|add|remove`

옵션:

list: --json, --plain
add <alias> <model>
remove <alias>

`models fallbacks list|add|remove|clear`

옵션:

list: --json, --plain
add <model>
remove <model>
clear

`models image-fallbacks list|add|remove|clear`

옵션:

list: --json, --plain
add <model>
remove <model>
clear

`models scan`

옵션:

--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|login|login-github-copilot|setup-token|paste-token`

옵션:

add: 대화형 인증 도우미 (provider 인증 flow 또는 token 붙여넣기)
login: --provider <name>, --method <method>, --set-default
login-github-copilot: GitHub Copilot OAuth 로그인 flow (--yes)
setup-token: --provider <name>, --yes
paste-token: --provider <name>, --profile-id <id>, --expires-in <duration>

참고 사항:

setup-token과 paste-token은 token 인증 방식을 노출하는 provider를 위한 범용 token 명령어입니다.
setup-token은 대화형 TTY가 필요하며 provider의 token 인증 메소드를 실행합니다.
paste-token은 token 값을 입력받으며, --profile-id를 생략하면 기본적으로 auth profile id를 <provider>:manual로 설정합니다.
Anthropic setup-token / paste-token 방식은 여전히 지원되지만, OpenClaw는 이제 Claude CLI 재사용과 claude -p 방식을 더 선호합니다.

`models auth order get|set|clear`

옵션:

get: --provider <name>, --agent <id>, --json
set: --provider <name>, --agent <id>, <profileIds...>
clear: --provider <name>, --agent <id>

시스템

`system event`

시스템 이벤트를 큐에 추가하고 선택적으로 heartbeat (Gateway RPC)를 트리거합니다.

필수 항목:

--text <text>

옵션:

--mode <now|next-heartbeat>
--json
--url, --token, --timeout, --expect-final

`system heartbeat last|enable|disable`

heartbeat 제어 기능입니다 (Gateway RPC).

옵션:

--json
--url, --token, --timeout, --expect-final

`system presence`

시스템 presence 항목을 리스트업합니다 (Gateway RPC).

옵션:

--json
--url, --token, --timeout, --expect-final

Cron

예약된 작업(scheduled jobs)을 관리하는 기능이에요 (Gateway RPC). 자세한 내용은 /automation/cron-jobs를 확인해 보세요.

사용 가능한 서브 명령어들은 다음과 같아요:

- cron status [--json]
- cron list [--all] [--json] (table output by default; use --json for raw)
- cron add (alias: create; requires --name and exactly one of --at | --every | --cron, and exactly one payload of --system-event | --message)
- cron edit <id> (patch fields)
- cron rm <id> (aliases: remove, delete)
- cron enable <id>
- cron disable <id>
- cron runs --id <id> [--limit <n>]
- cron run <id> [--due]

모든 cron 명령어는 --url, --token, --timeout, --expect-final 옵션을 함께 사용할 수 있어요.

cron add|edit --model ...을 사용하면 해당 작업에 선택한 모델을 지정할 수 있어요. 만약 허용되지 않은 모델을 선택하면 cron이 경고를 표시하고, 대신 작업의 에이전트 설정이나 기본 모델 설정을 사용하게 됩니다. 기존에 설정된 fallback 체인은 여전히 적용되지만, 별도의 fallback 리스트 없이 모델만 오버라이드한 경우에는 에이전트의 기본 모델이 숨겨진 재시도 대상으로 추가되지 않아요.

Node host

`node`

node는 headless node host를 실행하거나 백그라운드 서비스로 관리할 때 사용해요. 자세한 내용은 openclaw node를 참고해 보세요.

사용 가능한 서브 명령어들이에요:

- node run --host <gateway-host> --port 18789
- node status
- node install [--host <gateway-host>] [--port <port>] [--tls] [--tls-fingerprint <sha256>] [--node-id <id>] [--display-name <name>] [--runtime &lt;node|bun&gt;] [--force]
- node uninstall
- node stop
- node restart

인증 관련 참고 사항:

node는 환경 변수나 설정 파일에서 Gateway 인증 정보를 가져와요. --token이나 --password 플래그는 사용하지 않습니다. OPENCLAW_GATEWAY_TOKEN 또는 OPENCLAW_GATEWAY_PASSWORD를 먼저 확인하고, 그 다음 gateway.auth.* 설정을 확인해요. 로컬 모드에서 node host는 의도적으로 gateway.remote.* 설정을 무시하지만, gateway.mode=remote인 경우에는 우선순위 규칙에 따라 gateway.remote.* 설정이 적용됩니다.
Node host 인증 시에는 오직 OPENCLAW_GATEWAY_* 환경 변수만 사용된다는 점을 기억해 주세요.

노드 (Nodes)

nodes는 Gateway와 통신하며 페어링된 노드들을 대상으로 작업해요. 자세한 내용은 /nodes에서 확인할 수 있어요.

공통 옵션:

--url, --token, --timeout, --json

서브 커맨드:

nodes status [--connected] [--last-connected <duration>]
nodes describe --node <id|name|ip>
nodes list [--connected] [--last-connected <duration>]
nodes pending
nodes 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 notify --node <id|name|ip> [--title <text>] [--body <text>] [--sound <name>] [--priority <passive|active|timeSensitive>] [--delivery <system|overlay|auto>] [--invoke-timeout <ms>] (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>]

브라우저 (Browser)

브라우저 제어를 위한 CLI예요 (Chrome, Brave, Edge, Chromium 전용). openclaw browser와 Browser tool 문서를 함께 살펴보세요.

공통 옵션:

--url, --token, --timeout, --expect-final, --json
--browser-profile <name>

관리:

browser status
browser start
browser stop
browser reset-profile
browser tabs
browser open <url>
browser focus <targetId>
browser close [targetId]
browser profiles
browser create-profile --name <name> [--color <hex>] [--cdp-url <url>] [--driver existing-session] [--user-data-dir <path>]
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>]

보이스 콜

`voicecall`

플러그인에서 제공하는 보이스 콜 유틸리티예요. 이 기능은 voicecall 플러그인이 설치되고 활성화된 경우에만 나타나요. 자세한 내용은 openclaw voicecall 링크를 확인해 보세요.

자주 사용하는 명령어예요:

voicecall call --to <phone> --message <text> [--mode notify|conversation]
voicecall start --to <phone> [--message <text>] [--mode notify|conversation]
voicecall continue --call-id <id> --message <text>
voicecall speak --call-id <id> --message <text>
voicecall end --call-id <id>
voicecall status --call-id <id>
voicecall tail [--file <path>] [--since <n>] [--poll <ms>]
voicecall latency [--file <path>] [--last <n>]
voicecall expose [--mode off|serve|funnel] [--path <path>] [--port <port>] [--serve-path <path>]

문서 검색

`docs`

실시간 OpenClaw 문서 인덱스를 검색해요.

`docs [query...]`

실시간 문서 인덱스를 검색할 수 있어요.

TUI

`tui`

Gateway에 연결된 터미널 UI를 열어줘요.

옵션:

--url <url>
--token <token>
--password <password>
--session <key>
--deliver
--thinking <level>
--message <text>
--timeout-ms <ms> (agents.defaults.timeoutSeconds 값이 기본으로 설정돼요)
--history-limit <n>

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.

OpenClaw CLI 활용 가이드: 터미널에서 효율적으로 작업하기

명령어 페이지

글로벌 플래그

출력 스타일링

컬러 팔레트

명령 트리 (Command tree)

보안 (Security)

비밀 정보 (Secrets)

secrets

플러그인 (Plugins)

메모리

샌드박스

채팅 슬래시 명령어

설정 및 온보딩

completion

setup

onboard

configure

config

doctor

dashboard

update

backup

채널 헬퍼 (Channel helpers)

channels

directory

skills

pairing

devices

qr

clawbot

hooks

webhooks

webhooks gmail

dns

dns setup

메시징 + 에이전트 (Messaging + agent)

message

agent

agents

agents list

agents add [name]

agents bindings

agents bind

agents unbind

agents delete <id>

agents set-identity

acp

acp client

mcp

mcp serve

mcp list

mcp show [name]

mcp set <name> <value>

mcp unset <name>

approvals

approvals get

approvals set

approvals allowlist add|remove

status

사용량 추적 (Usage tracking)

health

sessions

초기화 및 삭제

reset

uninstall

tasks

flows

Gateway

gateway

gateway service

daemon

logs

gateway <subcommand>

모델

models (root)

models list

models status

models set <model>

models set-image <model>

`secrets`

`completion`

`setup`

`onboard`

`configure`

`config`

`doctor`

`dashboard`

`update`

`backup`

`channels`

`directory`

`skills`

`pairing`

`devices`

`qr`

`clawbot`

`hooks`

`webhooks`

`webhooks gmail`

`dns`

`dns setup`

`message`

`agent`

`agents`

`agents list`

`agents add [name]`

`agents bindings`

`agents bind`

`agents unbind`

`agents delete <id>`

`agents set-identity`

`acp`

`acp client`

`mcp`

`mcp serve`

`mcp list`

`mcp show [name]`

`mcp set <name> <value>`

`mcp unset <name>`

`approvals`

`approvals get`

`approvals set`

`approvals allowlist add|remove`

`status`

`health`

`sessions`

`reset`

`uninstall`

`tasks`

`flows`

`gateway`

`gateway service`

`daemon`

`logs`

`gateway <subcommand>`

`models` (root)

`models list`

`models status`

`models set <model>`

`models set-image <model>`

`models aliases list|add|remove`

`models fallbacks list|add|remove|clear`

`models image-fallbacks list|add|remove|clear`

`models scan`

`models auth add|login|login-github-copilot|setup-token|paste-token`

`models auth order get|set|clear`

`system event`

`system heartbeat last|enable|disable`

`system presence`

`node`

`voicecall`

`docs`

`docs [query...]`

`tui`