콘텐츠로 이동
OpenClaw

openclaw config로 설정 관리하기

설정 파일을 직접 수정하다가 오타 하나 때문에 전체 시스템이 멈춰버린 경험, 다들 한 번쯤 있으시죠? 특히 복잡한 설정을 다룰 때 매번 파일을 열고 닫는 과정은 번거롭고 실수하기 쉽습니다.

이제 OpenClaw의 config 명령어를 사용해 보세요. OpenClaw 설정을 안전하고 효율적으로 관리할 수 있는 강력한 도구입니다.

openclaw config 개요

섹션 제목: “openclaw config 개요”

OpenClaw 설정 파일인 openclaw.json을 비대화형 방식으로 수정할 수 있는 도우미 명령어입니다. 경로를 통해 값을 가져오거나(get), 설정하고(set), 삭제(unset)할 수 있으며, 현재 활성화된 설정 파일을 확인하거나 스키마를 검증할 수도 있습니다. 하위 명령 없이 실행하면 설정 마법사가 시작됩니다.

루트 옵션:

  • --section <section>: 하위 명령 없이 openclaw config를 실행할 때 가이드 설정 섹션을 필터링합니다.

지원되는 가이드 섹션:

  • workspace
  • model
  • web
  • gateway
  • daemon
  • channels
  • plugins
  • skills
  • health

Examples

섹션 제목: “Examples”

다양한 설정 작업을 수행하는 예시 명령어들입니다.

Terminal window
openclaw config file
openclaw config --section model
openclaw config --section gateway --section daemon
openclaw config schema
openclaw config get browser.executablePath
openclaw config set browser.executablePath "/usr/bin/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 channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config validate
openclaw config validate --json

config schema

섹션 제목: “config schema”

openclaw.json에 대한 JSON 스키마를 표준 출력으로 보여줍니다.

포함된 내용:

  • 현재 루트 설정 스키마 및 에디터 도구를 위한 루트 $schema 문자열 필드
  • Control UI에서 사용하는 필드 title 및 description 문서 메타데이터
  • 중첩 객체, 와일드카드(*), 배열 항목([]) 노드는 필드 문서가 존재할 때 동일한 메타데이터를 상속받습니다.
  • anyOf / oneOf / allOf 분기 역시 일치하는 필드 문서가 있을 때 메타데이터를 상속받습니다.
  • 런타임 매니페스트를 로드할 수 있을 때 최선의 실시간 플러그인 및 채널 스키마 메타데이터를 제공합니다.
  • 현재 설정이 유효하지 않은 경우에도 깔끔한 대체 스키마를 제공합니다.

관련 런타임 RPC:

  • config.schema.lookup은 정규화된 설정 경로 하나와 얕은 스키마 노드, UI 힌트 메타데이터, 즉각적인 하위 요약 정보를 반환합니다. Control UI나 커스텀 클라이언트에서 경로 기반으로 상세 정보를 확인할 때 사용하세요.
Terminal window
openclaw config schema

다른 도구로 검사하거나 검증하려면 파일로 리다이렉트하세요:

Terminal window
openclaw config schema > openclaw.schema.json

경로(Paths)

섹션 제목: “경로(Paths)”

경로는 점(dot) 또는 대괄호 표기법을 사용합니다:

Terminal window
openclaw config get agents.defaults.workspace
openclaw config get agents.list[0].id

에이전트 목록 인덱스를 사용하여 특정 에이전트를 지정하세요:

Terminal window
openclaw config get agents.list
openclaw config set agents.list[1].tools.exec.node "node-id-or-name"

Values

섹션 제목: “Values”

값은 가능한 경우 JSON5로 파싱되며, 그렇지 않으면 문자열로 처리됩니다. JSON5 파싱을 강제하려면 --strict-json을 사용하세요. --json은 레거시 별칭으로 계속 지원됩니다.

Terminal window
openclaw config set agents.defaults.heartbeat.every "0m"
openclaw config set gateway.port 19001 --strict-json
openclaw config set channels.whatsapp.groups '["*"]' --strict-json

config get <path> --json은 터미널 형식의 텍스트 대신 원본 값을 JSON으로 출력합니다.

config set modes

섹션 제목: “config set modes”

openclaw config set은 네 가지 할당 스타일을 지원합니다.

  1. 값 모드: openclaw config set <path> <value>
  2. SecretRef 빌더 모드:
Terminal window
openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN
  1. 공급자(Provider) 빌더 모드 (secrets.providers.<alias> 경로 전용):
Terminal window
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
  1. 배치 모드 (--batch-json 또는 --batch-file):
Terminal window
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" }
  }
]'
Terminal window
openclaw config set --batch-file ./config-set.batch.json --dry-run

정책 참고:

  • SecretRef 할당은 런타임 변경이 지원되지 않는 영역(예: hooks.token, commands.ownerDisplaySecret, Discord 스레드 바인딩 webhook 토큰, WhatsApp 자격 증명 JSON)에서는 거부됩니다. SecretRef Credential Surface를 확인하세요.

배치 파싱은 항상 배치 페이로드(--batch-json/--batch-file)를 진실의 원천으로 사용합니다. --strict-json / --json은 배치 파싱 동작을 변경하지 않습니다.

JSON 경로/값 모드는 SecretRef와 공급자 모두에 대해 계속 지원됩니다:

