구성

각 채널은 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",   // pairing | allowlist | open | disabled      allowFrom: ["tg:123"], // 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는 대화 기록/도구 이미지의 축소 크기를 제어합니다(기본값 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",  // 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",          // 선택 사항. 기본값: 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",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },}

• sessionRetention: SQLite 세션 행에서 완료된 격리 실행 세션을 정리합니다(기본값 24h; 비활성화하려면 false로 설정).
• runLog: 작업별로 보존된 Cron 실행 기록 행을 정리합니다. 기록은 SQLite에 저장되며, maxBytes(기본값 2_000_000)는 이전 파일 기반 실행 로그와의 호환성을 위해 유지되고 keepLines의 기본값은 2000입니다.
• 기능 개요와 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"],  },}

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