CLI 명령어 참조

OpenClaw CLI는 Gateway 실행뿐 아니라 onboarding, 채널 진단, skills/ClawHub, docs 검색, 구조화 파일 편집, backup, model/auth까지 포함합니다. 이 페이지는 자주 쓰는 표면을 빠르게 찾기 위한 요약입니다.

기준일: 2026-06-07
공식 기준: OpenClaw CLI reference

개요

CLI 사용법

# 기본 형식
openclaw [command] [options] [arguments]

# 도움말
openclaw --help
openclaw [command] --help

주요 명령어

Setup과 onboarding

setup / onboard / configure - 초기 설정과 변경

# 최소 baseline 구성
openclaw setup

# gateway, model auth, workspace, channels, skills, health까지 guided 설정
openclaw onboard

# 기존 설치의 특정 영역만 재설정
openclaw configure
openclaw dashboard
openclaw doctor

처음 설치 후에는 openclaw onboard가 가장 안전합니다. 이미 설정이 있다면 configure로 model auth, gateway, channels, plugins, skills 중 필요한 영역만 바꿉니다.

Gateway 관리

gateway - 게이트웨이 제어

# Gateway 시작
openclaw gateway start

# Gateway 중지
openclaw gateway stop

# Gateway 상태 확인
openclaw gateway status

# Gateway 재시작
openclaw gateway restart

상태 출력 예시:

Gateway Status: Running
PID: 12345
Uptime: 2 hours 30 minutes
Channels: 3 active (Slack, Telegram, Discord)

채널 상태와 pairing

channels / pairing - 채널 진단과 승인

# 채널 상태와 probe
openclaw channels status
openclaw channels status --probe

# pairing 요청 확인
openclaw pairing list

# 특정 채널 승인
openclaw pairing approve telegram <CODE>

설정 관리

config - 설정 관리

# 설정 조회
openclaw config get

# 특정 설정 조회
openclaw config get channels.slack.enabled

# 설정 변경
openclaw config set agents.model "claude-sonnet-4-20250514"

# 설정 삭제
openclaw config unset channels.slack.enabled

# 설정 편집기
openclaw config edit

설정 파일 경로:

• Linux/macOS: ~/.openclaw/openclaw.json
• Windows: %USERPROFILE%\.openclaw\openclaw.json

세션 관리

sessions - 세션 관리

# 활성 세션 목록
openclaw sessions

# 오래된 세션 정리
openclaw sessions cleanup

문서 검색과 구조화 파일 편집

docs / path - 공식 문서 검색과 oc-path

# 라이브 공식 문서 검색
openclaw docs gateway token secretref
openclaw docs browser existing-session

# oc:// 주소로 Markdown, JSONC, JSONL, YAML 값을 조회/수정
openclaw path resolve 'oc://AGENTS.md/tools/gh/risk' --human
openclaw path find 'oc://gateway.jsonc/channels/**/enabled'
openclaw path validate 'oc://AGENTS.md/tools/gh' --human
openclaw path set 'oc://gateway.jsonc/server/port' '18789' --dry-run

path는 bundled optional oc-path plugin이 제공하므로 처음 쓰기 전 openclaw plugins enable oc-path가 필요할 수 있습니다.

Backup과 reset/update

backup / update - 상태 보존과 업그레이드

# 백업 생성 및 검증
openclaw backup create
openclaw backup verify

# 업데이트와 상태 확인
openclaw update
openclaw status --deep
openclaw health --verbose

Gateway나 채널 설정을 바꾸기 전에는 backup을 먼저 만들고, 업데이트 뒤에는 status --deep 또는 health --verbose로 실제 연결 상태를 확인합니다.

스킬 관리

skills - 스킬 관리 (v2026.3.22 업데이트)

v2026.3.22부터 skills 명령이 ClawHub 네이티브 검색·설치·업데이트 플로우를 지원합니다:

# 스킬 검색 (ClawHub)
openclaw skills search <keyword>

# 스킬 설치
openclaw skills install <skill-name>

# 스킬 업데이트
openclaw skills update <skill-name>

# 설치된 스킬 목록
openclaw skills list

모델과 인증

models / model / auth - provider와 credential 관리

# 모델 상태와 선택
openclaw models list
openclaw models status
openclaw models set <model-id>

