설정 참조

~/.openclaw/openclaw.json의 핵심 구성 참조입니다. 작업 중심 개요는 구성을 참고하세요.

주요 OpenClaw 구성 표면을 다루며, 하위 시스템에 자체 심층 참조가 있는 경우 해당 문서로 연결합니다. 채널 및 Plugin 소유 명령 카탈로그와 심층 메모리/QMD 조정값은 이 페이지가 아니라 각각의 전용 페이지에 있습니다.

코드 기준:

• openclaw config schema는 검증 및 Control UI에 사용되는 실시간 JSON Schema를 출력하며, 가능한 경우 번들/Plugin/채널 메타데이터를 병합합니다
• config.schema.lookup은 드릴다운 도구를 위해 경로 범위가 지정된 스키마 노드 하나를 반환합니다
• pnpm config:docs:check / pnpm config:docs:gen은 현재 스키마 표면을 기준으로 구성 문서 기준 해시를 검증합니다

에이전트 조회 경로: 편집 전에 정확한 필드 수준 문서와 제약 조건을 확인하려면 gateway 도구 작업 config.schema.lookup을 사용하세요. 작업 중심 안내는 구성을 사용하고, 더 넓은 필드 맵, 기본값, 하위 시스템 참조 링크는 이 페이지를 사용하세요.

전용 심층 참조:

• agents.defaults.memorySearch.*, memory.qmd.*, memory.citations, 그리고 plugins.entries.memory-core.config.dreaming 아래의 dreaming 구성은 메모리 구성 참조를 참고하세요
• 현재 기본 제공 + 번들 명령 카탈로그는 슬래시 명령을 참고하세요
• 채널별 명령 표면은 소유 채널/Plugin 페이지를 참고하세요

구성 형식은 JSON5입니다(주석 + 후행 쉼표 허용). 모든 필드는 선택 사항입니다. 생략하면 OpenClaw가 안전한 기본값을 사용합니다.

채널

채널별 구성 키는 전용 페이지로 이동했습니다. Slack, Discord, Telegram, WhatsApp, Matrix, iMessage 및 기타 번들 채널(인증, 접근 제어, 다중 계정, 멘션 게이팅)을 포함한 channels.*는 구성 - 채널을 참고하세요.

에이전트 기본값, 다중 에이전트, 세션, 메시지

전용 페이지로 이동했습니다. 다음 항목은 구성 - 에이전트를 참고하세요.

• agents.defaults.*(작업 영역, 모델, thinking, heartbeat, 메모리, 미디어, Skills, 샌드박스)
• multiAgent.*(다중 에이전트 라우팅 및 바인딩)
• session.*(세션 수명 주기, compaction, 정리)
• messages.*(메시지 전달, TTS, 마크다운 렌더링)
• talk.*(Talk 모드)
  • talk.consultThinkingLevel: Control UI Talk 실시간 상담 뒤에서 실행되는 전체 OpenClaw 에이전트 실행의 thinking 수준 오버라이드
  • talk.consultFastMode: Control UI Talk 실시간 상담의 일회성 빠른 모드 오버라이드
  • talk.speechLocale: iOS/macOS에서 Talk 음성 인식을 위한 선택적 BCP 47 로캘 ID
  • talk.silenceTimeoutMs: 설정하지 않으면 Talk는 전사본을 보내기 전에 플랫폼 기본 일시 중지 창을 유지합니다(macOS 및 Android에서는 700 ms, iOS에서는 900 ms)
  • talk.realtime.consultRouting: openclaw_agent_consult를 건너뛰는 확정된 실시간 Talk 전사본을 위한 Gateway 릴레이 폴백

도구 및 사용자 지정 제공자

도구 정책, 실험적 토글, 제공자 기반 도구 구성, 사용자 지정 제공자 / 기본 URL 설정은 전용 페이지로 이동했습니다. 구성 - 도구 및 사용자 지정 제공자를 참고하세요.

모델

제공자 정의, 모델 허용 목록, 사용자 지정 제공자 설정은 구성 - 도구 및 사용자 지정 제공자에 있습니다. models 루트는 전역 모델 카탈로그 동작도 소유합니다.

