Configuration 참조
기준일: 2026-07-13 난이도: 중급 공식 기준: Config CLI, Configuration reference
OpenClaw 설정은 설치된 core, plugin, channel metadata를 합쳐 생성한 live JSON Schema를 기준으로 검증됩니다. 문서의 큰 JSON 예제를 그대로 복사하기보다 현재 설치에서 정확한 path와 schema를 조회한 뒤 작은 변경을 적용하는 편이 안전합니다.
핵심 개념
활성 설정 파일
기본 설정 파일은 ~/.openclaw/openclaw.json이며 OPENCLAW_CONFIG_PATH로 다른 일반 파일을 지정할 수 있습니다. 실제 경로는 추측하지 말고 다음 명령으로 확인합니다.
openclaw config file
주요 설정 영역
| 영역 | 공식 key family |
|---|---|
| Agent 기본값 | agents.defaults.* |
| 다중 agent routing | multiAgent.* |
| 세션 lifecycle | session.* |
| 메시지 전달 | messages.* |
| 채널 | channels.* |
| Gateway | gateway.* |
| 브라우저 | browser.* |
| Plugins | plugins.* |
| Secret providers | secrets.providers.* |
sessions, workspace, automation 같은 임의의 root object를 만들어 넣기 전에 반드시 live schema를 확인합니다. 공식 reference에서 세션 영역은 session.*, 기본 workspace와 heartbeat는 agents.defaults.* 아래에 설명됩니다.
선택 기준
- 첫 설정은
openclaw onboard, 기존 설정의 대화형 변경은openclaw configure를 사용합니다. - 한두 key는
config get|set|unset, 여러 key는 검토 가능한config patch를 사용합니다. - 모델과 채널은 전용
models,channelsCLI를 우선합니다. - secret은 평문 예제를 문서나 shell history에 남기지 않고 SecretRef 또는 전용 인증 flow를 사용합니다.
- Nix mode에서는 writer 명령이 거부되므로 Nix source를 수정합니다.
실습
1. schema와 현재 값 확인
openclaw config file
openclaw config schema
openclaw config get gateway.mode
openclaw config get agents.defaults.model --json
openclaw config validate --json
config get은 secret을 redacted snapshot으로 읽습니다. 현재 schema의 특정 path가 불확실하면 값을 만들기 전에 config schema와 해당 공식 deep reference를 확인합니다.
2. 작은 변경을 dry-run 후 적용
openclaw config set gateway.mode local --dry-run
openclaw config set gateway.mode local
openclaw config validate
모델 allowlist에 값을 추가할 때는 기존 항목을 덮어쓰지 않도록 공식 merge 형식을 사용합니다.
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw models set openai/gpt-5.4
3. secret을 참조로 저장
openclaw config set channels.discord.token \
--ref-provider default \
--ref-source env \
--ref-id DISCORD_BOT_TOKEN \
--dry-run
dry-run 결과와 환경 변수 제공 위치를 확인한 뒤 같은 명령에서 --dry-run만 제거합니다. 전체 secret 표면은 SecretRef credential surface를 확인합니다.
4. 채널은 전용 CLI로 구성
openclaw channels add --channel telegram --token <bot-token>
openclaw channels status --probe
채널마다 key와 credential 방식이 다릅니다. 공통 Configuration 문서에 Slack·Telegram·Discord 전체 JSON을 하드코딩하지 않고 각 Channel guide와 openclaw channels add --help를 기준으로 설정합니다.
5. 거부된 변경과 복구
OpenClaw는 invalid config를 Gateway 시작이나 hot reload에 자동 적용하지 않습니다. 설정이 이미 깨졌다면 다음 순서로 확인합니다.
openclaw config validate
openclaw configure
openclaw doctor --lint
자동 복구가 필요하면 먼저 백업하고, 변경을 수행하는 doctor --fix를 명시적으로 선택합니다.
openclaw backup create --verify
openclaw doctor --fix
openclaw config validate
도구에 입력할 프롬프트
현재 OpenClaw 설정을 live schema 기준으로 검토해줘.
먼저 openclaw config file, config schema, config validate --json을 읽고,
공식 schema에 없는 key와 평문 secret만 찾아줘.
변경은 하지 말고 최소 수정 명령과 dry-run 명령을 함께 제시해줘.
체크리스트
- 활성 파일을
config file로 확인했다. - live schema를 조회한 뒤 key를 선택했다.
- 기존 map을 덮어쓰지 않도록 merge/replace 의미를 구분했다.
- secret을 평문 JSON이나 shell history에 남기지 않았다.
- 모든 변경 뒤
config validate를 실행했다. - repair 전에 검증된 backup을 만들었다.
다음 단계
- CLI 명령어 참조에서 현재 command surface를 확인합니다.
- 환경 변수에서 process env와 state 경로를 분리합니다.
- 보안에서 Gateway 노출과 SecretRef 정책을 점검합니다.