CLI commands
구성
openclaw.json을 위한 비대화형 도우미입니다. 경로를 기준으로 값을 가져오거나 설정, 패치, 해제하고, 스키마를 출력하거나, 유효성을 검사하거나, 활성 파일 경로를 출력합니다. 하위 명령 없이 openclaw config를 실행하면 openclaw configure와 동일한 안내형 마법사가 열립니다.
루트 옵션
OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc2VjdGlvbiA8c2VjdGlvbg
" type="string">
하위 명령 없이 openclaw config를 실행할 때 반복해서 지정할 수 있는 안내형 설정 섹션 필터입니다.
안내형 섹션: workspace, model, web, gateway, daemon, channels, plugins, skills, health.
예시
openclaw config fileopenclaw config --section modelopenclaw config --section gateway --section daemonopenclaw config schemaopenclaw config get browser.executablePathopenclaw config set browser.executablePath "/usr/bin/google-chrome"openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"openclaw config set agents.defaults.heartbeat.every "2h"openclaw config set 'agents.list[0].tools.exec.node' "node-id-or-name"openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --mergeopenclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKENopenclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode jsonopenclaw config patch --file ./openclaw.patch.json5 --dry-runopenclaw config unset plugins.entries.brave.config.webSearch.apiKeyopenclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-runopenclaw config validateopenclaw config validate --json경로
점 또는 대괄호 표기법을 사용합니다. zsh가 [0]을 글로브 확장하지 않도록 셸 예시에서는 대괄호 경로를 따옴표로 묶으세요.
openclaw config get agents.defaults.workspaceopenclaw config get 'agents.list[0].id'openclaw config get agents.listopenclaw config set 'agents.list[1].tools.exec.node' "node-id-or-name"config get
민감 정보가 가려진 구성 스냅샷에서 값을 읽습니다(비밀 정보는 절대 출력되지 않음). --json은 원시 값을 JSON으로 출력합니다. 그렇지 않으면 문자열, 숫자, 불리언은 그대로 출력되고 객체와 배열은 서식이 적용된 JSON으로 출력됩니다.
openclaw config get browser.executablePathopenclaw config get agents.defaults.model --jsonconfig file
OPENCLAW_CONFIG_PATH 또는 기본 위치에서 확인한 활성 구성 파일 경로를 출력합니다. 이 경로는 심볼릭 링크가 아닌 일반 파일을 가리킵니다. 쓰기 안전성을 참조하세요.
config schema
openclaw.json에 대해 생성된 JSON 스키마를 표준 출력으로 출력합니다.
포함 내용
- 현재 루트 구성 스키마와 편집기 도구용 루트
$schema문자열 필드. - Control UI에서 사용하는 필드
title/description문서 메타데이터. - 일치하는 필드 문서가 있는 경우 중첩 객체, 와일드카드(
*), 배열 항목([]) 노드도 동일한title/description메타데이터를 상속합니다. anyOf/oneOf/allOf분기도 동일한 문서 메타데이터를 상속합니다.- 런타임 매니페스트를 로드할 수 있는 경우 최선형 방식으로 제공되는 실시간 Plugin 및 채널 스키마 메타데이터.
- 현재 구성이 유효하지 않은 경우에도 제공되는 깔끔한 대체 스키마.
관련 런타임 RPC
config.schema.lookup은 얕은 스키마 노드(title, description, type, enum, const, 일반적인 범위 제한), 일치하는 UI 힌트 메타데이터 및 직계 하위 항목 요약과 함께 정규화된 구성 경로 하나를 반환합니다. Control UI 또는 사용자 정의 클라이언트에서 경로 범위의 상세 탐색에 사용하세요.
openclaw config schemaopenclaw config schema > openclaw.schema.jsonconfig validate
Gateway를 시작하지 않고 현재 구성의 유효성을 활성 스키마에 대해 검사합니다.
openclaw config validateopenclaw config validate --json값
가능하면 값을 JSON5로 구문 분석하고, 그렇지 않으면 원시 문자열로 취급합니다. 문자열 대체 없이 표준 JSON만 허용하려면 --strict-json을 사용하세요. 이 경우 주석, 후행 쉼표, 따옴표 없는 키와 같은 JSON5 전용 구문은 거부됩니다. --json은 config set에서 --strict-json을 가리키는 레거시 별칭입니다.
openclaw config set agents.defaults.heartbeat.every "0m"openclaw config set gateway.port 19001 --strict-jsonopenclaw config set channels.whatsapp.groups '["*"]' --strict-jsonconfig get <path> --json은 터미널용 서식이 적용된 텍스트 대신 원시 값을 JSON으로 출력합니다.
이러한 맵에 항목을 추가할 때는 --merge를 사용하세요.
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --mergeopenclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge제공한 값이 의도적으로 전체 대상 값이 되어야 하는 경우에만 --replace를 사용하세요.
config set 모드
값 모드
openclaw config set <path> <value>SecretRef 빌더 모드
openclaw config set channels.discord.token \ --ref-provider default \ --ref-source env \ --ref-id DISCORD_BOT_TOKEN공급자 빌더 모드
secrets.providers.<alias> 경로만 대상으로 합니다.
openclaw config set secrets.providers.vault \ --provider-source exec \ --provider-command /usr/local/bin/openclaw-vault \ --provider-arg read \ --provider-arg openai/api-key \ --provider-timeout-ms 5000일괄 처리 모드
openclaw config set --batch-json '[ { "path": "secrets.providers.default", "provider": { "source": "env" } }, { "path": "channels.discord.token", "ref": { "source": "env", "provider": "default", "id": "DISCORD_BOT_TOKEN" } }]'openclaw config set --batch-file ./config-set.batch.json --dry-run일괄 처리 구문 분석에서는 항상 일괄 처리 페이로드(--batch-json/--batch-file)를 신뢰할 수 있는 원본으로 사용합니다. --strict-json / --json은 일괄 처리 구문 분석 동작을 변경하지 않습니다.
JSON 경로/값 모드는 SecretRef와 공급자에도 직접 사용할 수 있습니다.
openclaw config set channels.discord.token \ '{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \ --strict-json openclaw config set secrets.providers.vaultfile \ '{"source":"file","path":"/etc/openclaw/secrets.json","mode":"json"}' \ --strict-json공급자 빌더 플래그
공급자 빌더 대상은 경로로 secrets.providers.<alias>를 사용해야 합니다.
공통 플래그
--provider-source <env|file|exec>--provider-timeout-ms <ms>(file,exec)
환경 변수 공급자(--provider-source env)
--provider-allowlist <ENV_VAR>(반복 가능)
파일 공급자(--provider-source file)
--provider-path <path>(필수)--provider-mode <singleValue|json>--provider-max-bytes <bytes>--provider-allow-insecure-path
실행 공급자(--provider-source exec)
--provider-command <path>(필수)--provider-arg <arg>(반복 가능)--provider-no-output-timeout-ms <ms>--provider-max-output-bytes <bytes>--provider-json-only--provider-env <KEY=VALUE>(반복 가능)--provider-pass-env <ENV_VAR>(반복 가능)--provider-trusted-dir <path>(반복 가능)--provider-allow-insecure-path--provider-allow-symlink-command
강화된 실행 공급자 예시:
openclaw config set secrets.providers.vault \ --provider-source exec \ --provider-command /usr/local/bin/openclaw-vault \ --provider-arg read \ --provider-arg openai/api-key \ --provider-json-only \ --provider-pass-env VAULT_TOKEN \ --provider-trusted-dir /usr/local/bin \ --provider-timeout-ms 5000config patch
여러 경로 기반 config set 명령을 실행하는 대신 구성 형식의 JSON5 패치를 붙여 넣거나 파이프로 전달합니다. 객체는 재귀적으로 병합되고, 배열과 스칼라 값은 대상을 대체하며, null은 대상 경로를 삭제합니다.
openclaw config patch --file ./openclaw.patch.json5 --dry-runopenclaw config patch --file ./openclaw.patch.json5원격 설정 스크립트에서는 표준 입력으로 패치를 파이프 전달하세요.
ssh user@gateway-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5ssh user@gateway-host 'openclaw config patch --stdin' < ./openclaw.patch.json5패치 예시:
{ channels: { slack: { enabled: true, mode: "socket", botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" }, appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" }, groupPolicy: "open", requireMention: false, }, discord: { enabled: true, token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" }, dmPolicy: "disabled", dm: { enabled: false }, groupPolicy: "allowlist", }, }, agents: { defaults: { model: { primary: "openai/gpt-5.6-sol" }, models: { "openai/gpt-5.6-sol": { params: { fastMode: true } }, }, }, },}객체나 배열 하나가 재귀적으로 패치되는 대신 제공된 값과 정확히 같아야 할 때는 --replace-path <path>를 사용하세요.
openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'--dry-run은 파일에 쓰지 않고 스키마 및 SecretRef 확인 가능성 검사를 실행합니다. 실행 기반 SecretRef는 기본적으로 시험 실행 중 건너뜁니다. 시험 실행에서 의도적으로 공급자 명령을 실행하려면 --allow-exec을 추가하세요.
시험 실행
--dry-run은 openclaw.json에 쓰지 않고 변경 사항의 유효성을 검사합니다. config set, config patch, config unset에서 사용할 수 있습니다.
openclaw config set channels.discord.token \ --ref-provider default \ --ref-source env \ --ref-id DISCORD_BOT_TOKEN \ --dry-run \ --json openclaw config set channels.discord.token \ --ref-provider vault \ --ref-source exec \ --ref-id discord/token \ --dry-run \ --allow-exec드라이런 동작
- 빌더 모드: 변경된 참조/프로바이더에 대해 SecretRef 해석 가능 여부 검사를 실행합니다.
- JSON 모드(
--strict-json,--json또는 배치 모드): 스키마 검증과 SecretRef 해석 가능 여부 검사를 실행합니다. - 정책 검증은 변경 후 전체 설정을 대상으로 실행되므로, 상위 객체 쓰기(예:
hooks를 객체로 설정)는 지원되지 않는 영역 검증을 우회할 수 없습니다. - 명령 실행의 부작용을 방지하기 위해 Exec SecretRef 검사는 기본적으로 건너뜁니다. 검사를 활성화하려면
--allow-exec를 전달하세요(프로바이더 명령이 실행될 수 있습니다).--allow-exec는 드라이런에서만 사용할 수 있으며--dry-run없이는 오류가 발생합니다.
--dry-run --json 필드
ok: 드라이런 통과 여부operations: 평가된 할당 수checks: 스키마/해석 가능 여부 검사의 실행 여부checks.resolvabilityComplete: 해석 가능 여부 검사가 완료될 때까지 실행되었는지 여부(Exec 참조를 건너뛰면 false)refsChecked: 드라이런 중 실제로 해석된 참조 수skippedExecRefs:--allow-exec가 설정되지 않아 건너뛴 Exec 참조 수errors:ok=false일 때 구조화된 누락 경로, 스키마 또는 해석 가능 여부 실패 정보
JSON 출력 형식
{ ok: boolean, operations: number, configPath: string, inputModes: ["value" | "json" | "builder" | "unset", ...], checks: { schema: boolean, resolvability: boolean, resolvabilityComplete: boolean, }, refsChecked: number, skippedExecRefs: number, errors?: [ { kind: "missing-path" | "schema" | "resolvability", message: string, ref?: string, // 해석 가능 여부 오류에 존재 }, ],}성공 예시
{ "ok": true, "operations": 1, "configPath": "~/.openclaw/openclaw.json", "inputModes": ["builder"], "checks": { "schema": false, "resolvability": true, "resolvabilityComplete": true }, "refsChecked": 1, "skippedExecRefs": 0}실패 예시
{ "ok": false, "operations": 1, "configPath": "~/.openclaw/openclaw.json", "inputModes": ["builder"], "checks": { "schema": false, "resolvability": true, "resolvabilityComplete": true }, "refsChecked": 1, "skippedExecRefs": 0, "errors": [ { "kind": "resolvability", "message": "오류: 환경 변수 \"MISSING_TEST_SECRET\"이 설정되지 않았습니다.", "ref": "env:default:MISSING_TEST_SECRET" } ]}드라이런이 실패하는 경우
config schema validation failed: 변경 후 설정 형식이 유효하지 않습니다. 경로/값 또는 프로바이더/참조 객체 형식을 수정하세요.Config policy validation failed: unsupported SecretRef usage: 해당 자격 증명을 다시 일반 텍스트/문자열 입력으로 변경하세요. SecretRef는 지원되는 영역에서만 사용하세요.SecretRef assignment(s) could not be resolved: 참조된 프로바이더/참조를 현재 해석할 수 없습니다(환경 변수 누락, 잘못된 파일 포인터, Exec 프로바이더 실패 또는 프로바이더/소스 불일치).Dry run note: skipped <n> exec SecretRef resolvability check(s): Exec 해석 가능 여부 검증이 필요하면--allow-exec를 사용해 다시 실행하세요.- 배치 모드에서는 실패한 항목을 수정한 후 쓰기 전에
--dry-run을 다시 실행하세요.
변경 사항 적용
config set / config patch / config unset이 성공할 때마다 CLI는 Gateway를 다시 시작해야 하는지 알 수 있도록 다음 세 가지 안내 중 하나를 출력합니다.
| 안내 | 의미 |
|---|---|
Restart the gateway to apply. |
변경된 경로를 적용하려면 전체 재시작이 필요합니다. |
Change will apply without restarting the gateway. |
핫 리로드가 자동으로 변경 사항을 적용합니다. |
No gateway restart needed. |
런타임과 관련된 변경 사항이 없습니다. |
CLI는 모든 Plugin의 리로드 메타데이터가 로드되었는지 확인할 수 없으므로 plugins.entries(또는 그 하위 경로)에 쓰면 항상 재시작해야 합니다.
쓰기 안전성
openclaw config set과 OpenClaw가 소유한 다른 설정 작성기는 디스크에 커밋하기 전에 변경 후 전체 설정을 검증합니다. 새 페이로드가 스키마 검증에 실패하거나 파괴적인 덮어쓰기로 보이면 활성 설정은 그대로 유지되며, 거부된 페이로드는 같은 위치에 openclaw.json.rejected.*로 저장됩니다.
작은 편집에는 CLI 쓰기를 사용하는 것이 좋습니다.
openclaw config set gateway.reload.mode hybrid --dry-runopenclaw config set gateway.reload.mode hybridopenclaw config validate쓰기가 거부되면 저장된 페이로드를 확인하고 전체 설정 형식을 수정하세요.
CONFIG="$(openclaw config file)"ls -lt "$CONFIG".rejected.* 2>/dev/null | headopenclaw config validate편집기에서 직접 쓰는 것도 가능하지만, 실행 중인 Gateway는 검증이 완료될 때까지 이를 신뢰할 수 없는 것으로 처리합니다. 유효하지 않은 직접 편집은 시작에 실패하거나 핫 리로드에서 건너뜁니다. Gateway는 openclaw.json을 다시 작성하지 않습니다. 접두사가 추가되거나 덮어써진 설정을 복구하거나 마지막으로 정상 작동한 사본을 복원하려면 openclaw doctor --fix를 실행하세요. Gateway 문제 해결을 참조하세요.
전체 파일 복구는 doctor 복구에만 사용됩니다. Plugin 스키마 변경이나 minHostVersion 불일치는 모델, 프로바이더, 인증 프로필, 채널, Gateway 노출, 도구, 메모리, 브라우저 또는 Cron 설정과 같은 관련 없는 사용자 설정을 롤백하지 않고 명확하게 오류를 표시합니다.
복구 루프
openclaw config validate가 통과하면 로컬 TUI를 사용하여 내장 에이전트가 활성 설정을 문서와 비교하도록 하고, 같은 터미널에서 각 변경 사항을 검증하세요.
openclaw chatTUI에서 앞에 !를 붙이면 문자 그대로 로컬 셸 명령을 실행합니다(세션당 한 번 표시되는 확인 프롬프트를 승인한 후).
!openclaw config file!openclaw docs gateway auth token secretref!openclaw config validate!openclaw doctor문서와 비교
에이전트에게 현재 설정을 관련 문서 페이지와 비교하고 가장 작은 수정 사항을 제안하도록 요청하세요.
대상 편집 적용
openclaw config set 또는 openclaw configure를 사용하여 대상 편집을 적용하세요.
다시 검증
각 변경 후 openclaw config validate를 다시 실행하세요.
런타임 문제에 doctor 사용
검증은 통과하지만 런타임이 여전히 비정상이라면 마이그레이션 및 복구 지원을 위해 openclaw doctor 또는 openclaw doctor --fix를 실행하세요.
