참조 (Reference)

OpenClaw 참조 문서는 고정된 예시값보다 현재 설치된 CLI, schema, provider auth, plugin 상태를 확인하는 흐름이 중요합니다.

기준일: 2026-07-13 공식 기준: CLI reference, Models CLI reference, Models CLI concepts, Model failover, Sub-agents

핵심 개념

확인 대상	공식/live 표면	목적
CLI command tree	openclaw --help, <command> --help, CLI reference	현재 설치된 core/plugin 명령 확인
Config schema	openclaw config schema, openclaw config validate	설정 키와 타입 확인
Model inventory	openclaw models status, openclaw models list	provider auth, primary, fallback, exact model ref 확인
Model auth	openclaw models auth list, openclaw models auth login ...	profile 상태와 provider별 인증 분리
Channel health	openclaw channels status --probe	채널 연결과 live probe 결과 확인
Sub-agents	/subagents list, /subagents info, /subagents log	child run 상태와 transcript path 확인
Docs search	openclaw docs <query>	공식 문서에서 현재 설명 확인

선택 기준

CLI reference의 command tree는 core 명령과 주요 subcommand를 보여줍니다. 다만 plugin-added subcommand는 설치 상태에 따라 달라질 수 있으므로 실제 작업 전에는 local help를 먼저 봅니다.

openclaw --help
openclaw models --help
openclaw models auth --help
openclaw config --help
openclaw sessions --help
openclaw skills --help

명령을 문서화할 때는 다음 원칙을 적용합니다.

• 공식 CLI reference에 없는 명령은 가이드 본문에 확정 명령처럼 쓰지 않습니다.
• plugin 명령은 "설치된 경우" 또는 local --help로 확인한 명령으로 표기합니다.
• JSON 자동화가 필요하면 해당 명령의 --json 지원 여부를 local help로 확인합니다.

실습

설정 파일을 직접 편집하기 전에 schema와 현재 값을 확인합니다.

echo "$OPENCLAW_CONFIG_PATH"
openclaw config get agents.defaults.model
openclaw config get agents.defaults.model.primary
openclaw config schema
openclaw config validate

OPENCLAW_CONFIG_PATH는 사용할 설정 파일 위치를 명시할 때만 확인합니다. 전역 단일 API key나 workspace 환경 변수를 기본 전제로 두지 않습니다.

모델 allowlist처럼 object를 편집할 때는 기존 항목을 덮어쓰지 않도록 --merge를 먼저 고려합니다.

openclaw config set agents.defaults.models '{"<provider/model>":{}}' --strict-json --merge
openclaw config validate

--replace는 새 object가 완전한 목표 상태일 때만 사용합니다.

Models reference

모델 관련 문제는 먼저 현재 환경의 resolved 상태를 봅니다.

openclaw models status
openclaw models status --json
openclaw models list
openclaw models list --all
openclaw models fallbacks list
openclaw models aliases list

Auth profile은 provider별로 분리해 확인합니다.

openclaw models auth list
openclaw models auth list --provider openai --json
openclaw models auth login --provider openai
openclaw models auth order get --provider openai

문서에 모델명을 적을 때는 openclaw models list에서 확인한 exact provider/model ref를 사용합니다.

Sub-agents reference

서브 에이전트는 채팅 slash command와 runtime tool 표면으로 확인합니다.

/subagents list
/subagents info <id|#>
/subagents log <id|#> [limit] [tools]

Thread-bound session을 운영하는 채널에서는 다음 명령을 함께 봅니다.

/focus <subagent-label|session-key|session-id|session-label>
/unfocus
/session idle <duration|off>
/session max-age <duration|off>

완료 대기를 문서화할 때는 polling loop가 아니라 sessions_yield를 기준으로 설명합니다.

진단 순서

증상	먼저 확인
명령이 없거나 옵션이 다름	<command> --help, 공식 CLI reference
설정 키가 맞는지 불확실함	openclaw config schema, openclaw config validate
채널 연결이 불안정함	openclaw channels status --probe
모델 선택이 막힘	openclaw models status, openclaw models list, allowlist 확인
fallback이 작동하지 않음	user session selection인지 configured default인지 구분
provider 인증 문제	openclaw models auth list, provider별 login/order 상태
sub-agent 결과가 안 보임	/subagents info, /subagents log, parent completion event 확인
공식 문서와 로컬 동작 차이	local version/help, plugin 설치 상태, release notes 확인

도구에 입력할 프롬프트

아래 OpenClaw CLI 출력과 설정 일부를 보고 설치 문제, config schema 문제, provider auth 문제, model allowlist 문제, sub-agent runtime 문제를 분리해줘.
공식 문서 기준으로 확인 가능한 명령만 제안하고, 추측 모델명이나 고정 가격은 쓰지 마.

체크리스트

• reference 문서는 날짜 기준과 공식 링크를 함께 둔다.
• 모델명은 provider/model 형태로만 쓴다.
• 현재 CLI에 없는 명령을 확정적으로 쓰지 않는다.
• 고정 가격, 고정 기본 모델, 계정별 availability를 일반 사실처럼 쓰지 않는다.
• schema-sensitive 예시는 json5 또는 CLI --strict-json 형태로 둔다.

다음 단계

• CLI 명령어에서 주요 명령의 상세 페이지를 봅니다.
• Configuration에서 설정 schema와 JSONC 구조를 확인합니다.
• 멀티 모델 전략에서 provider-qualified model과 fallback 정책을 봅니다.