구성

각 채널에는 channels.<provider> 아래에 자체 구성 섹션이 있습니다. 설정 단계는 전용 채널 페이지를 참고하세요.

• WhatsApp - channels.whatsapp
• Telegram - channels.telegram
• Discord - channels.discord
• Feishu - channels.feishu
• Google Chat - channels.googlechat
• Microsoft Teams - channels.msteams
• Slack - channels.slack
• Signal - channels.signal
• iMessage - channels.imessage
• Mattermost - channels.mattermost

모든 채널은 동일한 DM 정책 패턴을 공유합니다.

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // pairing | allowlist | open | disabled      allowFrom: ["tg:123"], // only for allowlist/open    },  },}

기본 모델과 선택 사항인 폴백을 설정하세요.

{  agents: {    defaults: {      model: {        primary: "anthropic/claude-sonnet-4-6",        fallbacks: ["openai/gpt-5.4"],      },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "openai/gpt-5.4": { alias: "GPT" },      },    },  },}

• agents.defaults.models는 모델 카탈로그를 정의하고 /model의 허용 목록 역할을 합니다. provider/* 항목은 동적 모델 탐색을 계속 사용하면서 /model, /models, 모델 선택기를 선택된 제공자로 필터링합니다.
• 기존 모델을 제거하지 않고 허용 목록 항목을 추가하려면 openclaw config set agents.defaults.models '<json>' --strict-json --merge를 사용하세요. 항목을 제거하게 되는 단순 대체는 --replace를 전달하지 않으면 거부됩니다.
• 모델 참조는 provider/model 형식을 사용합니다(예: anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx는 transcript/도구 이미지 다운스케일링을 제어합니다(기본값 1200). 값이 낮을수록 보통 스크린샷이 많은 실행에서 비전 토큰 사용량이 줄어듭니다.
• 채팅에서 모델을 전환하려면 모델 CLI를, 인증 순환 및 폴백 동작은 모델 장애 조치를 참고하세요.
• 사용자 지정/자체 호스팅 제공자는 참조의 사용자 지정 제공자를 참고하세요.

DM 접근은 채널별로 dmPolicy를 통해 제어됩니다.

• "pairing"(기본값): 알 수 없는 발신자는 승인을 위한 일회성 페어링 코드를 받습니다
• "allowlist": allowFrom에 있는 발신자만 허용합니다(또는 페어링된 허용 저장소)
• "open": 모든 인바운드 DM을 허용합니다(allowFrom: ["*"] 필요)
• "disabled": 모든 DM을 무시합니다

그룹에는 groupPolicy + groupAllowFrom 또는 채널별 허용 목록을 사용하세요.

채널별 세부 정보는 전체 참조를 참고하세요.

그룹 메시지는 기본적으로 멘션 필요입니다. Agent별 트리거 패턴을 구성하세요. 일반 그룹/채널 답장은 자동으로 게시됩니다. Agent가 언제 말할지 결정해야 하는 공유 공간에서는 메시지 도구 경로를 선택하세요.

{  messages: {    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere    groupChat: {      visibleReplies: "message_tool", // opt-in; visible output requires message(action=send)      unmentionedInbound: "room_event", // unmentioned always-on group chatter is quiet context    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• 메타데이터 멘션: 네이티브 @-멘션(WhatsApp 탭하여 멘션, Telegram @bot 등)
• 텍스트 패턴: mentionPatterns의 안전한 정규식 패턴
• 표시 답장: messages.visibleReplies는 전역적으로 메시지 도구 전송을 요구할 수 있으며, messages.groupChat.visibleReplies는 그룹/채널에 대해 이를 재정의합니다.
• 표시 답장 모드, 채널별 재정의, 셀프 채팅 모드는 전체 참조를 참고하세요.

공유 기준선에는 agents.defaults.skills를 사용한 다음, 특정 Agent는 agents.list[].skills로 재정의하세요.

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // inherits github, weather      { id: "docs", skills: ["docs-search"] }, // replaces defaults      { id: "locked-down", skills: [] }, // no skills    ],  },}

• 기본적으로 Skills를 제한하지 않으려면 agents.defaults.skills를 생략하세요.
• 기본값을 상속하려면 agents.list[].skills를 생략하세요.
• Skills를 사용하지 않으려면 agents.list[].skills: []로 설정하세요.
• Skills, Skills 구성, 그리고 구성 참조를 참고하세요.

오래된 것처럼 보이는 채널을 Gateway가 얼마나 적극적으로 재시작할지 제어하세요.

{  gateway: {    channelHealthCheckMinutes: 5,    channelStaleEventThresholdMinutes: 30,    channelMaxRestartsPerHour: 10,  },  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• 상태 모니터 재시작을 전역적으로 비활성화하려면 gateway.channelHealthCheckMinutes: 0으로 설정하세요.
• channelStaleEventThresholdMinutes는 확인 간격보다 크거나 같아야 합니다.
• 전역 모니터를 비활성화하지 않고 하나의 채널 또는 계정에 대한 자동 재시작을 비활성화하려면 channels.<provider>.healthMonitor.enabled 또는 channels.<provider>.accounts.<id>.healthMonitor.enabled를 사용하세요.
• 운영 디버깅은 상태 검사를, 모든 필드는 전체 참조를 참고하세요.

부하가 있거나 저전력인 호스트에서 로컬 클라이언트가 인증 전 WebSocket 핸드셰이크를 완료할 시간을 더 제공하세요.

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• 기본값은 15000밀리초입니다.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS는 일회성 서비스 또는 셸 재정의에 대해 여전히 우선합니다.
• 먼저 시작/이벤트 루프 지연을 수정하는 것을 권장합니다. 이 조정값은 정상적이지만 준비 중 느린 호스트를 위한 것입니다.

세션은 대화 연속성과 격리를 제어합니다.

{  session: {    dmScope: "per-channel-peer",  // recommended for multi-user    threadBindings: {      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },    reset: {      mode: "daily",      atHour: 4,      idleMinutes: 120,    },  },}

• dmScope: main (공유) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings: 스레드에 바인딩된 세션 라우팅의 전역 기본값입니다(Discord는 /focus, /unfocus, /agents, /session idle, /session max-age를 지원합니다).
• 범위 지정, ID 연결, 전송 정책은 세션 관리를 참고하세요.
• 모든 필드는 전체 참조를 참고하세요.

격리된 샌드박스 런타임에서 에이전트 세션을 실행합니다.

{  agents: {    defaults: {      sandbox: {        mode: "non-main",  // off | non-main | all        scope: "agent",    // session | agent | shared      },    },  },}

먼저 이미지를 빌드하세요. 소스 체크아웃에서는 scripts/sandbox-setup.sh를 실행하고, npm 설치에서는 샌드박싱 § 이미지 및 설정의 인라인 docker build 명령을 참고하세요.

전체 가이드는 샌드박싱을, 모든 옵션은 전체 참조를 참고하세요.

공개 App Store 빌드용 릴레이 기반 푸시는 호스팅되는 OpenClaw 릴레이 https://ios-push-relay.openclaw.ai를 사용합니다.

사용자 지정 릴레이 배포에는 릴레이 URL이 Gateway 릴레이 URL과 일치하는, 의도적으로 분리된 iOS 빌드/배포 경로가 필요합니다. 사용자 지정 릴레이 빌드를 사용하는 경우 Gateway 설정에서 이것을 설정하세요.

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // Optional. Default: 10000          timeoutMs: 10000,        },      },    },  },}

CLI 동등 명령:

openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com

이 설정이 하는 일:

• Gateway가 외부 릴레이를 통해 push.test, 깨우기 알림, 재연결 깨우기를 보낼 수 있게 합니다.
• 페어링된 iOS 앱이 전달한 등록 범위 전송 권한을 사용합니다. Gateway에는 배포 전체에 적용되는 릴레이 토큰이 필요하지 않습니다.
• 각 릴레이 기반 등록을 iOS 앱이 페어링한 Gateway ID에 바인딩하므로, 다른 Gateway가 저장된 등록을 재사용할 수 없습니다.
• 로컬/수동 iOS 빌드는 직접 APNs를 계속 사용합니다. 릴레이 기반 전송은 릴레이를 통해 등록한 공식 배포 빌드에만 적용됩니다.
• iOS 빌드에 내장된 릴레이 기본 URL과 일치해야 하므로 등록 및 전송 트래픽이 같은 릴레이 배포에 도달합니다.

엔드투엔드 흐름:

1. 공식 iOS 앱을 설치합니다.
2. 선택 사항: 의도적으로 분리된 사용자 지정 릴레이 빌드를 사용할 때만 Gateway에서 gateway.push.apns.relay.baseUrl을 구성합니다.
3. iOS 앱을 Gateway에 페어링하고 노드와 운영자 세션이 모두 연결되도록 합니다.
4. iOS 앱이 Gateway ID를 가져오고, App Attest와 앱 영수증을 사용해 릴레이에 등록한 다음, 릴레이 기반 push.apns.register 페이로드를 페어링된 Gateway에 게시합니다.
5. Gateway가 릴레이 핸들과 전송 권한을 저장한 다음 push.test, 깨우기 알림, 재연결 깨우기에 사용합니다.

운영 참고 사항:

• iOS 앱을 다른 Gateway로 전환하는 경우, 앱이 해당 Gateway에 바인딩된 새 릴레이 등록을 게시할 수 있도록 앱을 다시 연결하세요.
• 다른 릴레이 배포를 가리키는 새 iOS 빌드를 배포하면, 앱은 이전 릴레이 원본을 재사용하지 않고 캐시된 릴레이 등록을 새로 고칩니다.

호환성 참고 사항:

• OPENCLAW_APNS_RELAY_BASE_URL 및 OPENCLAW_APNS_RELAY_TIMEOUT_MS는 임시 환경 재정의로 계속 작동합니다.
• 사용자 지정 Gateway 릴레이 URL은 iOS 빌드에 내장된 릴레이 기본 URL과 일치해야 합니다. 공개 App Store 릴리스 경로는 사용자 지정 iOS 릴레이 URL 재정의를 거부합니다.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true는 local loopback 전용 개발 탈출구로 남아 있습니다. HTTP 릴레이 URL을 설정에 영구 저장하지 마세요.

엔드투엔드 흐름은 iOS 앱을, 릴레이 보안 모델은 인증 및 신뢰 흐름을 참고하세요.

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last",      },    },  },}

• every: 기간 문자열(30m, 2h). 비활성화하려면 0m으로 설정합니다.
• target: last | none | <channel-id>(예: discord, matrix, telegram, whatsapp)
• directPolicy: DM 스타일 Heartbeat 대상에 대해 allow(기본값) 또는 block
• 전체 가이드는 Heartbeat를 참고하세요.

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // default; cron dispatch + isolated cron agent-turn execution    sessionRetention: "24h",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },}

• sessionRetention: 완료된 격리 실행 세션을 sessions.json에서 정리합니다(기본값 24h; 비활성화하려면 false로 설정).
• runLog: 작업별로 보존된 Cron 실행 기록 행을 정리합니다. maxBytes는 이전 파일 기반 실행 로그용으로 계속 허용됩니다.
• 기능 개요와 CLI 예시는 Cron 작업을 참고하세요.

Gateway에서 HTTP Webhook 엔드포인트를 활성화합니다.

{  hooks: {    enabled: true,    token: "shared-secret",    path: "/hooks",    defaultSessionKey: "hook:ingress",    allowRequestSessionKey: false,    allowedSessionKeyPrefixes: ["hook:"],    mappings: [      {        match: { path: "gmail" },        action: "agent",        agentId: "main",        deliver: true,      },    ],  },}

보안 참고 사항:

• 모든 hook/webhook 페이로드 콘텐츠를 신뢰할 수 없는 입력으로 취급하세요.
• 전용 hooks.token을 사용하세요. 활성 Gateway 인증 비밀(gateway.auth.token / OPENCLAW_GATEWAY_TOKEN 또는 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD)을 재사용하지 마세요.
• Hook 인증은 헤더 전용입니다(Authorization: Bearer ... 또는 x-openclaw-token). 쿼리 문자열 토큰은 거부됩니다.
• hooks.path는 /일 수 없습니다. Webhook 수신은 /hooks 같은 전용 하위 경로에 유지하세요.
• 엄격하게 범위가 제한된 디버깅을 수행하는 경우가 아니라면 안전하지 않은 콘텐츠 우회 플래그(hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent)를 비활성화된 상태로 유지하세요.
• hooks.allowRequestSessionKey를 활성화하는 경우, 호출자가 선택한 세션 키의 범위를 제한하도록 hooks.allowedSessionKeyPrefixes도 설정하세요.
• Hook으로 구동되는 에이전트에는 강력한 최신 모델 티어와 엄격한 도구 정책을 선호하세요(예: 가능한 경우 메시징 전용과 샌드박싱).

모든 매핑 옵션과 Gmail 통합은 전체 참조를 참고하세요.

별도의 작업 영역과 세션을 가진 여러 격리 에이전트를 실행합니다.

{  agents: {    list: [      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },      { id: "work", workspace: "~/.openclaw/workspace-work" },    ],  },  bindings: [    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },  ],}

바인딩 규칙과 에이전트별 액세스 프로필은 다중 에이전트 및 전체 참조를 참고하세요.

$include를 사용해 큰 설정을 구성합니다.

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

• 단일 파일: 포함하는 객체를 대체합니다.
• 파일 배열: 순서대로 깊게 병합됩니다(나중 항목이 우선).
• 형제 키: include 이후 병합됩니다(포함된 값을 재정의).
• 중첩 include: 최대 10단계 깊이까지 지원됩니다.
• 상대 경로: 포함하는 파일을 기준으로 해석됩니다.
• 경로 형식: include 경로에는 null 바이트가 포함될 수 없으며, 해석 전후 모두 4096자보다 엄격히 짧아야 합니다.
• OpenClaw 소유 쓰기: 쓰기가 plugins: { $include: "./plugins.json5" } 같은 단일 파일 include가 뒷받침하는 최상위 섹션 하나만 변경하는 경우, OpenClaw는 해당 포함 파일을 업데이트하고 openclaw.json은 그대로 둡니다.
• 지원되지 않는 write-through: 루트 include, include 배열, 형제 재정의가 있는 include는 설정을 평탄화하는 대신 OpenClaw 소유 쓰기에 대해 닫힌 상태로 실패합니다.
• 제한: $include 경로는 openclaw.json이 있는 디렉터리 아래로 해석되어야 합니다. 여러 머신 또는 사용자 간에 트리를 공유하려면 include가 참조할 수 있는 추가 디렉터리의 경로 목록(POSIX에서는 :, Windows에서는 ;)으로 OPENCLAW_INCLUDE_ROOTS를 설정하세요. 심볼릭 링크는 해석된 뒤 다시 검사되므로, 경로가 문자상으로는 설정 디렉터리 안에 있더라도 실제 대상이 허용된 모든 루트를 벗어나면 여전히 거부됩니다.
• 오류 처리: 누락된 파일, 파싱 오류, 순환 include, 잘못된 경로 형식, 과도한 길이에 대해 명확한 오류를 제공합니다.