구성

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

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

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

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // 페어링 | 허용 목록 | 공개 | 비활성화      allowFrom: ["tg:123"], // 허용 목록/공개에만 사용    },  },}

기본 모델과 선택적 대체 모델을 설정하십시오.

{  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은 트랜스크립트/도구 이미지 다운스케일링을 제어합니다(기본값 1200). 값이 낮을수록 일반적으로 스크린샷이 많은 실행에서 비전 토큰 사용량이 줄어듭니다.
• 채팅에서 모델을 전환하는 방법은 모델 CLI를, 인증 순환 및 대체 동작은 모델 장애 조치를 참조하십시오.
• 사용자 지정/자체 호스팅 제공자는 참조 문서의 사용자 지정 제공자를 참조하십시오.

DM 액세스는 채널별 dmPolicy(기본값 "pairing")을 통해 제어됩니다.

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

그룹에는 groupPolicy("allowlist" | "open" | "disabled")과 groupAllowFrom 또는 채널별 허용 목록을 함께 사용하십시오.

채널별 세부 정보는 전체 참조를 확인하십시오.

그룹 메시지는 기본적으로 멘션 필요로 설정됩니다. 에이전트별 트리거 패턴을 구성하십시오. 일반 그룹/채널 답변은 자동으로 게시됩니다. 에이전트가 언제 말할지 결정해야 하는 공유 대화방에서는 메시지 도구 경로를 사용하도록 설정하십시오.

{  messages: {    visibleReplies: "automatic", // 모든 곳에서 메시지 도구 전송을 요구하려면 "message_tool"로 설정    groupChat: {      visibleReplies: "message_tool", // 명시적 사용 설정; 표시되는 출력에는 message(action=send)가 필요      unmentionedInbound: "room_event", // 멘션되지 않은 상시 그룹 대화는 조용한 컨텍스트    },  },  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을 사용한 다음, 특정 에이전트는 agents.list[].skills으로 재정의하십시오.

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // github, weather 상속      { id: "docs", skills: ["docs-search"] }, // 기본값 대체      { id: "locked-down", skills: [] }, // 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",  // 다중 사용자 환경에 권장    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: 스레드에 바인딩된 세션 라우팅의 전역 기본값입니다. /focus, /unfocus, /agents, /session idle, /session max-age은 세션별로 이를 바인딩, 바인딩 해제, 나열 및 조정합니다(Discord는 스레드를 바인딩하고 Telegram은 토픽/대화를 바인딩합니다).
• 범위 지정, ID 연결 및 전송 정책은 세션 관리를 참조하십시오.
• 모든 필드는 전체 참조를 참조하십시오.

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

{  agents: {    defaults: {      sandbox: {        mode: "non-main",  // 끄기 | 기본 외 | 모두        scope: "agent",    // 세션 | 에이전트 | 공유      },    },  },}

먼저 이미지를 빌드하십시오. 소스 체크아웃에서는 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",          // 선택 사항. 기본값: 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와 페어링하고 Node 및 운영자 세션이 모두 연결되도록 합니다.
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은 루프백 전용 개발 우회 수단으로 유지됩니다. HTTP 릴레이 URL을 구성에 영구 저장하지 마십시오.

엔드투엔드 흐름은 iOS 앱을, 릴레이 보안 모델은 인증 및 신뢰 흐름을 참조하십시오.

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

• every: 기간 문자열(30m, 2h). 비활성화하려면 0m으로 설정하십시오. 기본값: 30m.
• target: last | none | <channel-id>(예: discord, matrix, telegram 또는 whatsapp)
• directPolicy: DM 방식 Heartbeat 대상에는 allow(기본값) 또는 block
• 전체 가이드는 Heartbeat를 참조하십시오.

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // 기본값; Cron 디스패치 + 격리된 Cron 에이전트 턴 실행    sessionRetention: "24h",  },}

• sessionRetention: SQLite 세션 행에서 완료된 격리 실행 세션을 정리합니다(기본값 24h, 비활성화하려면 false으로 설정).
• 실행 기록은 작업별로 최신 터미널 행 2000개를 자동으로 유지하며, 유실된 행에는 24시간 정리 기간이 유지됩니다.
• 기능 개요와 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,      },    ],  },}

보안 참고 사항:

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

모든 매핑 옵션과 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"],  },}

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