# provider별 모델 실행/인증
openclaw model providers
openclaw model auth status
openclaw auth login
openclaw auth setup-token

모델 목록 실패가 곧 auth 문제라는 뜻은 아닙니다. Gateway가 떠 있는지, provider credential이 유효한지, 모델 alias/fallback이 맞는지 순서대로 분리합니다.

로그 및 디버깅

logs - 로그 확인

# 최근 로그
openclaw logs

# 실시간 로그 보기
openclaw logs --follow

# 특정 레벨 필터링
openclaw logs --level error

# 로그 파일 경로
openclaw logs --path

debug - 디버깅 모드

# 디버그 모드로 시작
openclaw --debug gateway start

# 상세 로그
openclaw --verbose logs

설정 확인 기준

CLI가 많은 영역을 다루기 때문에, 환경 변수 이름을 외우기보다 아래 순서로 현재 상태를 확인하는 편이 안전합니다.

openclaw config get
openclaw config validate
openclaw auth order get
openclaw model auth status
openclaw channels status --probe

공식 CLI는 config get/set/unset/file/schema/validate, auth order get|set|clear, model auth login|logout|status, channels status --probe처럼 영역별 진단 명령을 제공합니다. 불확실한 환경 변수 이름을 문서에 박아두기보다 live config와 auth 상태를 먼저 확인하세요.

자주 사용하는 명령 조합

빠른 시작

openclaw gateway start && openclaw logs --follow

설정 후 재시작

openclaw gateway restart

문제 해결

openclaw gateway status
openclaw logs --level error --follow

청소

openclaw gateway stop
openclaw sessions cleanup
openclaw backup create

종료 코드

팁

생산성 향상

별칭(Alias) 설정:

# ~/.bashrc 또는 ~/.zshrc
alias og='openclaw'
alias og-start='openclaw gateway start'
alias og-stop='openclaw gateway stop'
alias og-logs='openclaw logs --follow'

Shell 자동완성:

openclaw completion >> ~/.zshrc
source ~/.zshrc

주의사항

1. Root 권한 없이 실행: OpenClaw는 사용자 권한으로 실행됩니다. sudo를 사용하지 마세요.
2. 백그라운드 실행: 서버 환경에서는 systemd 서비스로 실행을 권장합니다.
3. 다중 인스턴스: 동일 시스템에서 여러 Gateway 실행은 지원하지 않습니다. 이미 실행 중인 경우 openclaw gateway restart를 사용하세요.

신규 명령어 (2026.3 ~ 2026.4)

infer — 추론 워크플로우 허브 (v2026.4.7)

provider 기반 추론 워크플로우를 위한 통합 허브입니다. 모델, 미디어, 웹, 임베딩 작업을 지원합니다:

openclaw infer model "질문을 입력하세요"
openclaw infer audio providers --json

exec-policy — 실행 정책 관리 (v2026.4.12)

로컬 exec 허가 파일과 tools.exec.* 설정을 동기화하는 명령어입니다:

# 현재 exec 정책 확인
openclaw exec-policy show

# 정책 프리셋 적용
openclaw exec-policy preset <preset-name>

# 정책 직접 설정
openclaw exec-policy set <key> <value>

flows — Task Flow 관리 (v2026.3.31)

백그라운드 Task Flow를 조회·취소하는 명령어입니다:

# Task Flow 목록
openclaw flows list

# Task Flow 상세 보기
openclaw flows show <flow-id>

# Task Flow 취소
openclaw flows cancel <flow-id>

--container 옵션 (v2026.3.24)

실행 중인 Docker 또는 Podman OpenClaw 컨테이너 내에서 명령을 실행합니다 (#52651):

# 컨테이너 내에서 실행
openclaw --container gateway status
openclaw --container logs --follow

# 환경 변수로도 지정 가능
OPENCLAW_CONTAINER=my-openclaw-container openclaw gateway status

/btw — 사이드 질문 (v2026.3.22)

현재 세션 컨텍스트를 변경하지 않고 빠른 답변을 얻는 채팅 명령어입니다. TUI에서는 in-session 답변으로 표시되고, 외부 채널에서는 명시적 BTW 응답으로 전송됩니다.

참고:

• 공식 CLI 문서