{  models: {    // Optional. Default: true. Requires a Gateway restart when changed.    pricing: { enabled: false },  },}

• models.mode: 제공자 카탈로그 동작(merge 또는 replace).
• models.providers: 제공자 ID로 키가 지정된 사용자 지정 제공자 맵.
• models.providers.*.localService: 로컬 모델 서버를 위한 선택적 주문형 프로세스 관리자. OpenClaw는 구성된 상태 확인 엔드포인트를 프로브하고, 필요할 때 절대 경로 command를 시작하며, 준비 상태를 기다린 다음 모델 요청을 보냅니다. 로컬 모델 서비스를 참고하세요.
• models.pricing.enabled: 사이드카와 채널이 Gateway 준비 경로에 도달한 뒤 시작되는 백그라운드 가격 부트스트랩을 제어합니다. false이면 Gateway는 OpenRouter 및 LiteLLM 가격 카탈로그 가져오기를 건너뜁니다. 구성된 models.providers.*.models[].cost 값은 로컬 비용 추정에 계속 작동합니다.

MCP

OpenClaw가 관리하는 MCP 서버 정의는 mcp.servers 아래에 있으며, 임베디드 OpenClaw 및 기타 런타임 어댑터에서 사용됩니다. openclaw mcp list, show, set, unset 명령은 구성 편집 중 대상 서버에 연결하지 않고 이 블록을 관리합니다.

{  mcp: {    // Optional. Default: 600000 ms (10 minutes). Set 0 to disable idle eviction.    sessionIdleTtlMs: 600000,    servers: {      docs: {        command: "npx",        args: ["-y", "@modelcontextprotocol/server-fetch"],      },      remote: {        url: "https://example.com/mcp",        transport: "streamable-http", // streamable-http | sse        timeout: 20,        connectTimeout: 5,        supportsParallelToolCalls: true,        headers: {          Authorization: "Bearer ${MCP_REMOTE_TOKEN}",        },        auth: "oauth",        oauth: {          scope: "docs.read",        },        sslVerify: true,        clientCert: "/path/to/client.crt",        clientKey: "/path/to/client.key",        toolFilter: {          include: ["search_*"],          exclude: ["admin_*"],        },        // Optional Codex app-server projection controls.        codex: {          agents: ["main"],          defaultToolsApprovalMode: "approve", // auto | prompt | approve        },      },    },  },}

• mcp.servers: 구성된 MCP 도구를 노출하는 런타임을 위한 이름 지정 stdio 또는 원격 MCP 서버 정의. 원격 항목은 transport: "streamable-http" 또는 transport: "sse"를 사용합니다. type: "http"는 openclaw mcp set 및 openclaw doctor --fix가 표준 transport 필드로 정규화하는 CLI 네이티브 별칭입니다.
• mcp.servers.<name>.enabled: 저장된 서버 정의는 유지하되 임베디드 OpenClaw MCP 검색 및 도구 프로젝션에서는 제외하려면 false로 설정합니다.
• mcp.servers.<name>.timeout / requestTimeoutMs: 서버별 MCP 요청 제한 시간(초 또는 밀리초).
• mcp.servers.<name>.connectTimeout / connectionTimeoutMs: 서버별 연결 제한 시간(초 또는 밀리초).
• mcp.servers.<name>.supportsParallelToolCalls: 병렬 MCP 도구 호출을 실행할지 선택할 수 있는 어댑터를 위한 선택적 동시성 힌트.
• mcp.servers.<name>.auth: OAuth가 필요한 HTTP MCP 서버에는 "oauth"를 설정합니다. OpenClaw 상태 아래에 토큰을 저장하려면 openclaw mcp login <name>을 실행하세요.
• mcp.servers.<name>.oauth: 선택적 OAuth 범위, 리디렉션 URL, 클라이언트 메타데이터 URL 오버라이드.
• mcp.servers.<name>.sslVerify, clientCert, clientKey: 비공개 엔드포인트 및 상호 TLS를 위한 HTTP TLS 제어.
• mcp.servers.<name>.toolFilter: 선택적 서버별 도구 선택. include는 검색된 MCP 도구를 일치하는 이름으로 제한하고, exclude는 일치하는 이름을 숨깁니다. 항목은 정확한 MCP 도구 이름이거나 단순 * 글롭입니다. 리소스 또는 프롬프트가 있는 서버도 유틸리티 도구 이름(resources_list, resources_read, prompts_list, prompts_get)을 생성하며, 해당 이름에도 동일한 필터가 적용됩니다.
• mcp.servers.<name>.codex: 선택적 Codex 앱 서버 프로젝션 제어. 이 블록은 Codex 앱 서버 스레드 전용 OpenClaw 메타데이터입니다. ACP 세션, 일반 Codex 하네스 구성 또는 다른 런타임 어댑터에는 영향을 주지 않습니다. 비어 있지 않은 codex.agents는 서버를 나열된 OpenClaw 에이전트 ID로 제한합니다. 비어 있거나, 공백이거나, 유효하지 않은 범위 지정 에이전트 목록은 구성 검증에서 거부되며, 전역이 되는 대신 런타임 프로젝션 경로에서 생략됩니다. codex.defaultToolsApprovalMode는 해당 서버에 대해 Codex의 네이티브 default_tools_approval_mode를 내보냅니다. OpenClaw는 네이티브 mcp_servers 구성을 Codex에 전달하기 전에 codex 블록을 제거합니다. Codex의 기본 MCP 승인 동작으로 모든 Codex 앱 서버 에이전트에 서버를 프로젝션하려면 이 블록을 생략하세요.
• mcp.sessionIdleTtlMs: 세션 범위 번들 MCP 런타임의 유휴 TTL. 일회성 임베디드 실행은 실행 종료 정리를 요청합니다. 이 TTL은 장기 실행 세션과 향후 호출자를 위한 최후 안전장치입니다.
• mcp.* 아래의 변경 사항은 캐시된 세션 MCP 런타임을 폐기하여 핫 적용됩니다. 다음 도구 검색/사용 시 새 구성에서 다시 생성되므로 제거된 mcp.servers 항목은 유휴 TTL을 기다리지 않고 즉시 정리됩니다.
• 런타임 검색은 해당 세션의 캐시된 카탈로그를 삭제하여 MCP 도구 목록 변경 알림도 준수합니다. 리소스 또는 프롬프트를 광고하는 서버는 리소스 나열/읽기 및 프롬프트 나열/가져오기를 위한 유틸리티 도구를 얻습니다. 반복되는 도구 호출 실패는 다른 호출을 시도하기 전에 영향을 받은 서버를 잠시 일시 중지합니다.

런타임 동작은 MCP 및 CLI 백엔드를 참고하세요.

Skills

{  skills: {    allowBundled: ["gemini", "peekaboo"],    load: {      extraDirs: ["~/Projects/agent-scripts/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },    install: {      preferBrew: true,      nodeManager: "npm", // npm | pnpm | yarn | bun      allowUploadedArchives: false,    },    workshop: {      allowSymlinkTargetWrites: false,    },    entries: {      "image-lab": {        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },      },      peekaboo: { enabled: true },      sag: { enabled: false },    },  },}

• allowBundled: 번들 Skills 전용 선택적 허용 목록(관리/작업 영역 Skills에는 영향 없음).
• load.extraDirs: 추가 공유 Skill 루트(가장 낮은 우선순위).
• load.allowSymlinkTargets: 링크가 구성된 소스 루트 외부에 있을 때 Skill 심볼릭 링크가 해석될 수 있는 신뢰된 실제 대상 루트.
• workshop.allowSymlinkTargetWrites: Skill Workshop 적용이 이미 신뢰된 심볼릭 링크 대상을 통해 쓰도록 허용합니다(기본값: false).
• install.preferBrew: true이면 brew를 사용할 수 있을 때 다른 설치 관리자 종류로 폴백하기 전에 Homebrew 설치 관리자를 우선합니다.
• install.nodeManager: metadata.openclaw.install 사양의 Node 설치 관리자 선호도(npm | pnpm | yarn | bun).
• install.allowUploadedArchives: 신뢰된 operator.admin Gateway 클라이언트가 skills.upload.*를 통해 스테이징된 비공개 zip 아카이브를 설치하도록 허용합니다(기본값: false). 이는 업로드된 아카이브 경로만 활성화합니다. 일반 ClawHub 설치에는 필요하지 않습니다.
• entries.<skillKey>.enabled: false는 번들/설치된 경우에도 Skill을 비활성화합니다.
• entries.<skillKey>.apiKey: 기본 env var를 선언하는 Skills를 위한 편의 기능(일반 텍스트 문자열 또는 SecretRef 객체).

Plugins

{  plugins: {    enabled: true,    allow: ["voice-call"],    deny: [],    load: {      paths: ["~/Projects/oss/voice-call-plugin"],    },    entries: {      "voice-call": {        enabled: true,        hooks: {          allowPromptInjection: false,        },        config: { provider: "twilio" },      },    },  },}

• ~/.openclaw/extensions 및 <workspace>/.openclaw/extensions 아래의 패키지 또는 번들 디렉터리와 plugins.load.paths에 나열된 파일 또는 디렉터리에서 로드됩니다.
• 독립 실행형 Plugin 파일은 plugins.load.paths에 넣으세요. 자동 발견된 확장 루트는 최상위 .js, .mjs, .ts 파일을 무시하므로 해당 루트의 헬퍼 스크립트가 시작을 막지 않습니다.
• 발견은 네이티브 OpenClaw Plugin뿐 아니라 매니페스트가 없는 Claude 기본 레이아웃 번들을 포함해 호환되는 Codex 번들 및 Claude 번들도 허용합니다.
• 설정 변경에는 Gateway 재시작이 필요합니다.
• allow: 선택적 허용 목록입니다(나열된 Plugin만 로드). deny가 우선합니다.
• plugins.entries.<id>.apiKey: Plugin 수준 API 키 편의 필드입니다(Plugin에서 지원하는 경우).
• plugins.entries.<id>.env: Plugin 범위 env var 맵입니다.
• plugins.entries.<id>.hooks.allowPromptInjection: false이면 코어가 before_prompt_build를 차단하고 레거시 before_agent_start의 프롬프트 변경 필드를 무시하면서, 레거시 modelOverride 및 providerOverride는 보존합니다. 네이티브 Plugin 훅과 지원되는 번들 제공 훅 디렉터리에 적용됩니다.
• plugins.entries.<id>.hooks.allowConversationAccess: true이면 신뢰할 수 있는 비번들 Plugin이 llm_input, llm_output, before_model_resolve, before_agent_reply, before_agent_run, before_agent_finalize, agent_end 같은 typed 훅에서 원시 대화 콘텐츠를 읽을 수 있습니다.
• plugins.entries.<id>.subagent.allowModelOverride: 이 Plugin이 백그라운드 하위 에이전트 실행에 대해 실행별 provider 및 model 재정의를 요청하도록 명시적으로 신뢰합니다.
• plugins.entries.<id>.subagent.allowedModels: 신뢰된 하위 에이전트 재정의를 위한 정식 provider/model 대상의 선택적 허용 목록입니다. 의도적으로 모든 모델을 허용하려는 경우에만 "*"를 사용하세요.
• plugins.entries.<id>.llm.allowModelOverride: 이 Plugin이 api.runtime.llm.complete에 대해 모델 재정의를 요청하도록 명시적으로 신뢰합니다.
• plugins.entries.<id>.llm.allowedModels: 신뢰된 Plugin LLM completion 재정의를 위한 정식 provider/model 대상의 선택적 허용 목록입니다. 의도적으로 모든 모델을 허용하려는 경우에만 "*"를 사용하세요.
• plugins.entries.<id>.llm.allowAgentIdOverride: 이 Plugin이 기본값이 아닌 에이전트 ID에 대해 api.runtime.llm.complete를 실행하도록 명시적으로 신뢰합니다.
• plugins.entries.<id>.config: Plugin 정의 설정 객체입니다(사용 가능한 경우 네이티브 OpenClaw Plugin 스키마로 검증됨).
• 채널 Plugin 계정/런타임 설정은 channels.<id> 아래에 있으며, 중앙 OpenClaw 옵션 레지스트리가 아니라 소유 Plugin의 매니페스트 channelConfigs 메타데이터로 설명되어야 합니다.

Codex 하네스 Plugin 설정

번들된 codex Plugin은 네이티브 Codex 앱 서버 하네스 설정을 plugins.entries.codex.config 아래에서 소유합니다. 전체 설정 표면은 Codex 하네스 참조를, 런타임 모델은 Codex 하네스를 참조하세요.

codexPlugins는 네이티브 Codex 하네스를 선택한 세션에만 적용됩니다. OpenClaw provider 실행, ACP 대화 바인딩 또는 Codex가 아닌 하네스에 대해 Codex Plugin을 활성화하지 않습니다.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          codexPlugins: {            enabled: true,            allow_destructive_actions: true,            plugins: {              "google-calendar": {                enabled: true,                marketplaceName: "openai-curated",                pluginName: "google-calendar",                allow_destructive_actions: false,              },            },          },        },      },    },  },}

• plugins.entries.codex.config.codexPlugins.enabled: Codex 하네스를 위한 네이티브 Codex Plugin/앱 지원을 활성화합니다. 기본값: false.
• plugins.entries.codex.config.codexPlugins.allow_destructive_actions: 마이그레이션된 Plugin 앱 elicitation의 기본 파괴적 작업 정책입니다. 프롬프트 없이 안전한 Codex 승인 스키마를 수락하려면 true, 거절하려면 false, Codex가 요구하는 승인을 OpenClaw Plugin 승인으로 라우팅하려면 "auto", 지속 승인 없이 모든 Plugin 쓰기/파괴적 작업에 대해 프롬프트하려면 "ask"를 사용하세요. "ask" 모드는 영향을 받는 앱의 도구별 지속 Codex 승인 재정의를 지우고, Codex 스레드가 시작되기 전에 해당 앱의 사람 승인 리뷰어를 선택합니다. 기본값: true.
• plugins.entries.codex.config.codexPlugins.plugins.<key>.enabled: 전역 codexPlugins.enabled도 true일 때 마이그레이션된 Plugin 항목을 활성화합니다. 기본값: 명시적 항목의 경우 true.
• plugins.entries.codex.config.codexPlugins.plugins.<key>.marketplaceName: 안정적인 마켓플레이스 ID입니다. V1은 "openai-curated"만 지원합니다.
• plugins.entries.codex.config.codexPlugins.plugins.<key>.pluginName: 마이그레이션에서 온 안정적인 Codex Plugin ID입니다. 예: "google-calendar".
• plugins.entries.codex.config.codexPlugins.plugins.<key>.allow_destructive_actions: Plugin별 파괴적 작업 재정의입니다. 생략하면 전역 allow_destructive_actions 값이 사용됩니다. Plugin별 값은 동일한 true, false, "auto", "ask" 정책을 허용합니다.

"ask"를 사용하는 허용된 각 Plugin 앱은 해당 앱의 승인 요청을 사람 리뷰어에게 라우팅합니다. 다른 앱과 앱이 아닌 스레드 승인은 구성된 리뷰어를 유지하므로, 혼합 Plugin 정책은 "ask" 동작을 상속하지 않습니다.

codexPlugins.enabled는 전역 활성화 지시문입니다. 마이그레이션이 작성한 명시적 Plugin 항목은 지속 설치 및 복구 적격성 집합입니다. plugins["*"]는 지원되지 않고, install 스위치는 없으며, 로컬 marketplacePath 값은 호스트별 값이므로 의도적으로 설정 필드가 아닙니다.

app/list 준비 상태 검사는 한 시간 동안 캐시되며 오래되면 비동기적으로 새로 고칩니다. Codex 스레드 앱 설정은 매 턴이 아니라 Codex 하네스 세션 설정 시 계산됩니다. 네이티브 Plugin 설정을 변경한 뒤에는 /new, /reset 또는 Gateway 재시작을 사용하세요.

• plugins.entries.firecrawl.config.webFetch: Firecrawl 웹 가져오기 provider 설정입니다.
  • apiKey: 더 높은 한도를 위한 선택적 Firecrawl API 키입니다(SecretRef 허용). plugins.entries.firecrawl.config.webSearch.apiKey, 레거시 tools.web.fetch.firecrawl.apiKey 또는 FIRECRAWL_API_KEY env var로 폴백합니다.
  • baseUrl: Firecrawl API 기본 URL입니다(기본값: https://api.firecrawl.dev; 자체 호스팅 재정의는 프라이빗/내부 엔드포인트를 대상으로 해야 함).
  • onlyMainContent: 페이지에서 본문 콘텐츠만 추출합니다(기본값: true).
  • maxAgeMs: 최대 캐시 수명(밀리초)입니다(기본값: 172800000 / 2일).
  • timeoutSeconds: 스크레이프 요청 제한 시간(초)입니다(기본값: 60).
• plugins.entries.xai.config.xSearch: xAI X Search(Grok 웹 검색) 설정입니다.
  • enabled: X Search provider를 활성화합니다.
  • model: 검색에 사용할 Grok 모델입니다(예: "grok-4-1-fast").
• plugins.entries.memory-core.config.dreaming: 메모리 Dreaming 설정입니다. 단계와 임계값은 Dreaming을 참조하세요.
  • enabled: 마스터 Dreaming 스위치입니다(기본값 false).
  • frequency: 각 전체 Dreaming 스윕의 Cron 주기입니다(기본값 "0 3 * * *").
  • model: 선택적 Dream Diary 하위 에이전트 모델 재정의입니다. plugins.entries.memory-core.subagent.allowModelOverride: true가 필요하며, 대상을 제한하려면 allowedModels와 함께 사용하세요. 모델을 사용할 수 없는 오류는 세션 기본 모델로 한 번 재시도합니다. 신뢰 또는 허용 목록 실패는 조용히 폴백하지 않습니다.
  • 단계 정책과 임계값은 구현 세부 사항입니다(사용자 대상 설정 키가 아님).
• 전체 메모리 설정은 메모리 설정 참조에 있습니다.
  • agents.defaults.memorySearch.*
  • memory.backend
  • memory.citations
  • memory.qmd.*
  • plugins.entries.memory-core.config.dreaming
• 활성화된 Claude 번들 Plugin도 settings.json에서 임베디드 OpenClaw 기본값을 제공할 수 있습니다. OpenClaw는 이를 원시 OpenClaw 설정 패치가 아니라 정제된 에이전트 설정으로 적용합니다.
• plugins.slots.memory: 활성 메모리 Plugin ID를 선택하거나, 메모리 Plugin을 비활성화하려면 "none"을 선택합니다.
• plugins.slots.contextEngine: 활성 컨텍스트 엔진 Plugin ID를 선택합니다. 다른 엔진을 설치하고 선택하지 않는 한 기본값은 "legacy"입니다.

Plugins를 참조하세요.

커밋먼트

commitments는 추론된 후속 메모리를 제어합니다. OpenClaw는 대화 턴에서 체크인을 감지하고 Heartbeat 실행을 통해 전달할 수 있습니다.

• commitments.enabled: 추론된 후속 커밋먼트에 대한 숨겨진 LLM 추출, 저장 및 Heartbeat 전달을 활성화합니다. 기본값: false.
• commitments.maxPerDay: 롤링 하루 동안 에이전트 세션당 전달되는 추론된 후속 커밋먼트의 최대 개수입니다. 기본값: 3.

추론된 커밋먼트를 참조하세요.

브라우저

{  browser: {    enabled: true,    evaluateEnabled: true,    defaultProfile: "user",    ssrfPolicy: {      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access      // allowPrivateNetwork: true, // legacy alias      // hostnameAllowlist: ["*.example.com", "example.com"],      // allowedHostnames: ["localhost"],    },    tabCleanup: {      enabled: true,      idleMinutes: 120,      maxTabsPerSession: 8,      sweepMinutes: 5,    },    profiles: {      openclaw: { cdpPort: 18800, color: "#FF4500" },      work: {        cdpPort: 18801,        color: "#0066CC",        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",      },      user: { driver: "existing-session", attachOnly: true, color: "#00AA00" },      brave: {        driver: "existing-session",        attachOnly: true,        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",        color: "#FB542B",      },      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },    },    color: "#FF4500",    // headless: false,    // noSandbox: false,    // extraArgs: [],    // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",    // attachOnly: false,  },}

• evaluateEnabled: false는 act:evaluate와 wait --fn을 비활성화합니다.
• tabCleanup은 유휴 시간이 지난 후 또는 세션이 한도를 초과하면 추적 중인 기본 에이전트 탭을 회수합니다. 해당 개별 정리 모드를 비활성화하려면 idleMinutes: 0 또는 maxTabsPerSession: 0을 설정하세요.
• ssrfPolicy.dangerouslyAllowPrivateNetwork는 설정되지 않으면 비활성화되므로, 브라우저 탐색은 기본적으로 엄격하게 유지됩니다.
• 비공개 네트워크 브라우저 탐색을 의도적으로 신뢰하는 경우에만 ssrfPolicy.dangerouslyAllowPrivateNetwork: true를 설정하세요.
• 엄격 모드에서는 원격 CDP 프로필 엔드포인트(profiles.*.cdpUrl)도 도달 가능성/검색 검사 중 동일한 비공개 네트워크 차단의 적용을 받습니다.
• ssrfPolicy.allowPrivateNetwork는 레거시 별칭으로 계속 지원됩니다.
• 엄격 모드에서는 명시적 예외에 ssrfPolicy.hostnameAllowlist와 ssrfPolicy.allowedHostnames를 사용하세요.
• 원격 프로필은 연결 전용입니다(시작/중지/재설정 비활성화).
• profiles.*.cdpUrl은 http://, https://, ws://, wss://를 허용합니다. OpenClaw가 /json/version을 검색하도록 하려면 HTTP(S)를 사용하고, 제공자가 직접 DevTools WebSocket URL을 제공하는 경우에는 WS(S)를 사용하세요.
• remoteCdpTimeoutMs와 remoteCdpHandshakeTimeoutMs는 원격 및 attachOnly CDP 도달 가능성과 탭 열기 요청에 적용됩니다. 관리형 루프백 프로필은 로컬 CDP 기본값을 유지합니다.
• 외부에서 관리되는 CDP 서비스가 루프백을 통해 도달 가능하다면 해당 프로필의 attachOnly: true를 설정하세요. 그렇지 않으면 OpenClaw가 루프백 포트를 로컬 관리형 브라우저 프로필로 취급하여 로컬 포트 소유권 오류를 보고할 수 있습니다.
• existing-session 프로필은 CDP 대신 Chrome MCP를 사용하며, 선택한 호스트 또는 연결된 브라우저 노드를 통해 연결할 수 있습니다.
• existing-session 프로필은 Brave 또는 Edge 같은 특정 Chromium 기반 브라우저 프로필을 대상으로 userDataDir를 설정할 수 있습니다.
• Chrome이 DevTools HTTP(S) 검색 엔드포인트 또는 직접 WS(S) 엔드포인트 뒤에서 이미 실행 중인 경우 existing-session 프로필은 cdpUrl을 설정할 수 있습니다. 이 모드에서 OpenClaw는 자동 연결을 사용하는 대신 엔드포인트를 Chrome MCP에 전달하며, Chrome MCP 실행 인수에서는 userDataDir가 무시됩니다.
• existing-session 프로필은 현재 Chrome MCP 경로 제한을 유지합니다: CSS 선택자 대상 지정 대신 스냅샷/ref 기반 동작, 단일 파일 업로드 훅, 대화 상자 타임아웃 재정의 없음, wait --load networkidle 없음, 그리고 responsebody, PDF 내보내기, 다운로드 가로채기 또는 배치 동작 없음.
• 로컬 관리형 openclaw 프로필은 cdpPort와 cdpUrl을 자동 할당합니다. cdpUrl은 원격 CDP 프로필 또는 기존 세션 엔드포인트 연결에만 명시적으로 설정하세요.
• 로컬 관리형 프로필은 해당 프로필의 전역 browser.executablePath를 재정의하도록 executablePath를 설정할 수 있습니다. 한 프로필은 Chrome에서, 다른 프로필은 Brave에서 실행하려면 이를 사용하세요.
• 로컬 관리형 프로필은 프로세스 시작 후 Chrome CDP HTTP 검색에 browser.localLaunchTimeoutMs를 사용하고, 실행 후 CDP WebSocket 준비 상태에 browser.localCdpReadyTimeoutMs를 사용합니다. Chrome은 성공적으로 시작되지만 준비 상태 검사가 시작과 경합하는 느린 호스트에서는 값을 늘리세요. 두 값 모두 120000 ms 이하의 양의 정수여야 하며, 잘못된 구성 값은 거부됩니다.
• 자동 감지 순서: Chromium 기반인 경우 기본 브라우저 → Chrome → Brave → Edge → Chromium → Chrome Canary.
• browser.executablePath와 browser.profiles.<name>.executablePath는 모두 Chromium 실행 전에 OS 홈 디렉터리에 대해 ~와 ~/...를 허용합니다. existing-session 프로필의 프로필별 userDataDir도 틸드 확장됩니다.
• 제어 서비스: 루프백만 해당(gateway.port에서 포트 파생, 기본값 18791).
• extraArgs는 로컬 Chromium 시작에 추가 실행 플래그를 덧붙입니다(예: --disable-gpu, 창 크기 조정 또는 디버그 플래그).

UI

{  ui: {    seamColor: "#FF4500",    assistant: {      name: "OpenClaw",      avatar: "CB", // emoji, short text, image URL, or data URI    },  },}

• seamColor: 네이티브 앱 UI 크롬의 강조 색상(Talk Mode 말풍선 색조 등).
• assistant: Control UI ID 재정의입니다. 활성 에이전트 ID로 대체됩니다.

Gateway

{  gateway: {    mode: "local", // local | remote    port: 18789,    bind: "loopback",    auth: {      mode: "token", // none | token | password | trusted-proxy      token: "your-token",      // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD      // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth      allowTailscale: true,      rateLimit: {        maxAttempts: 10,        windowMs: 60000,        lockoutMs: 300000,        exemptLoopback: true,      },    },    tailscale: {      mode: "off", // off | serve | funnel      resetOnExit: false,    },    controlUi: {      enabled: true,      basePath: "/openclaw",      // root: "dist/control-ui",      // embedSandbox: "scripts", // strict | scripts | trusted      // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs      // chatMessageMaxWidth: "min(1280px, 82%)", // optional grouped chat message max-width      // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI      // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode      // allowInsecureAuth: false,      // dangerouslyDisableDeviceAuth: false,    },    remote: {      url: "ws://127.0.0.1:18789",      transport: "ssh", // ssh | direct      token: "your-token",      // password: "your-password",    },    trustedProxies: ["10.0.0.1"],    // Optional. Default false.    allowRealIpFallback: false,    nodes: {      pairing: {        // Optional. Default unset/disabled.        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],      },      allowCommands: ["canvas.navigate"],      denyCommands: ["system.run"],    },    tools: {      // Additional /tools/invoke HTTP denies      deny: ["browser"],      // Remove tools from the default HTTP deny list for owner/admin callers      allow: ["gateway"],    },    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          timeoutMs: 10000,        },      },    },  },}

OpenAI 호환 endpoint

• Admin HTTP RPC: 기본적으로 admin-http-rpc Plugin으로 꺼져 있습니다. Plugin을 활성화하면 POST /api/v1/admin/rpc가 등록됩니다. Admin HTTP RPC를 참고하세요.
• Chat Completions: 기본적으로 비활성화되어 있습니다. gateway.http.endpoints.chatCompletions.enabled: true로 활성화하세요.
• Responses API: gateway.http.endpoints.responses.enabled.
• Responses URL 입력 강화:
  • gateway.http.endpoints.responses.maxUrlParts
  • gateway.http.endpoints.responses.files.urlAllowlist
  • gateway.http.endpoints.responses.images.urlAllowlist 빈 allowlist는 설정되지 않은 것으로 처리됩니다. URL fetching을 비활성화하려면 gateway.http.endpoints.responses.files.allowUrl=false 및/또는 gateway.http.endpoints.responses.images.allowUrl=false를 사용하세요.
• 선택적 response 강화 헤더:
  • gateway.http.securityHeaders.strictTransportSecurity(직접 제어하는 HTTPS origin에만 설정하세요. Trusted Proxy Auth 참고)

다중 instance 격리

고유한 포트와 state dir로 하나의 호스트에서 여러 Gateway를 실행하세요.

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \OPENCLAW_STATE_DIR=~/.openclaw-a \openclaw gateway --port 19001

편의 flags: --dev(~/.openclaw-dev + 포트 19001 사용), --profile <name>(~/.openclaw-<name> 사용).

Multiple Gateways를 참고하세요.

gateway.tls

{  gateway: {    tls: {      enabled: false,      autoGenerate: false,      certPath: "/etc/openclaw/tls/server.crt",      keyPath: "/etc/openclaw/tls/server.key",      caPath: "/etc/openclaw/tls/ca-bundle.crt",    },  },}

• enabled: Gateway listener(HTTPS/WSS)에서 TLS termination을 활성화합니다(기본값: false).
• autoGenerate: 명시적 파일이 구성되지 않은 경우 로컬 self-signed cert/key pair를 자동 생성합니다. 로컬/개발 용도로만 사용하세요.
• certPath: TLS certificate 파일의 filesystem path입니다.
• keyPath: TLS private key 파일의 filesystem path입니다. 권한을 제한해 유지하세요.
• caPath: 클라이언트 검증 또는 사용자 지정 trust chain을 위한 선택적 CA bundle path입니다.

gateway.reload

{  gateway: {    reload: {      mode: "hybrid", // off | restart | hot | hybrid      debounceMs: 500,      deferralTimeoutMs: 300000,    },  },}

• mode: 런타임에서 config 편집이 적용되는 방식을 제어합니다.
  • "off": 실시간 편집을 무시합니다. 변경 사항에는 명시적 재시작이 필요합니다.
  • "restart": config 변경 시 항상 gateway 프로세스를 재시작합니다.
  • "hot": 재시작하지 않고 프로세스 내부에서 변경 사항을 적용합니다.
  • "hybrid"(기본값): 먼저 hot reload를 시도하고, 필요한 경우 restart로 대체합니다.
• debounceMs: config 변경 사항이 적용되기 전의 디바운스 창(밀리초, 음수가 아닌 정수)입니다.
• deferralTimeoutMs: restart 또는 channel hot reload를 강제하기 전에 진행 중인 작업을 기다릴 선택적 최대 시간(밀리초)입니다. 생략하면 기본 제한 대기(300000)를 사용합니다. 0으로 설정하면 무기한 대기하고 주기적으로 아직 대기 중이라는 경고를 기록합니다.

후크

{  hooks: {    enabled: true,    token: "shared-secret",    path: "/hooks",    maxBodyBytes: 262144,    defaultSessionKey: "hook:ingress",    allowRequestSessionKey: true,    allowedSessionKeyPrefixes: ["hook:", "hook:gmail:"],    allowedAgentIds: ["hooks", "main"],    presets: ["gmail"],    transformsDir: "~/.openclaw/hooks/transforms",    mappings: [      {        match: { path: "gmail" },        action: "agent",        agentId: "hooks",        wakeMode: "now",        name: "Gmail",        sessionKey: "hook:gmail:{{messages[0].id}}",        messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",        deliver: true,        channel: "last",        model: "openai/gpt-5.4-mini",      },    ],  },}

인증: Authorization: Bearer <token> 또는 x-openclaw-token: <token>. 쿼리 문자열 hook token은 거부됩니다.

검증 및 안전 참고 사항:

• hooks.enabled=true에는 비어 있지 않은 hooks.token이 필요합니다.
• hooks.token은 활성 Gateway 공유 비밀 인증(gateway.auth.token / OPENCLAW_GATEWAY_TOKEN 또는 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD)과 달라야 합니다. 재사용이 감지되면 시작 시 치명적이지 않은 보안 경고를 기록합니다.
• openclaw security audit는 감사 시점에만 제공된 Gateway password 인증(--auth password --password <password>)을 포함하여 hook/Gateway 인증 재사용을 심각한 결과로 표시합니다. openclaw doctor --fix를 실행해 저장된 재사용 hooks.token을 교체한 다음, 외부 hook sender가 새 hook token을 사용하도록 업데이트하세요.
• hooks.path는 /일 수 없습니다. /hooks 같은 전용 하위 경로를 사용하세요.
• hooks.allowRequestSessionKey=true인 경우 hooks.allowedSessionKeyPrefixes를 제한하세요(예: ["hook:"]).
• mapping 또는 preset이 템플릿화된 sessionKey를 사용하는 경우 hooks.allowedSessionKeyPrefixes를 설정하고 hooks.allowRequestSessionKey=true를 설정하세요. 정적 mapping key에는 이 옵트인이 필요하지 않습니다.

엔드포인트:

• POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
• POST /hooks/agent → { message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
  • 요청 payload의 sessionKey는 hooks.allowRequestSessionKey=true인 경우에만 허용됩니다(기본값: false).
• POST /hooks/<name> → hooks.mappings를 통해 해석됩니다.
  • Template으로 렌더링된 mapping sessionKey 값은 외부에서 제공된 것으로 처리되며, 마찬가지로 hooks.allowRequestSessionKey=true가 필요합니다.

Gmail 통합

• 기본 제공 Gmail preset은 sessionKey: "hook:gmail:{{messages[0].id}}"를 사용합니다.
• 메시지별 라우팅을 유지하는 경우 hooks.allowRequestSessionKey: true를 설정하고 hooks.allowedSessionKeyPrefixes를 Gmail namespace와 일치하도록 제한하세요. 예: ["hook:", "hook:gmail:"].
• hooks.allowRequestSessionKey: false가 필요한 경우 템플릿화된 기본값 대신 정적 sessionKey로 preset을 재정의하세요.

{  hooks: {    gmail: {      account: "openclaw@gmail.com",      topic: "projects/<project-id>/topics/gog-gmail-watch",      subscription: "gog-gmail-watch-push",      pushToken: "shared-push-token",      hookUrl: "http://127.0.0.1:18789/hooks/gmail",      includeBody: true,      maxBytes: 20000,      renewEveryMinutes: 720,      serve: { bind: "127.0.0.1", port: 8788, path: "/" },      tailscale: { mode: "funnel", path: "/gmail-pubsub" },      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",      thinking: "off",    },  },}

• Gateway는 구성된 경우 부팅 시 gog gmail watch serve를 자동 시작합니다. 비활성화하려면 OPENCLAW_SKIP_GMAIL_WATCHER=1을 설정하세요.
• Gateway와 함께 별도의 gog gmail watch serve를 실행하지 마세요.

Canvas Plugin 호스트

{  plugins: {    entries: {      canvas: {        config: {          host: {            root: "~/.openclaw/workspace/canvas",            liveReload: true,            // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1          },        },      },    },  },}

• Gateway port 아래에서 agent가 편집할 수 있는 HTML/CSS/JS와 A2UI를 HTTP로 제공합니다.
  • http://<gateway-host>:<gateway.port>/__openclaw__/canvas/
  • http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/
• 로컬 전용: gateway.bind: "loopback"(기본값)을 유지하세요.
• 비 loopback bind: canvas route에는 다른 Gateway HTTP surface와 동일하게 Gateway 인증(token/password/trusted-proxy)이 필요합니다.
• Node WebView는 일반적으로 인증 header를 보내지 않습니다. Node가 페어링되고 연결된 뒤 Gateway는 canvas/A2UI 접근을 위한 Node 범위 capability URL을 광고합니다.
• Capability URL은 활성 Node WS session에 바인딩되며 빠르게 만료됩니다. IP 기반 fallback은 사용되지 않습니다.
• 제공되는 HTML에 live-reload client를 삽입합니다.
• 비어 있으면 시작용 index.html을 자동 생성합니다.
• A2UI도 /__openclaw__/a2ui/에서 제공합니다.
• 변경 사항에는 gateway restart가 필요합니다.
• 큰 디렉터리 또는 EMFILE 오류의 경우 live reload를 비활성화하세요.

검색

mDNS(Bonjour)

{  discovery: {    mdns: {      mode: "minimal", // minimal | full | off    },  },}

• minimal(번들 bonjour Plugin이 활성화된 경우 기본값): TXT record에서 cliPath + sshPort를 생략합니다.
• full: cliPath + sshPort를 포함합니다. LAN multicast advertising에는 여전히 번들 bonjour Plugin이 활성화되어 있어야 합니다.
• off: Plugin 활성화 상태를 변경하지 않고 LAN multicast advertising을 억제합니다.
• 번들 bonjour Plugin은 macOS host에서 자동 시작되며 Linux, Windows, containerized Gateway 배포에서는 옵트인입니다.
• hostname은 유효한 DNS label인 경우 system hostname으로 기본 설정되고, 그렇지 않으면 openclaw로 대체됩니다. OPENCLAW_MDNS_HOSTNAME으로 재정의하세요.

광역(DNS-SD)

{  discovery: {    wideArea: { enabled: true },  },}

~/.openclaw/dns/ 아래에 유니캐스트 DNS-SD 영역을 작성합니다. 네트워크 간 검색에는 DNS 서버(CoreDNS 권장) + Tailscale 분할 DNS와 함께 사용하세요.

설정: openclaw dns setup --apply.

환경

env (인라인 환경 변수)

{  env: {    OPENROUTER_API_KEY: "sk-or-...",    vars: {      GROQ_API_KEY: "gsk-...",    },    shellEnv: {      enabled: true,      timeoutMs: 15000,    },  },}

• 인라인 환경 변수는 프로세스 환경에 해당 키가 없을 때만 적용됩니다.
• .env 파일: CWD .env + ~/.openclaw/.env(둘 다 기존 변수를 덮어쓰지 않음).
• shellEnv: 로그인 셸 프로필에서 누락된 예상 키를 가져옵니다.
• 전체 우선순위는 환경을 참고하세요.

환경 변수 치환

모든 구성 문자열에서 ${VAR_NAME}으로 환경 변수를 참조하세요.

{  gateway: {    auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" },  },}

• 대문자 이름만 일치합니다: [A-Z_][A-Z0-9_]*.
• 누락되었거나 비어 있는 변수는 구성 로드 시 오류를 발생시킵니다.
• 리터럴 ${VAR}에는 $${VAR}로 이스케이프하세요.
• $include와 함께 작동합니다.

비밀 정보

비밀 정보 참조는 추가 방식입니다. 평문 값도 계속 작동합니다.

SecretRef

하나의 객체 형태를 사용하세요.

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

검증:

• provider 패턴: ^[a-z][a-z0-9_-]{0,63}$
• source: "env" id 패턴: ^[A-Z][A-Z0-9_]{0,127}$
• source: "file" id: 절대 JSON 포인터(예: "/providers/openai/apiKey")
• source: "exec" id 패턴: ^[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}$(AWS 스타일 secret#json_key 선택자 지원)
• source: "exec" id에는 . 또는 .. 슬래시 구분 경로 세그먼트가 포함되면 안 됩니다(예: a/../b는 거부됨).

지원되는 자격 증명 표면

• 표준 매트릭스: SecretRef 자격 증명 표면
• secrets apply는 지원되는 openclaw.json 자격 증명 경로를 대상으로 합니다.
• auth-profiles.json 참조는 런타임 해석 및 감사 범위에 포함됩니다.

비밀 정보 공급자 구성

{  secrets: {    providers: {      default: { source: "env" }, // optional explicit env provider      filemain: {        source: "file",        path: "~/.openclaw/secrets.json",        mode: "json",        timeoutMs: 5000,      },      vault: {        source: "exec",        command: "/usr/local/bin/openclaw-vault-resolver",        passEnv: ["PATH", "VAULT_ADDR"],      },    },    defaults: {      env: "default",      file: "filemain",      exec: "vault",    },  },}

참고:

• file 공급자는 mode: "json" 및 mode: "singleValue"를 지원합니다(singleValue 모드에서는 id가 "value"여야 함).
• Windows ACL 검증을 사용할 수 없는 경우 파일 및 exec 공급자 경로는 검증 실패 시 차단됩니다. 검증할 수 없는 신뢰할 수 있는 경로에만 allowInsecurePath: true를 설정하세요.
• exec 공급자는 절대 command 경로가 필요하며 stdin/stdout에서 프로토콜 페이로드를 사용합니다.
• 기본적으로 심볼릭 링크 명령 경로는 거부됩니다. 해석된 대상 경로를 검증하면서 심볼릭 링크 경로를 허용하려면 allowSymlinkCommand: true를 설정하세요.
• trustedDirs가 구성된 경우 신뢰할 수 있는 디렉터리 검사는 해석된 대상 경로에 적용됩니다.
• exec 자식 환경은 기본적으로 최소화되어 있습니다. 필요한 변수는 passEnv로 명시적으로 전달하세요.
• 비밀 정보 참조는 활성화 시점에 메모리 내 스냅샷으로 해석되며, 이후 요청 경로는 스냅샷만 읽습니다.
• 활성 표면 필터링은 활성화 중에 적용됩니다. 활성화된 표면의 해석되지 않은 참조는 시작/다시 로드를 실패하게 하며, 비활성 표면은 진단과 함께 건너뜁니다.

인증 저장소

{  auth: {    profiles: {      "anthropic:default": { provider: "anthropic", mode: "api_key" },      "anthropic:work": { provider: "anthropic", mode: "api_key" },      "openai:personal": { provider: "openai", mode: "oauth" },    },    order: {      anthropic: ["anthropic:default", "anthropic:work"],      openai: ["openai:personal"],    },  },}

• 에이전트별 프로필은 <agentDir>/auth-profiles.json에 저장됩니다.
• auth-profiles.json은 정적 자격 증명 모드에 대해 값 수준 참조(api_key에는 keyRef, token에는 tokenRef)를 지원합니다.
• { "provider": { "apiKey": "..." } } 같은 레거시 평면 auth-profiles.json 맵은 런타임 형식이 아닙니다. openclaw doctor --fix는 이를 .legacy-flat.*.bak 백업과 함께 표준 provider:default API 키 프로필로 다시 작성합니다.
• OAuth 모드 프로필(auth.profiles.<id>.mode = "oauth")은 SecretRef 기반 인증 프로필 자격 증명을 지원하지 않습니다.
• 정적 런타임 자격 증명은 메모리 내에서 해석된 스냅샷에서 가져옵니다. 레거시 정적 auth.json 항목은 발견되면 제거됩니다.
• 레거시 OAuth는 ~/.openclaw/credentials/oauth.json에서 가져옵니다.
• OAuth를 참조하세요.
• 시크릿 런타임 동작 및 audit/configure/apply 도구: 시크릿 관리.

auth.cooldowns

{  auth: {    cooldowns: {      billingBackoffHours: 5,      billingBackoffHoursByProvider: { anthropic: 3, openai: 8 },      billingMaxHours: 24,      authPermanentBackoffMinutes: 10,      authPermanentMaxMinutes: 60,      failureWindowHours: 24,      overloadedProfileRotations: 1,      overloadedBackoffMs: 0,      rateLimitedProfileRotations: 1,    },  },}

• billingBackoffHours: 실제 청구/크레딧 부족 오류로 인해 프로필이 실패할 때의 기본 백오프 시간(시간 단위, 기본값: 5). 명시적인 청구 관련 텍스트는 401/403 응답에서도 여기에 포함될 수 있지만, 공급자별 텍스트 매처는 해당 매처를 소유한 공급자 범위에만 유지됩니다(예: OpenRouter Key limit exceeded). 재시도 가능한 HTTP 402 사용 기간 또는 조직/워크스페이스 지출 한도 메시지는 대신 rate_limit 경로에 유지됩니다.
• billingBackoffHoursByProvider: 청구 백오프 시간에 대한 선택적 공급자별 재정의입니다.
• billingMaxHours: 청구 백오프 지수 증가의 시간 단위 상한(기본값: 24)입니다.
• authPermanentBackoffMinutes: 신뢰도 높은 auth_permanent 실패에 대한 기본 백오프 시간(분 단위, 기본값: 10)입니다.
• authPermanentMaxMinutes: auth_permanent 백오프 증가의 분 단위 상한(기본값: 60)입니다.
• failureWindowHours: 백오프 카운터에 사용되는 시간 단위 롤링 윈도우(기본값: 24)입니다.
• overloadedProfileRotations: 모델 폴백으로 전환하기 전 과부하 오류에 대해 허용되는 동일 공급자 인증 프로필 순환의 최대 횟수(기본값: 1)입니다. ModelNotReadyException 같은 공급자 사용 중 형태가 여기에 포함됩니다.
• overloadedBackoffMs: 과부하 상태인 공급자/프로필 순환을 재시도하기 전의 고정 지연 시간(기본값: 0)입니다.
• rateLimitedProfileRotations: 모델 폴백으로 전환하기 전 속도 제한 오류에 대해 허용되는 동일 공급자 인증 프로필 순환의 최대 횟수(기본값: 1)입니다. 이 속도 제한 버킷에는 Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, resource exhausted 같은 공급자 형태의 텍스트가 포함됩니다.

로깅

{  logging: {    level: "info",    file: "/tmp/openclaw/openclaw.log",    consoleLevel: "info",    consoleStyle: "pretty", // pretty | compact | json    redactSensitive: "tools", // off | tools    redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],  },}

• 기본 로그 파일: /tmp/openclaw/openclaw-YYYY-MM-DD.log.
• 안정적인 경로를 사용하려면 logging.file을 설정하세요.
• --verbose가 사용되면 consoleLevel이 debug로 올라갑니다.
• maxFileBytes: 순환 전 활성 로그 파일의 최대 크기(바이트 단위, 양의 정수, 기본값: 104857600 = 100 MB). OpenClaw는 활성 파일 옆에 번호가 붙은 아카이브를 최대 5개까지 유지합니다.
• redactSensitive / redactPatterns: 콘솔 출력, 파일 로그, OTLP 로그 레코드, 저장된 세션 트랜스크립트 텍스트에 대한 최선의 마스킹입니다. redactSensitive: "off"는 이 일반 로그/트랜스크립트 정책만 비활성화합니다. UI/도구/진단 안전 표면은 여전히 방출 전에 시크릿을 마스킹합니다.

진단

{  diagnostics: {    enabled: true,    flags: ["telegram.*"],    stuckSessionWarnMs: 30000,    stuckSessionAbortMs: 300000,    memoryPressureSnapshot: false,     otel: {      enabled: false,      endpoint: "https://otel-collector.example.com:4318",      tracesEndpoint: "https://traces.example.com/v1/traces",      metricsEndpoint: "https://metrics.example.com/v1/metrics",      logsEndpoint: "https://logs.example.com/v1/logs",      protocol: "http/protobuf", // http/protobuf | grpc      headers: { "x-tenant-id": "my-org" },      serviceName: "openclaw-gateway",      traces: true,      metrics: true,      logs: false,      logsExporter: "otlp",      sampleRate: 1.0,      flushIntervalMs: 5000,      captureContent: {        enabled: false,        inputMessages: false,        outputMessages: false,        toolInputs: false,        toolOutputs: false,        systemPrompt: false,        toolDefinitions: false,      },    },     cacheTrace: {      enabled: false,      filePath: "~/.openclaw/logs/cache-trace.jsonl",      includeMessages: true,      includePrompt: true,      includeSystem: true,    },  },}

• enabled: 계측 출력의 마스터 토글(기본값: true)입니다.
• flags: 대상 로그 출력을 활성화하는 플래그 문자열 배열입니다("telegram.*" 또는 "*" 같은 와일드카드 지원).
• stuckSessionWarnMs: 장시간 실행 중인 처리 세션을 session.long_running, session.stalled, 또는 session.stuck으로 분류하기 위한 진행 없음 기간 임계값(ms 단위)입니다. 응답, 도구, 상태, 블록, ACP 진행은 타이머를 재설정합니다. 반복되는 session.stuck 진단은 변경이 없을 때 백오프됩니다.
• stuckSessionAbortMs: 복구를 위해 적격한 정체 활성 작업을 중단 드레인할 수 있기 전의 진행 없음 기간 임계값(ms 단위)입니다. 설정되지 않은 경우 OpenClaw는 최소 5분 및 stuckSessionWarnMs의 3배인 더 안전한 확장 임베디드 실행 윈도우를 사용합니다.
• memoryPressureSnapshot: 메모리 압박이 critical에 도달하면 OOM 전 안정성 스냅샷을 마스킹해 캡처합니다(기본값: false). 일반 메모리 압박 이벤트를 유지하면서 안정성 번들 파일 스캔/쓰기를 추가하려면 true로 설정하세요.
• otel.enabled: OpenTelemetry 내보내기 파이프라인을 활성화합니다(기본값: false). 전체 구성, 신호 카탈로그, 개인정보 보호 모델은 OpenTelemetry 내보내기를 참조하세요.
• otel.endpoint: OTel 내보내기용 컬렉터 URL입니다.
• otel.tracesEndpoint / otel.metricsEndpoint / otel.logsEndpoint: 선택적 신호별 OTLP 엔드포인트입니다. 설정되면 해당 신호에 대해서만 otel.endpoint를 재정의합니다.
• otel.protocol: "http/protobuf"(기본값) 또는 "grpc"입니다.
• otel.headers: OTel 내보내기 요청과 함께 전송되는 추가 HTTP/gRPC 메타데이터 헤더입니다.
• otel.serviceName: 리소스 속성의 서비스 이름입니다.
• otel.traces / otel.metrics / otel.logs: 트레이스, 메트릭 또는 로그 내보내기를 활성화합니다.
• otel.logsExporter: 로그 내보내기 대상입니다. "otlp"(기본값), stdout 줄당 JSON 객체 하나를 출력하는 "stdout", 또는 "both"입니다.
• otel.sampleRate: 트레이스 샘플링 비율 0-1입니다.
• otel.flushIntervalMs: 주기적 텔레메트리 플러시 간격(ms 단위)입니다.
• otel.captureContent: OTEL 스팬 속성에 대한 원시 콘텐츠 캡처를 옵트인합니다. 기본값은 꺼짐입니다. 불리언 true는 시스템이 아닌 메시지/도구 콘텐츠를 캡처합니다. 객체 형식에서는 inputMessages, outputMessages, toolInputs, toolOutputs, systemPrompt, toolDefinitions를 명시적으로 활성화할 수 있습니다.
• OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental: {gen_ai.operation.name} {gen_ai.request.model} 스팬 이름, CLIENT 스팬 종류, 레거시 gen_ai.system 대신 gen_ai.provider.name을 포함하는 최신 실험적 GenAI 추론 스팬 형태를 위한 환경 토글입니다. 기본적으로 스팬은 호환성을 위해 openclaw.model.call 및 gen_ai.system을 유지하며, GenAI 메트릭은 제한된 의미론적 속성을 사용합니다.
• OPENCLAW_OTEL_PRELOADED=1: 전역 OpenTelemetry SDK를 이미 등록한 호스트용 환경 토글입니다. 그러면 OpenClaw는 진단 리스너를 활성 상태로 유지하면서 Plugin 소유 SDK 시작/종료를 건너뜁니다.
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, 및 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: 일치하는 구성 키가 설정되지 않았을 때 사용되는 신호별 엔드포인트 환경 변수입니다.
• cacheTrace.enabled: 임베디드 실행에 대한 캐시 트레이스 스냅샷을 기록합니다(기본값: false).
• cacheTrace.filePath: 캐시 트레이스 JSONL의 출력 경로입니다(기본값: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl).
• cacheTrace.includeMessages / includePrompt / includeSystem: 캐시 트레이스 출력에 포함할 내용을 제어합니다(모두 기본값: true).

업데이트

{  update: {    channel: "stable", // stable | beta | dev    checkOnStart: true,     auto: {      enabled: false,      stableDelayHours: 6,      stableJitterHours: 12,      betaCheckIntervalHours: 1,    },  },}

• channel: npm/git 설치용 릴리스 채널입니다. "stable", "beta", 또는 "dev"입니다.
• checkOnStart: Gateway가 시작될 때 npm 업데이트를 확인합니다(기본값: true).
• auto.enabled: 패키지 설치에 대한 백그라운드 자동 업데이트를 활성화합니다(기본값: false).
• auto.stableDelayHours: 안정 채널 자동 적용 전 최소 지연 시간(시간 단위, 기본값: 6, 최대: 168)입니다.
• auto.stableJitterHours: 안정 채널 롤아웃 분산을 위한 추가 시간 윈도우(시간 단위, 기본값: 12, 최대: 168)입니다.
• auto.betaCheckIntervalHours: 베타 채널 확인 실행 주기(시간 단위, 기본값: 1, 최대: 24)입니다.

ACP

{  acp: {    enabled: true,    dispatch: { enabled: true },    backend: "acpx",    defaultAgent: "main",    allowedAgents: ["main", "ops"],    maxConcurrentSessions: 10,     stream: {      coalesceIdleMs: 50,      maxChunkChars: 1000,      repeatSuppression: true,      deliveryMode: "live", // live | final_only      hiddenBoundarySeparator: "paragraph", // none | space | newline | paragraph      maxOutputChars: 50000,      maxSessionUpdateChars: 500,    },     runtime: {      ttlMinutes: 30,    },  },}

• enabled: 전역 ACP 기능 게이트입니다(기본값: true, ACP 디스패치 및 생성 어포던스를 숨기려면 false로 설정).
• dispatch.enabled: ACP 세션 턴 디스패치에 대한 독립 게이트입니다(기본값: true). 실행을 차단하면서 ACP 명령은 계속 사용할 수 있게 하려면 false로 설정하세요.
• backend: 기본 ACP 런타임 백엔드 ID입니다(등록된 ACP 런타임 Plugin과 일치해야 함). 먼저 백엔드 Plugin을 설치하고, plugins.allow가 설정되어 있으면 백엔드 Plugin ID(예: acpx)를 포함하세요. 그렇지 않으면 ACP 백엔드가 로드되지 않습니다.
• defaultAgent: 생성에서 명시적 대상이 지정되지 않았을 때의 폴백 ACP 대상 에이전트 ID입니다.
• allowedAgents: ACP 런타임 세션에 허용되는 에이전트 ID 허용 목록입니다. 비어 있으면 추가 제한이 없습니다.
• maxConcurrentSessions: 동시에 활성화될 수 있는 ACP 세션의 최대 수입니다.
• stream.coalesceIdleMs: 스트리밍된 텍스트의 유휴 플러시 윈도우(ms 단위)입니다.
• stream.maxChunkChars: 스트리밍된 블록 프로젝션을 분할하기 전 최대 청크 크기입니다.
• stream.repeatSuppression: 턴별 반복 상태/도구 줄을 억제합니다(기본값: true).
• stream.deliveryMode: "live"는 증분 스트리밍합니다. "final_only"는 턴 종료 이벤트까지 버퍼링합니다.
• stream.hiddenBoundarySeparator: 숨겨진 도구 이벤트 뒤 표시 텍스트 앞에 들어가는 구분자입니다(기본값: "paragraph").
• stream.maxOutputChars: ACP 턴당 프로젝션되는 어시스턴트 출력 문자의 최대 수입니다.
• stream.maxSessionUpdateChars: 프로젝션된 ACP 상태/업데이트 줄의 최대 문자 수입니다.
• stream.tagVisibility: 스트리밍 이벤트에 대한 태그 이름별 불리언 표시 여부 재정의 레코드입니다.
• runtime.ttlMinutes: 정리 대상이 되기 전 ACP 세션 워커의 유휴 TTL(분 단위)입니다.
• runtime.installCommand: ACP 런타임 환경을 부트스트랩할 때 실행할 선택적 설치 명령입니다.

CLI

{  cli: {    banner: {      taglineMode: "off", // random | default | off    },  },}

• cli.banner.taglineMode는 배너 태그라인 스타일을 제어합니다:
  • "random" (기본값): 재미있거나 계절에 맞는 태그라인을 순환 표시합니다.
  • "default": 고정된 중립 태그라인(All your chats, one OpenClaw.)입니다.
  • "off": 태그라인 텍스트가 없습니다(배너 제목/버전은 계속 표시됨).
• 전체 배너를 숨기려면(태그라인만이 아니라) env OPENCLAW_HIDE_BANNER=1을 설정하세요.

마법사

CLI 안내 설정 흐름(onboard, configure, doctor)에서 작성하는 메타데이터:

{  wizard: {    lastRunAt: "2026-01-01T00:00:00.000Z",    lastRunVersion: "2026.1.4",    lastRunCommit: "abc1234",    lastRunCommand: "configure",    lastRunMode: "local",    securityAcknowledgedAt: "2026-01-01T00:00:00.000Z",  },}

ID

에이전트 기본값 아래의 agents.list ID 필드를 참조하세요.

브리지(레거시, 제거됨)

현재 빌드에는 더 이상 TCP 브리지가 포함되지 않습니다. Node는 Gateway WebSocket을 통해 연결됩니다. bridge.* 키는 더 이상 구성 스키마의 일부가 아닙니다(제거될 때까지 유효성 검사가 실패하며, openclaw doctor --fix로 알 수 없는 키를 제거할 수 있습니다).

{"bridge": {  "enabled": true,  "port": 18790,  "bind": "tailnet",  "tls": {    "enabled": true,    "autoGenerate": true  }}}

Cron

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // default; cron dispatch + isolated cron agent-turn execution    webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs    webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth    sessionRetention: "24h", // duration string or false    runLog: {      maxBytes: "2mb", // default 2_000_000 bytes      keepLines: 2000, // default 2000    },  },}

• sessionRetention: 완료된 격리 cron 실행 세션을 sessions.json에서 정리하기 전에 보관할 기간입니다. 보관된 삭제 cron 대화 기록의 정리도 제어합니다. 기본값: 24h; 비활성화하려면 false로 설정하세요.
• runLog.maxBytes: 이전 파일 기반 cron 실행 로그와의 호환성을 위해 허용됩니다. 기본값: 2_000_000바이트.
• runLog.keepLines: 작업별로 유지되는 최신 SQLite 실행 기록 행입니다. 기본값: 2000.
• webhookToken: cron Webhook POST 전달(delivery.mode = "webhook")에 사용되는 bearer token입니다. 생략하면 인증 헤더가 전송되지 않습니다.
• webhook: notify: true가 아직 있는 저장된 작업을 openclaw doctor --fix로 마이그레이션할 때 사용되는 사용 중단된 레거시 폴백 Webhook URL(http/https)입니다. 런타임 전달은 작업별 delivery.mode="webhook"와 delivery.to, 또는 알림 전달을 보존할 때 delivery.completionDestination을 사용합니다.

cron.retry

{  cron: {    retry: {      maxAttempts: 3,      backoffMs: [30000, 60000, 300000],      retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"],    },  },}

• maxAttempts: 일시적 오류에서 cron 작업의 최대 재시도 횟수입니다(기본값: 3; 범위: 0-10).
• backoffMs: 각 재시도 시도에 대한 ms 단위 백오프 지연 배열입니다(기본값: [30000, 60000, 300000]; 항목 1-10개).
• retryOn: 재시도를 트리거하는 오류 유형입니다 - "rate_limit", "overloaded", "network", "timeout", "server_error". 모든 일시적 유형을 재시도하려면 생략하세요.

일회성 작업은 재시도 횟수가 소진될 때까지 활성 상태로 유지된 다음, 최종 오류 상태를 유지한 채 비활성화됩니다. 반복 작업은 동일한 일시적 재시도 정책을 사용하여 다음 예약 슬롯 전에 백오프 후 다시 실행됩니다. 영구 오류 또는 소진된 일시적 재시도는 오류 백오프와 함께 일반 반복 일정으로 돌아갑니다.

cron.failureAlert

{  cron: {    failureAlert: {      enabled: false,      after: 3,      cooldownMs: 3600000,      includeSkipped: false,      mode: "announce",      accountId: "main",    },  },}

• enabled: cron 작업의 실패 알림을 활성화합니다(기본값: false).
• after: 알림이 발생하기 전의 연속 실패 횟수입니다(양의 정수, 최솟값: 1).
• cooldownMs: 동일한 작업에 대해 반복 알림 사이의 최소 밀리초입니다(음수가 아닌 정수).
• includeSkipped: 연속 건너뛴 실행을 알림 임계값에 포함합니다(기본값: false). 건너뛴 실행은 별도로 추적되며 실행 오류 백오프에 영향을 주지 않습니다.
• mode: 전달 모드입니다 - "announce"는 채널 메시지로 전송하고, "webhook"은 구성된 Webhook에 게시합니다.
• accountId: 알림 전달 범위를 지정하는 선택적 계정 또는 채널 ID입니다.

cron.failureDestination

{  cron: {    failureDestination: {      mode: "announce",      channel: "last",      to: "channel:C1234567890",      accountId: "main",    },  },}

• 모든 작업에 대한 cron 실패 알림의 기본 대상입니다.
• mode: "announce" 또는 "webhook"입니다. 충분한 대상 데이터가 있으면 기본값은 "announce"입니다.
• channel: announce 전달을 위한 채널 재정의입니다. "last"는 마지막으로 알려진 전달 채널을 재사용합니다.
• to: 명시적 announce 대상 또는 Webhook URL입니다. Webhook 모드에는 필수입니다.
• accountId: 전달을 위한 선택적 계정 재정의입니다.
• 작업별 delivery.failureDestination은 이 전역 기본값을 재정의합니다.
• 전역 또는 작업별 실패 대상이 설정되지 않은 경우, 이미 announce로 전달하는 작업은 실패 시 해당 기본 announce 대상으로 폴백합니다.
• delivery.failureDestination은 작업의 기본 delivery.mode가 "webhook"인 경우를 제외하고 sessionTarget="isolated" 작업에만 지원됩니다.

Cron 작업을 참조하세요. 격리 cron 실행은 백그라운드 작업으로 추적됩니다.

미디어 모델 템플릿 변수

tools.media.models[].args에서 확장되는 템플릿 자리표시자:

구성 include($include)

구성을 여러 파일로 분할합니다:

// ~/.openclaw/openclaw.json{  gateway: { port: 18789 },  agents: { $include: "./agents.json5" },  broadcast: {    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],  },}

병합 동작:

• 단일 파일: 포함하는 객체를 대체합니다.
• 파일 배열: 순서대로 deep-merge됩니다(나중 항목이 이전 항목을 재정의).
• 형제 키: include 이후 병합됩니다(포함된 값을 재정의).
• 중첩 include: 최대 10단계 깊이까지 가능합니다.
• 경로: include하는 파일을 기준으로 해석되지만, 최상위 구성 디렉터리(openclaw.json의 dirname) 내부에 있어야 합니다. 절대 경로/../ 형식은 해당 경계 내부로 해석되는 경우에만 허용됩니다. 경로에는 null 바이트가 포함되어서는 안 되며, 해석 전후 모두 4096자보다 엄격히 짧아야 합니다.
• 단일 파일 include가 뒷받침하는 하나의 최상위 섹션만 변경하는 OpenClaw 소유 쓰기는 해당 포함 파일에 직접 기록됩니다. 예를 들어 plugins install은 plugins.json5의 plugins: { $include: "./plugins.json5" }를 업데이트하고 openclaw.json은 그대로 둡니다.
• 루트 include, include 배열, 형제 재정의가 있는 include는 OpenClaw 소유 쓰기에 대해 읽기 전용입니다. 이러한 쓰기는 구성을 평탄화하는 대신 fail-closed됩니다.
• 오류: 누락된 파일, 구문 분석 오류, 순환 include, 잘못된 경로 형식, 과도한 길이에 대해 명확한 메시지를 제공합니다.

관련: 구성 · 구성 예시 · Doctor

관련

• 구성
• 구성 예시