설정

각 채널에는 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의 허용 목록 역할을 합니다.
• 기존 모델을 제거하지 않고 허용 목록 항목을 추가하려면 openclaw config set agents.defaults.models '<json>' --strict-json --merge를 사용하세요. 항목을 제거하는 일반 대체는 --replace를 전달하지 않으면 거부됩니다.
• 모델 참조는 provider/model 형식(예: anthropic/claude-opus-4-6)을 사용합니다.
• agents.defaults.imageMaxDimensionPx는 transcript/tool 이미지 다운스케일링을 제어합니다(기본값 1200). 낮은 값은 보통 스크린샷이 많은 실행에서 비전 토큰 사용량을 줄입니다.
• 채팅에서 모델을 전환하려면 Models CLI를, 인증 순환 및 대체 동작은 Model Failover를 참조하세요.
• 사용자 지정/자체 호스팅 provider는 참조의 사용자 지정 provider를 참조하세요.

DM 액세스는 dmPolicy를 통해 채널별로 제어됩니다.

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

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

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

그룹 메시지는 기본적으로 멘션 필요입니다. 에이전트별 트리거 패턴을 구성하고, 레거시 자동 최종 답장을 의도적으로 원하는 경우가 아니라면 표시되는 방 답장은 기본 메시지 도구 경로에 유지하세요.

{
  messages: {
    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere
    groupChat: {
      visibleReplies: "message_tool", // default; use "automatic" for legacy room replies
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

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

공유 기준선에는 agents.defaults.skills를 사용한 다음, 특정 에이전트는 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 명령을 참고하세요.

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

릴레이 기반 푸시는 openclaw.json에서 구성합니다.

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를 계속 사용합니다. 릴레이 기반 전송은 릴레이를 통해 등록된 공식 배포 빌드에만 적용됩니다.
• 등록 트래픽과 전송 트래픽이 같은 릴레이 배포에 도달하도록, 공식/TestFlight iOS 빌드에 내장된 릴레이 기본 URL과 일치해야 합니다.

엔드투엔드 흐름:

1. 동일한 릴레이 기본 URL로 컴파일된 공식/TestFlight 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는 임시 환경 변수 재정의로 계속 작동합니다.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true는 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: 2, // cron dispatch + isolated cron agent-turn execution
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

• sessionRetention: 완료된 격리 실행 세션을 sessions.json에서 정리합니다(기본값 24h; 비활성화하려면 false로 설정).
• runLog: 크기와 보존된 줄 수를 기준으로 cron/runs/<jobId>.jsonl을 정리합니다.
• 기능 개요와 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 토큰을 재사용하지 마세요.
• 훅 인증은 헤더 전용입니다(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"],
  },
}

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