설정

각 채널은 `channels.<provider>` 아래에 자체 설정 섹션이 있습니다. 설정 절차는 전용 채널 페이지를 참조하세요:

- [WhatsApp](/docs/channels/whatsapp) — `channels.whatsapp`
- [Telegram](/docs/channels/telegram) — `channels.telegram`
- [Discord](/docs/channels/discord) — `channels.discord`
- [Slack](/docs/channels/slack) — `channels.slack`
- [Signal](/docs/channels/signal) — `channels.signal`
- [iMessage](/docs/channels/imessage) — `channels.imessage`
- [Google Chat](/docs/channels/googlechat) — `channels.googlechat`
- [Mattermost](/docs/channels/mattermost) — `channels.mattermost`
- [MS Teams](/docs/channels/msteams) — `channels.msteams`

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

```json5
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // allowlist/open에서만 사용
    },
  },
}
```

기본 모델과 선택적 폴백을 설정합니다:

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

- `agents.defaults.models`는 모델 카탈로그를 정의하며 `/model`의 허용 목록으로 동작합니다.
- 모델 참조는 `provider/model` 형식을 사용합니다 (예: `anthropic/claude-opus-4-6`).
- `agents.defaults.imageMaxDimensionPx`는 제공자 호출 전 트랜스크립트/도구 이미지의 다운스케일링을 제어합니다 (기본값 `1200`). 낮은 값은 대개 스크린샷 집약적 실행에서 비전 토큰 사용량을 줄입니다.
- 채팅에서 모델 전환은 [모델 CLI](/docs/concepts/models)를, 인증 로테이션 및 폴백 동작은 [모델 페일오버](/docs/concepts/model-failover)를 참조하세요.
- 커스텀/셀프 호스팅 제공자에 대해서는 레퍼런스의 [커스텀 제공자](/docs/gateway/configuration-reference#custom-providers-and-base-urls)를 참조하세요.

DM 접근은 `dmPolicy`로 채널별로 제어됩니다:

- `"pairing"` (기본값): 알 수 없는 발신자가 승인할 일회성 페어링 코드를 받음
- `"allowlist"`: `allowFrom` (또는 페어링 허용 저장소)에 있는 발신자만
- `"open"`: 모든 수신 DM 허용 (`allowFrom: ["*"]` 필요)
- `"disabled"`: 모든 DM 무시

그룹의 경우, `groupPolicy` + `groupAllowFrom` 또는 채널별 허용 목록을 사용하세요.

채널별 세부 정보는 [전체 레퍼런스](/docs/gateway/configuration-reference#dm-and-group-access)를 참조하세요.

그룹 메시지는 기본적으로 **멘션 필요**입니다. 에이전트별로 패턴을 설정합니다:

```json5
{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
```

- **메타데이터 멘션**: 네이티브 @-멘션 (WhatsApp 탭하여 멘션, Telegram @bot 등)
- **텍스트 패턴**: `mentionPatterns`의 정규식 패턴
- 멘션 게이팅은 감지가 가능한 경우(네이티브 멘션 또는 최소 하나의 패턴)에만 적용됨을 참조하세요.

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

```json5
{
  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`: 스레드 바인딩 세션 라우팅의 전역 기본값 (Discord는 `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` 지원).
- 범위 지정, ID 링크, 전송 정책에 대해서는 [세션 관리](/docs/concepts/session)를 참조하세요.
- 모든 필드는 [전체 레퍼런스](/docs/gateway/configuration-reference#session)를 참조하세요.

에이전트 세션을 격리된 Docker 컨테이너에서 실행합니다:

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

먼저 이미지를 빌드합니다: `scripts/sandbox-setup.sh`

전체 가이드는 [샌드박싱](/docs/gateway/sandboxing)을, 모든 옵션은 [전체 레퍼런스](/docs/gateway/configuration-reference#sandbox)를 참조하세요.

릴레이 기반 푸시는 `openclaw.json`에서 설정합니다.

게이트웨이 설정에 다음을 추가합니다:

```json5
{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // 선택적. 기본값: 10000
          timeoutMs: 10000,
        },
      },
    },
  },
}
```

CLI 동등 명령어:

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

동작 설명:

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

엔드 투 엔드 흐름:

1. 동일한 릴레이 기본 URL로 컴파일된 공식/TestFlight iOS 빌드를 설치합니다.
2. 게이트웨이에서 `gateway.push.apns.relay.baseUrl`을 설정합니다.
3. iOS 앱을 게이트웨이에 페어링하고 노드와 오퍼레이터 세션이 모두 연결되도록 합니다.
4. iOS 앱이 게이트웨이 ID를 가져오고, App Attest와 앱 영수증을 사용하여 릴레이에 등록한 다음, 페어링된 게이트웨이에 릴레이 기반 `push.apns.register` 페이로드를 게시합니다.
5. 게이트웨이가 릴레이 핸들과 전송 권한을 저장한 다음, `push.test`, 웨이크 넛지, 재연결 웨이크에 사용합니다.

운영 참고 사항:

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

호환성 참고:

- `OPENCLAW_APNS_RELAY_BASE_URL`과 `OPENCLAW_APNS_RELAY_TIMEOUT_MS`는 임시 환경 오버라이드로 여전히 동작합니다.
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`는 루프백 전용 개발 이스케이프 해치로 유지됩니다. HTTP 릴레이 URL을 설정에 영구 저장하지 마세요.

엔드 투 엔드 흐름은 [iOS 앱](/docs/platforms/ios#relay-backed-push-for-official-builds)을, 릴레이 보안 모델은 [인증 및 신뢰 흐름](/docs/platforms/ios#authentication-and-trust-flow)을 참조하세요.

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

- `every`: 기간 문자열 (`30m`, `2h`). `0m`으로 설정하면 비활성화.
- `target`: `last` | `whatsapp` | `telegram` | `discord` | `none`
- `directPolicy`: `allow` (기본값) 또는 DM 스타일 하트비트 대상에 대해 `block`
- 전체 가이드는 [하트비트](/docs/gateway/heartbeat)를 참조하세요.

```json5
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}
```

- `sessionRetention`: `sessions.json`에서 완료된 격리 실행 세션을 정리합니다 (기본값 `24h`; `false`로 비활성화).
- `runLog`: 크기와 유지 줄 수에 따라 `cron/runs/<jobId>.jsonl`을 정리합니다.
- 기능 개요 및 CLI 예시는 [크론 작업](/docs/automation/cron-jobs)을 참조하세요.

게이트웨이에서 HTTP 웹훅 엔드포인트를 활성화합니다:

```json5
{
  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.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`). 엄격하게 범위가 지정된 디버깅이 아니라면 사용하지 마세요.
- hook 구동 에이전트의 경우, 강력한 최신 모델 계층과 엄격한 도구 정책(예: 메시징 전용 + 가능한 경우 샌드박싱)을 선호하세요.

모든 매핑 옵션과 Gmail 연동은 [전체 레퍼런스](/docs/gateway/configuration-reference#hooks)를 참조하세요.

별도의 워크스페이스와 세션을 가진 여러 격리된 에이전트를 실행합니다:

```json5
{
  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" } },
  ],
}
```

바인딩 규칙과 에이전트별 접근 프로필은 [멀티 에이전트](/docs/concepts/multi-agent)와 [전체 레퍼런스](/docs/gateway/configuration-reference#multi-agent-routing)를 참조하세요.

`$include`를 사용하여 대규모 설정을 정리합니다:

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

- **단일 파일**: 포함하는 객체를 대체
- **파일 배열**: 순서대로 딥 머지 (나중 것이 우선)
- **형제 키**: 인클루드 후 머지 (인클루드된 값을 오버라이드)
- **중첩 인클루드**: 최대 10 레벨까지 지원
- **상대 경로**: 인클루드하는 파일 기준으로 해석
- **오류 처리**: 누락된 파일, 파싱 오류, 순환 인클루드에 대한 명확한 오류

전체 설정을 유효성 검사 + 기록하고 한 번에 게이트웨이를 재시작합니다.

> **경고:** `config.apply`는 **전체 설정**을 교체합니다. 부분 업데이트에는 `config.patch`를, 단일 키에는 `openclaw config set`을 사용하세요.

매개변수:

- `raw` (문자열) — 전체 설정에 대한 JSON5 페이로드
- `baseHash` (선택적) — `config.get`에서 받은 설정 해시 (설정이 존재할 때 필수)
- `sessionKey` (선택적) — 재시작 후 웨이크업 핑을 위한 세션 키
- `note` (선택적) — 재시작 센티널용 메모
- `restartDelayMs` (선택적) — 재시작 전 지연 시간 (기본값 2000)

이미 대기 중/진행 중인 재시작 요청은 통합되며, 재시작 주기 간 30초 쿨다운이 적용됩니다.

```bash
openclaw gateway call config.get --params '{}'  # payload.hash 캡처
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
  "baseHash": "<hash>",
  "sessionKey": "agent:main:whatsapp:direct:+15555550123"
}'
```

기존 설정에 부분 업데이트를 머지합니다 (JSON 머지 패치 시맨틱스):

- 객체는 재귀적으로 머지
- `null`은 키를 삭제
- 배열은 교체

매개변수:

- `raw` (문자열) — 변경할 키만 포함된 JSON5
- `baseHash` (필수) — `config.get`에서 받은 설정 해시
- `sessionKey`, `note`, `restartDelayMs` — `config.apply`와 동일

재시작 동작은 `config.apply`와 동일: 대기 중인 재시작을 통합하고 재시작 주기 간 30초 쿨다운 적용.

```bash
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'
```

활성화하고 예상 키가 설정되지 않은 경우, OpenClaw는 로그인 셸을 실행하고 누락된 키만 가져옵니다:

{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}

환경 변수 동등: OPENCLAW_LOAD_SHELL_ENV=1

모든 설정 문자열 값에서 ${VAR_NAME}으로 환경 변수를 참조합니다:

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

규칙:

• 대문자 이름만 매칭: [A-Z_][A-Z0-9_]*
• 누락/비어있는 변수는 로드 시 오류 발생
• $${VAR}로 리터럴 출력을 이스케이프
• $include 파일 내에서도 동작
• 인라인 치환: "${BASE}/v1" → "https://api.example.com/v1"

SecretRef 객체를 지원하는 필드의 경우 다음을 사용할 수 있습니다:

{
  models: {
    providers: {
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
  skills: {
    entries: {
      "nano-banana-pro": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/nano-banana-pro/apiKey",
        },
      },
    },
  },
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount",
      },
    },
  },
}

SecretRef 세부 사항(env/file/exec에 대한 secrets.providers 포함)은 시크릿 관리를 참조하세요. 지원되는 자격 증명 경로는 SecretRef 자격 증명 표면에 나열되어 있습니다.