Terminal window
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

Provider Builder Flags

섹션 제목: “Provider Builder Flags”

공급자 빌더 대상은 반드시 secrets.providers.<alias>를 경로로 사용해야 합니다.

공통 플래그:

  • --provider-source &lt;env|file|exec&gt;
  • --provider-timeout-ms <ms> (file, exec)

Env 공급자 (--provider-source env):

  • --provider-allowlist <ENV_VAR> (반복 가능)

File 공급자 (--provider-source file):

  • --provider-path <path> (필수)
  • --provider-mode &lt;singleValue|json&gt;
  • --provider-max-bytes <bytes>

Exec 공급자 (--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

강화된 Exec 공급자 예시:

Terminal window
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 5000

Dry run

섹션 제목: “Dry run”

--dry-run을 사용하여 openclaw.json을 실제로 수정하지 않고 변경 사항을 검증하세요.

Terminal window
openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN \
  --dry-run


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

Dry-run 동작:

  • 빌더 모드: 변경된 참조/공급자에 대한 SecretRef 해결 가능 여부를 확인합니다.
  • JSON 모드 (--strict-json, --json 또는 배치 모드): 스키마 검증 및 SecretRef 해결 가능 여부를 확인합니다.
  • 정책 검증은 알려진 지원되지 않는 SecretRef 대상 영역에 대해서도 실행됩니다.
  • 정책 검사는 변경 후의 전체 설정을 평가하므로, 부모 객체 쓰기(예: hooks를 객체로 설정)를 통해 지원되지 않는 영역 검증을 우회할 수 없습니다.
  • Exec SecretRef 검사는 명령 부작용을 방지하기 위해 dry-run 중 기본적으로 건너뜁니다.
  • Exec SecretRef 검사를 선택하려면 --dry-run과 함께 --allow-exec를 사용하세요.
  • --allow-exec는 dry-run 전용이며, --dry-run 없이 사용하면 오류가 발생합니다.

--dry-run --json은 기계가 읽을 수 있는 보고서를 출력합니다:

  • ok: dry-run 통과 여부
  • operations: 평가된 할당 횟수
  • checks: 스키마/해결 가능성 검사 실행 여부
  • checks.resolvabilityComplete: 해결 가능성 검사가 완료되었는지 여부 (exec 참조가 건너뛰어지면 false)
  • refsChecked: dry-run 중 실제로 해결된 참조 횟수
  • skippedExecRefs: --allow-exec가 설정되지 않아 건너뛴 exec 참조 횟수
  • errors: ok=false일 때의 구조화된 스키마/해결 실패 정보

JSON 출력 형태

섹션 제목: “JSON 출력 형태”
{
  ok: boolean,
  operations: number,
  configPath: string,
  inputModes: ["value" | "json" | "builder", ...],
  checks: {
    schema: boolean,
    resolvability: boolean,
    resolvabilityComplete: boolean,
  },
  refsChecked: number,
  skippedExecRefs: number,
  errors?: [
    {
      kind: "schema" | "resolvability",
      message: string,
      ref?: string, // present for resolvability errors
    },
  ],
}

성공 예시:

{
  "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": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.",
      "ref": "env:default:MISSING_TEST_SECRET"
    }
  ]
}

dry-run 실패 시:

  • 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): dry-run이 exec 참조를 건너뛰었습니다. exec 해결 검증이 필요하면 --allow-exec를 추가하여 다시 실행하세요.
  • 배치 모드의 경우, 실패한 항목을 수정하고 다시 --dry-run을 실행한 후 작성하세요.

Write safety

섹션 제목: “Write safety”

openclaw config set 및 기타 OpenClaw 소유의 설정 작성 도구는 변경 사항을 디스크에 커밋하기 전에 전체 설정을 검증합니다. 새 페이로드가 스키마 검증에 실패하거나 파괴적인 덮어쓰기로 보일 경우, 기존 설정은 유지되며 거부된 페이로드는 openclaw.json.rejected.*로 저장됩니다.

작은 수정은 CLI 쓰기를 권장합니다:

Terminal window
openclaw config set gateway.reload.mode hybrid --dry-run
openclaw config set gateway.reload.mode hybrid
openclaw config validate

쓰기가 거부되면 저장된 페이로드를 검사하고 전체 설정 형태를 수정하세요:

Terminal window
CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".rejected.* 2>/dev/null | head
openclaw config validate

직접 에디터로 수정하는 것도 가능하지만, 실행 중인 Gateway는 검증되기 전까지는 이를 신뢰하지 않습니다. 잘못된 직접 수정은 시작 또는 핫 리로드 중에 마지막으로 알려진 정상 백업에서 복구될 수 있습니다. Gateway troubleshooting을 참조하세요.

Subcommands

섹션 제목: “Subcommands”
  • config file: 활성화된 설정 파일 경로를 출력합니다 (OPENCLAW_CONFIG_PATH 또는 기본 위치에서 확인).

수정 후에는 Gateway를 재시작하세요.

Validate

섹션 제목: “Validate”

Gateway를 시작하지 않고 현재 설정을 활성 스키마에 대해 검증합니다.

Terminal window
openclaw config validate
openclaw config validate --json

관련 문서

섹션 제목: “관련 문서”

도움이 더 필요하신가요? AI Setup Assistant를 통해 언제든 문의해 주세요.

OpenClaw

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.