고급 기능 개요
OpenClaw 고급 기능은 임의의 에이전트 스크립트가 아니라 공식 CLI, 설정 schema, 모델 카탈로그, 서브 에이전트 도구 표면을 조합해 운영합니다.
기준일: 2026-07-13 공식 기준: Models CLI concepts, Model failover, Models CLI reference, Sub-agents, CLI reference
핵심 개념
| 영역 | 공식 표면 | 먼저 확인할 것 |
|---|---|---|
| 모델 선택 | provider/model, /model, openclaw models |
openclaw models status, openclaw models list |
| 모델 허용 목록 | agents.defaults.models |
exact ref 또는 provider/* wildcard |
| failover | agents.defaults.model.primary, fallbacks, auth profile rotation |
사용자 session pin과 configured fallback 구분 |
| 서브 에이전트 | sessions_spawn, sessions_yield, /subagents |
child 결과는 parent가 종합한다는 점 |
| CLI 참조 | <command> --help, openclaw config schema, 공식 CLI 페이지 |
plugin subcommand는 설치 상태에 따라 달라질 수 있음 |
선택 기준
모델 이름은 bare alias가 아니라 provider-qualified ref를 기준으로 적습니다.
{
agents: {
defaults: {
model: {
primary: "<provider/model>",
fallbacks: ["<fallback-provider/model>"],
},
models: {
"<provider/model>": { alias: "primary" },
"<fallback-provider/*>": {},
},
},
},
}
운영 기준은 다음과 같습니다.
agents.defaults.model.primary가 기본 시작점입니다.agents.defaults.model.fallbacks는 configured default 또는 job primary가 실패할 때 순서대로 시도됩니다./model이나 model picker로 사용자가 고른 session model은 strict selection입니다. 이 선택이 실패하면 fallback으로 조용히 넘어가지 않고 실패를 드러냅니다.- Auth profile rotation은 같은 provider 안에서 먼저 일어나며, 그 다음에 fallback model로 넘어갑니다.
agents.defaults.models를 설정하면/model과 picker의 allowlist가 됩니다. provider 전체를 열려면"provider/*": {}형태를 사용합니다.
실습
서브 에이전트는 parent session이 sessions_spawn으로 시작하는 별도 실행 단위입니다. child 결과는 internal completion event로 parent/requester session에 돌아오고, 사용자에게 무엇을 보여줄지는 parent가 결정합니다.
{
task: "공식 문서 기준으로 모델 failover 문서를 검토하고 근거 링크를 보고해줘",
taskName: "review_model_failover",
label: "Model failover review",
model: "<provider/model>",
context: "isolated",
cleanup: "keep",
}
사용 시 주의점입니다.
- 필요한 child를 spawn한 뒤 결과가 필요하면
sessions_yield를 사용합니다. - 완료 대기를 위해
/subagents list,sessions_list,sessions_history, shell sleep을 polling loop로 돌리지 않습니다. - child task와 label은 데이터이며 상위 지시를 덮어쓰지 못합니다.
- thread-bound session은 지원 채널에서
thread: true와/focus,/unfocus,/session idle,/session max-age로 운영합니다. - 대량 위임은
agents.defaults.subagents.maxConcurrent,maxChildrenPerAgent,runTimeoutSeconds같은 공식 config key로 제한합니다.
제거한 오래된 패턴
이 문서군에서는 다음 패턴을 사용하지 않습니다.
claude-*-4-20250514처럼 provider가 빠진 오래된 모델 문자열- OpenClaw 공식 schema가 아닌 임의 YAML 라우팅 예시
- 비공식 JavaScript 위임 API 예시
- 현재 CLI reference에 없는 에이전트 상태 명령
- 고정 토큰 가격, 고정 기본 모델, 비공식 절감률
도구에 입력할 프롬프트
현재 OpenClaw의 models status/list, config schema, sub-agent 정책을 확인해줘.
provider-qualified model, fallback, allowlist, child concurrency를 구분하고
공식 CLI와 schema로 확인되지 않은 값은 제안하지 마.
체크리스트
- 모델 문제는
openclaw models status와openclaw models list로 현재 provider/auth/model ref를 확인한다. - 모델 변경은 provider-qualified ref로 기록한다.
- fallback은 configured default와 user session selection의 차이를 구분해 설명한다.
- 서브 에이전트 상태는
/subagents list,/subagents info,/subagents log또는 도구 표면으로 on-demand 확인한다. - CLI 명령은 공식 reference와 local
--help를 함께 확인한다.