구성 🔧

OpenClaw는 ~/.openclaw/openclaw.json에서 선택적 JSON5 구성을 읽습니다(주석 + 후행 쉼표 허용).

파일이 없으면 OpenClaw는 안전한 기본값을 사용합니다(임베디드 Pi 에이전트 + 발신자별 세션 + 작업 공간 ~/.openclaw/workspace). 일반적으로 다음과 같은 경우에만 구성이 필요합니다:

• 봇을 트리거할 수 있는 사용자 제한(channels.whatsapp.allowFrom, channels.telegram.allowFrom 등)
• 그룹 허용 목록 + 멘션 동작 제어(channels.whatsapp.groups, channels.telegram.groups, channels.discord.guilds, agents.list[].groupChat)
• 메시지 접두사 사용자 지정(messages)
• 에이전트의 작업 공간 설정(agents.defaults.workspace 또는 agents.list[].workspace)
• 임베디드 에이전트 기본값(agents.defaults) 및 세션 동작(session) 조정
• 에이전트별 정체성 설정(agents.list[].identity)

구성이 처음이신가요? 자세한 설명이 포함된 전체 예제는 구성 예제 가이드를 확인하세요!

엄격한 구성 유효성 검사

OpenClaw는 스키마와 완전히 일치하는 구성만 허용합니다. 알 수 없는 키, 잘못된 형식의 타입 또는 잘못된 값이 있으면 Gateway가 안전을 위해 시작을 거부합니다.

유효성 검사가 실패하면:

• Gateway가 부팅되지 않습니다.
• 진단 명령만 허용됩니다(예: openclaw doctor, openclaw logs, openclaw health, openclaw status, openclaw service, openclaw help).
• openclaw doctor를 실행하여 정확한 문제를 확인하세요.
• openclaw doctor --fix(또는 --yes)를 실행하여 마이그레이션/수리를 적용하세요.

Doctor는 명시적으로 --fix/--yes를 선택하지 않는 한 변경 사항을 작성하지 않습니다.

스키마 + UI 힌트

Gateway는 UI 편집기를 위해 config.schema를 통해 구성의 JSON Schema 표현을 노출합니다. Control UI는 이 스키마에서 폼을 렌더링하며, Raw JSON 편집기를 탈출구로 제공합니다.

채널 플러그인 및 확장은 구성에 대한 스키마 + UI 힌트를 등록할 수 있으므로 채널 설정이 하드코딩된 폼 없이 앱 전체에서 스키마 기반으로 유지됩니다.

힌트(레이블, 그룹화, 민감한 필드)는 스키마와 함께 제공되므로 클라이언트가 구성 지식을 하드코딩하지 않고도 더 나은 폼을 렌더링할 수 있습니다.

Apply + restart (RPC)

config.apply를 사용하여 전체 구성을 유효성 검사 + 작성하고 Gateway를 한 번에 재시작하세요. 재시작 센티널을 작성하고 Gateway가 다시 시작된 후 마지막 활성 세션에 핑을 보냅니다.

경고: config.apply는 전체 구성을 대체합니다. 몇 개의 키만 변경하려면 config.patch 또는 openclaw config set을 사용하세요. ~/.openclaw/openclaw.json의 백업을 유지하세요.

매개변수:

• raw (문자열) — 전체 구성에 대한 JSON5 페이로드
• baseHash (선택 사항) — config.get의 구성 해시(구성이 이미 있는 경우 필수)
• sessionKey (선택 사항) — 재시작 핑을 위한 마지막 활성 세션 키
• note (선택 사항) — 재시작 센티널에 포함할 메모
• restartDelayMs (선택 사항) — 재시작 전 지연(기본값 2000)

예제(gateway call을 통해):

openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{\\n  agents: { defaults: { workspace: \\"~/.openclaw/workspace\\" } }\\n}\\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

부분 업데이트 (RPC)

config.patch를 사용하여 관련 없는 키를 덮어쓰지 않고 부분 업데이트를 기존 구성에 병합하세요. JSON 병합 패치 의미 체계를 적용합니다:

• 객체는 재귀적으로 병합
• null은 키 삭제
• 배열은 대체 config.apply와 마찬가지로 유효성을 검사하고 구성을 작성하며 재시작 센티널을 저장하고 Gateway 재시작을 예약합니다(sessionKey가 제공된 경우 선택적 재시작 알림 포함).

매개변수:

• raw (문자열) — 변경할 키만 포함하는 JSON5 페이로드
• baseHash (필수) — config.get의 구성 해시
• sessionKey (선택 사항) — 재시작 핑을 위한 마지막 활성 세션 키
• note (선택 사항) — 재시작 센티널에 포함할 메모
• restartDelayMs (선택 사항) — 재시작 전 지연(기본값 2000)

예제:

openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.patch --params '{
  "raw": "{\\n  channels: { telegram: { groups: { \\"*\\": { requireMention: false } } } }\\n}\\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

최소 구성 (권장 시작점)

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } }
}

다음 명령으로 기본 이미지를 한 번 빌드합니다:

scripts/sandbox-setup.sh

셀프 채팅 모드 (그룹 제어에 권장)

그룹에서 WhatsApp @-멘션에 응답하지 않도록 하려면(특정 텍스트 트리거에만 응답):

{
  agents: {
    defaults: { workspace: "~/.openclaw/workspace" },
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["@openclaw", "reisponde"] }
      }
    ]
  },
  channels: {
    whatsapp: {
      // 허용 목록은 DM 전용입니다; 자신의 번호를 포함하면 셀프 채팅 모드가 활성화됩니다.
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } }
    }
  }
}

구성 포함 ($include)

$include 지시문을 사용하여 구성을 여러 파일로 분할합니다. 다음과 같은 경우에 유용합니다:

• 대규모 구성 구성(예: 클라이언트별 에이전트 정의)
• 환경 간 공통 설정 공유
• 민감한 구성을 별도로 유지

기본 사용법

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  
  // 단일 파일 포함(키의 값을 대체)
  agents: { "$include": "./agents.json5" },
  
  // 여러 파일 포함(순서대로 깊이 병합)
  broadcast: { 
    "$include": [
      "./clients/mueller.json5",
      "./clients/schmidt.json5"
    ]
  }
}

// ~/.openclaw/agents.json5
{
  defaults: { sandbox: { mode: "all", scope: "session" } },
  list: [
    { id: "main", workspace: "~/.openclaw/workspace" }
  ]
}

병합 동작

• 단일 파일: $include가 포함된 객체를 대체
• 파일 배열: 파일을 순서대로 깊이 병합(나중 파일이 이전 파일을 재정의)
• 형제 키 포함: 포함 후 형제 키가 병합됩니다(포함된 값을 재정의)
• 형제 키 + 배열/원시값: 지원되지 않음(포함된 콘텐츠는 객체여야 함)

// 형제 키는 포함된 값을 재정의합니다
{
  "$include": "./base.json5",   // { a: 1, b: 2 }
  b: 99                          // 결과: { a: 1, b: 99 }
}

중첩 포함

포함된 파일 자체에 $include 지시문이 포함될 수 있습니다(최대 10레벨 깊이):

// clients/mueller.json5
{
  agents: { "$include": "./mueller/agents.json5" },
  broadcast: { "$include": "./mueller/broadcast.json5" }
}

경로 해석

• 상대 경로: 포함하는 파일을 기준으로 해석
• 절대 경로: 그대로 사용
• 상위 디렉토리: ../ 참조가 예상대로 작동

{ "$include": "./sub/config.json5" }      // 상대 경로
{ "$include": "/etc/openclaw/base.json5" } // 절대 경로
{ "$include": "../shared/common.json5" }   // 상위 디렉토리

오류 처리

• 파일 누락: 해석된 경로와 함께 명확한 오류
• 파싱 오류: 실패한 포함 파일 표시
• 순환 포함: 포함 체인과 함께 감지 및 보고

예제: 다중 클라이언트 법률 설정

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789, auth: { token: "secret" } },
  
  // 공통 에이전트 기본값
  agents: {
    defaults: {
      sandbox: { mode: "all", scope: "session" }
    },
    // 모든 클라이언트의 에이전트 목록 병합
    list: { "$include": [
      "./clients/mueller/agents.json5",
      "./clients/schmidt/agents.json5"
    ]}
  },
  
  // 브로드캐스트 구성 병합
  broadcast: { "$include": [
    "./clients/mueller/broadcast.json5",
    "./clients/schmidt/broadcast.json5"
  ]},
  
  channels: { whatsapp: { groupPolicy: "allowlist" } }
}

// ~/.openclaw/clients/mueller/agents.json5
[
  { id: "mueller-transcribe", workspace: "~/clients/mueller/transcribe" },
  { id: "mueller-docs", workspace: "~/clients/mueller/docs" }
]

// ~/.openclaw/clients/mueller/broadcast.json5
{
  "[email protected]": ["mueller-transcribe", "mueller-docs"]
}

공통 옵션

환경 변수 + .env

OpenClaw는 상위 프로세스(셸, launchd/systemd, CI 등)에서 환경 변수를 읽습니다.

또한 다음을 로드합니다:

• 현재 작업 디렉토리의 .env(있는 경우)
• ~/.openclaw/.env(즉, $OPENCLAW_STATE_DIR/.env)의 전역 대체 .env

두 .env 파일 모두 기존 환경 변수를 재정의하지 않습니다.

구성에서 인라인 환경 변수를 제공할 수도 있습니다. 이는 프로세스 환경에 키가 누락된 경우에만 적용됩니다(동일한 비재정의 규칙):

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-..."
    }
  }
}

전체 우선 순위 및 소스는 /environment를 참조하세요.

env.shellEnv (선택 사항)

옵트인 편의 기능: 활성화되고 예상 키가 아직 설정되지 않은 경우 OpenClaw는 로그인 셸을 실행하고 누락된 예상 키만 가져옵니다(재정의하지 않음). 이는 셸 프로필을 효과적으로 소싱합니다.

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

환경 변수 등가물:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

구성의 환경 변수 치환

${VAR_NAME} 구문을 사용하여 구성 문자열 값에서 직접 환경 변수를 참조할 수 있습니다. 변수는 유효성 검사 전 구성 로드 시 치환됩니다.

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}"
      }
    }
  },
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    }
  }
}

규칙:

• 대문자 환경 변수 이름만 일치: [A-Z_][A-Z0-9_]*
• 누락되거나 비어 있는 환경 변수는 구성 로드 시 오류를 발생시킵니다
• $${VAR}로 이스케이프하여 리터럴 ${VAR} 출력
• $include와 함께 작동(포함된 파일도 치환 가능)

인라인 치환:

{
  models: {
    providers: {
      custom: {
        baseUrl: "${CUSTOM_API_BASE}/v1"  // → "https://api.example.com/v1"
      }
    }
  }
}

인증 스토리지 (OAuth + API 키)

OpenClaw는 에이전트별 인증 프로필(OAuth + API 키)을 다음에 저장합니다:

• <agentDir>/auth-profiles.json(기본값: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json)

참조: /concepts/oauth

레거시 OAuth 가져오기:

• ~/.openclaw/credentials/oauth.json(또는 $OPENCLAW_STATE_DIR/credentials/oauth.json)

임베디드 Pi 에이전트는 다음 위치에서 런타임 캐시를 유지합니다:

• <agentDir>/auth.json(자동으로 관리됨; 수동으로 편집하지 마세요)

레거시 에이전트 디렉토리(다중 에이전트 이전):

• ~/.openclaw/agent/*(openclaw doctor에 의해 ~/.openclaw/agents/<defaultAgentId>/agent/*로 마이그레이션됨)

재정의:

• OAuth 디렉토리(레거시 가져오기만): OPENCLAW_OAUTH_DIR
• 에이전트 디렉토리(기본 에이전트 루트 재정의): OPENCLAW_AGENT_DIR(권장), PI_CODING_AGENT_DIR(레거시)

첫 사용 시 OpenClaw는 oauth.json 항목을 auth-profiles.json으로 가져옵니다.

auth

인증 프로필에 대한 선택적 메타데이터입니다. 비밀을 저장하지 않습니다; 프로필 ID를 공급자 + 모드(및 선택적 이메일)에 매핑하고 장애 조치에 사용되는 공급자 순환 순서를 정의합니다.

{
  auth: {
    profiles: {
      "anthropic:[email protected]": { provider: "anthropic", mode: "oauth", email: "[email protected]" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" }
    },
    order: {
      anthropic: ["anthropic:[email protected]", "anthropic:work"]
    }
  }
}

agents.list[].identity

기본값 및 UX에 사용되는 선택적 에이전트별 정체성입니다. 이는 macOS 온보딩 어시스턴트에 의해 작성됩니다.

설정된 경우 OpenClaw는 기본값을 파생합니다(명시적으로 설정하지 않은 경우에만):

• 활성 에이전트의 identity.emoji에서 messages.ackReaction(👀로 대체)
• 에이전트의 identity.name/identity.emoji에서 agents.list[].groupChat.mentionPatterns(Telegram/Slack/Discord/Google Chat/iMessage/WhatsApp의 그룹에서 "@Samantha"가 작동하도록)
• identity.avatar는 작업 공간 상대 이미지 경로 또는 원격 URL/데이터 URL을 허용합니다. 로컬 파일은 에이전트 작업 공간 내에 있어야 합니다.

identity.avatar는 다음을 허용합니다:

• 작업 공간 상대 경로(에이전트 작업 공간 내에 있어야 함)
• http(s) URL
• data: URI

{
  agents: {
    list: [
      {
        id: "main",
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png"
        }
      }
    ]
  }
}

wizard

CLI 마법사(onboard, configure, doctor)에 의해 작성된 메타데이터입니다.

{
  wizard: {
    lastRunAt: "2026-01-01T00:00:00.000Z",
    lastRunVersion: "2026.1.4",
    lastRunCommit: "abc1234",
    lastRunCommand: "configure",
    lastRunMode: "local"
  }
}

logging

• 기본 로그 파일: /tmp/openclaw/openclaw-YYYY-MM-DD.log
• 안정적인 경로를 원하면 logging.file을 /tmp/openclaw/openclaw.log로 설정하세요.
• 콘솔 출력은 다음을 통해 별도로 조정할 수 있습니다:
  • logging.consoleLevel(기본값 info, --verbose일 때 debug로 증가)
  • logging.consoleStyle(pretty | compact | json)
• 툴 요약은 비밀 유출을 피하기 위해 수정할 수 있습니다:
  • logging.redactSensitive(off | tools, 기본값: tools)
  • logging.redactPatterns(정규식 문자열 배열; 기본값 재정의)

{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools",
    redactPatterns: [
      // 예제: 자체 규칙으로 기본값 재정의.
      "\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1",
      "/\\bsk-[A-Za-z0-9_-]{8,}\\b/gi"
    ]
  }
}

channels.whatsapp.dmPolicy

WhatsApp 다이렉트 채팅(DM)을 처리하는 방법을 제어합니다:

• "pairing"(기본값): 알 수 없는 발신자는 페어링 코드를 받습니다; 소유자가 승인해야 합니다
• "allowlist": channels.whatsapp.allowFrom(또는 페어링된 허용 저장소)의 발신자만 허용
• "open": 모든 인바운드 DM 허용(channels.whatsapp.allowFrom에 "*"가 포함되어야 함)
• "disabled": 모든 인바운드 DM 무시

페어링 코드는 1시간 후에 만료됩니다; 봇은 새 요청이 생성될 때만 페어링 코드를 보냅니다. 대기 중인 DM 페어링 요청은 기본적으로 채널당 3개로 제한됩니다.

페어링 승인:

• openclaw pairing list whatsapp
• openclaw pairing approve whatsapp <code>

channels.whatsapp.allowFrom

WhatsApp 자동 응답을 트리거할 수 있는 E.164 전화번호의 허용 목록입니다(DM 전용). 비어 있고 channels.whatsapp.dmPolicy="pairing"인 경우 알 수 없는 발신자는 페어링 코드를 받습니다. 그룹의 경우 channels.whatsapp.groupPolicy + channels.whatsapp.groupAllowFrom을 사용하세요.

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000, // 선택적 아웃바운드 청크 크기(문자)
      chunkMode: "length", // 선택적 청킹 모드(length | newline)
      mediaMaxMb: 50 // 선택적 인바운드 미디어 제한(MB)
    }
  }
}

channels.whatsapp.sendReadReceipts

인바운드 WhatsApp 메시지를 읽음으로 표시할지(파란색 체크 표시) 제어합니다. 기본값: true.

셀프 채팅 모드는 활성화되어 있어도 항상 읽음 확인을 건너뜁니다.

계정별 재정의: channels.whatsapp.accounts.<id>.sendReadReceipts.

{
  channels: {
    whatsapp: { sendReadReceipts: false }
  }
}

channels.whatsapp.accounts (다중 계정)

하나의 Gateway에서 여러 WhatsApp 계정을 실행합니다:

{
  channels: {
    whatsapp: {
      accounts: {
        default: {}, // 선택 사항; 기본 ID를 안정적으로 유지
        personal: {},
        biz: {
          // 선택적 재정의. 기본값: ~/.openclaw/credentials/whatsapp/biz
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        }
      }
    }
  }
}

참고:

• 아웃바운드 명령은 default 계정이 있는 경우 기본값으로 사용됩니다; 그렇지 않으면 첫 번째로 구성된 계정 ID(정렬됨)를 사용합니다.
• 레거시 단일 계정 Baileys 인증 디렉토리는 openclaw doctor에 의해 whatsapp/default로 마이그레이션됩니다.

channels.telegram.accounts / channels.discord.accounts / channels.googlechat.accounts / channels.slack.accounts / channels.mattermost.accounts / channels.signal.accounts / channels.imessage.accounts

채널당 여러 계정을 실행합니다(각 계정에는 자체 accountId와 선택적 name이 있음):

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC..."
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ..."
        }
      }
    }
  }
}

참고:

• accountId가 생략되면 default가 사용됩니다(CLI + 라우팅).
• 환경 토큰은 기본 계정에만 적용됩니다.
• 기본 채널 설정(그룹 정책, 멘션 게이팅 등)은 계정별로 재정의하지 않는 한 모든 계정에 적용됩니다.
• bindings[].match.accountId를 사용하여 각 계정을 다른 agents.defaults로 라우팅합니다.

그룹 채팅 멘션 게이팅 (agents.list[].groupChat + messages.groupChat)

그룹 메시지는 기본적으로 멘션 필요(메타데이터 멘션 또는 정규식 패턴)입니다. WhatsApp, Telegram, Discord, Google Chat 및 iMessage 그룹 채팅에 적용됩니다.

멘션 타입:

• 메타데이터 멘션: 네이티브 플랫폼 @-멘션(예: WhatsApp 탭하여 멘션). WhatsApp 셀프 채팅 모드에서 무시됨(channels.whatsapp.allowFrom 참조).
• 텍스트 패턴: agents.list[].groupChat.mentionPatterns에 정의된 정규식 패턴. 셀프 채팅 모드와 관계없이 항상 확인됩니다.
• 멘션 게이팅은 멘션 감지가 가능한 경우에만 적용됩니다(네이티브 멘션 또는 최소 하나의 mentionPattern).

{
  messages: {
    groupChat: { historyLimit: 50 }
  },
  agents: {
    list: [
      { id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }
    ]
  }
}

messages.groupChat.historyLimit은 그룹 히스토리 컨텍스트의 전역 기본값을 설정합니다. 채널은 channels.<channel>.historyLimit(또는 다중 계정의 경우 channels.<channel>.accounts.*.historyLimit)으로 재정의할 수 있습니다. 히스토리 래핑을 비활성화하려면 0으로 설정하세요.

DM 히스토리 제한

DM 대화는 에이전트가 관리하는 세션 기반 히스토리를 사용합니다. DM 세션당 유지되는 사용자 턴 수를 제한할 수 있습니다:

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,  // DM 세션을 30 사용자 턴으로 제한
      dms: {
        "123456789": { historyLimit: 50 }  // 사용자별 재정의(사용자 ID)
      }
    }
  }
}

해결 순서:

1. DM별 재정의: channels.<provider>.dms[userId].historyLimit
2. 공급자 기본값: channels.<provider>.dmHistoryLimit
3. 제한 없음(모든 히스토리 유지)

지원되는 공급자: telegram, whatsapp, discord, slack, signal, imessage, msteams.

에이전트별 재정의(설정되면 우선 순위가 높음, []도 포함):

{
  agents: {
    list: [
      { id: "work", groupChat: { mentionPatterns: ["@workbot", "\\+15555550123"] } },
      { id: "personal", groupChat: { mentionPatterns: ["@homebot", "\\+15555550999"] } }
    ]
  }
}

멘션 게이팅 기본값은 채널별로 설정됩니다(channels.whatsapp.groups, channels.telegram.groups, channels.imessage.groups, channels.discord.guilds). *.groups가 설정되면 그룹 허용 목록으로도 작동합니다; 모든 그룹을 허용하려면 "*"를 포함하세요.

특정 텍스트 트리거에만 응답하려면(네이티브 @-멘션 무시):

{
  channels: {
    whatsapp: {
      // 자신의 번호를 포함하여 셀프 채팅 모드를 활성화합니다(네이티브 @-멘션 무시).
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } }
    }
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          // 이 텍스트 패턴만 응답을 트리거합니다
          mentionPatterns: ["reisponde", "@openclaw"]
        }
      }
    ]
  }
}

그룹 정책 (채널별)

channels.*.groupPolicy를 사용하여 그룹/룸 메시지를 전혀 받아들일지 제어합니다:

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"]
    },
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["tg:123456789", "@alice"]
    },
    signal: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"]
    },
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["chat_id:123"]
    },
    msteams: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["[email protected]"]
    },
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        "GUILD_ID": {
          channels: { help: { allow: true } }
        }
      }
    },
    slack: {
      groupPolicy: "allowlist",
      channels: { "#general": { allow: true } }
    }
  }
}

참고:

• "open": 그룹이 허용 목록을 우회합니다; 멘션 게이팅은 여전히 적용됩니다.
• "disabled": 모든 그룹/룸 메시지를 차단합니다.
• "allowlist": 구성된 허용 목록과 일치하는 그룹/룸만 허용합니다.
• channels.defaults.groupPolicy는 공급자의 groupPolicy가 설정되지 않은 경우 기본값을 설정합니다.
• WhatsApp/Telegram/Signal/iMessage/Microsoft Teams는 groupAllowFrom을 사용합니다(대체: 명시적 allowFrom).
• Discord/Slack은 채널 허용 목록을 사용합니다(channels.discord.guilds.*.channels, channels.slack.channels).
• 그룹 DM(Discord/Slack)은 여전히 dm.groupEnabled + dm.groupChannels에 의해 제어됩니다.
• 기본값은 groupPolicy: "allowlist"입니다(channels.defaults.groupPolicy로 재정의하지 않는 한); 허용 목록이 구성되지 않은 경우 그룹 메시지가 차단됩니다.

다중 에이전트 라우팅 (agents.list + bindings)

하나의 Gateway 내에서 여러 격리된 에이전트(별도의 작업 공간, agentDir, 세션)를 실행합니다. 인바운드 메시지는 바인딩을 통해 에이전트로 라우팅됩니다.

• agents.list[]: 에이전트별 재정의.
  • id: 안정적인 에이전트 ID(필수).
  • default: 선택 사항; 여러 개가 설정된 경우 첫 번째가 우선되고 경고가 기록됩니다. 설정되지 않은 경우 목록의 첫 번째 항목이 기본 에이전트입니다.
  • name: 에이전트의 표시 이름.
  • workspace: 기본값 ~/.openclaw/workspace-<agentId>(main의 경우 agents.defaults.workspace로 대체).
  • agentDir: 기본값 ~/.openclaw/agents/<agentId>/agent.
  • model: 에이전트별 기본 모델, 해당 에이전트의 agents.defaults.model을 재정의합니다.
    • 문자열 형식: "provider/model", agents.defaults.model.primary만 재정의
    • 객체 형식: { primary, fallbacks }(fallbacks는 agents.defaults.model.fallbacks를 재정의; []는 해당 에이전트의 전역 fallbacks를 비활성화)
  • identity: 에이전트별 이름/테마/이모지(멘션 패턴 + ack 반응에 사용).
  • groupChat: 에이전트별 멘션 게이팅(mentionPatterns).
  • sandbox: 에이전트별 샌드박스 구성(agents.defaults.sandbox 재정의).
    • mode: "off" | "non-main" | "all"
    • workspaceAccess: "none" | "ro" | "rw"
    • scope: "session" | "agent" | "shared"
    • workspaceRoot: 사용자 지정 샌드박스 작업 공간 루트
    • docker: 에이전트별 도커 재정의(예: image, network, env, setupCommand, 제한; scope: "shared"일 때 무시됨)
    • browser: 에이전트별 샌드박스 브라우저 재정의(scope: "shared"일 때 무시됨)
    • prune: 에이전트별 샌드박스 정리 재정의(scope: "shared"일 때 무시됨)
  • subagents: 에이전트별 서브 에이전트 기본값.
    • allowAgents: 이 에이전트에서 sessions_spawn을 위한 에이전트 ID의 허용 목록(["*"] = 모든 허용; 기본값: 동일한 에이전트만)
  • tools: 에이전트별 도구 제한(샌드박스 도구 정책 전에 적용).
    • profile: 기본 도구 프로필(allow/deny 전에 적용)
    • allow: 허용된 도구 이름 배열
    • deny: 거부된 도구 이름 배열(거부가 우선)
• agents.defaults: 공유 에이전트 기본값(모델, 작업 공간, 샌드박스 등).
• bindings[]: 인바운드 메시지를 agentId로 라우팅합니다.
  • match.channel(필수)
  • match.accountId(선택 사항; * = 모든 계정; 생략 = 기본 계정)
  • match.peer(선택 사항; { kind: dm|group|channel, id })
  • match.guildId / match.teamId(선택 사항; 채널별)

결정론적 일치 순서:

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId(정확, peer/guild/team 없음)
5. match.accountId: "*"(채널 전체, peer/guild/team 없음)
6. 기본 에이전트(agents.list[].default, 그렇지 않으면 첫 번째 목록 항목, 그렇지 않으면 "main")

각 일치 계층 내에서 bindings의 첫 번째 일치 항목이 우선합니다.

에이전트별 액세스 프로필 (다중 에이전트)

각 에이전트는 자체 샌드박스 + 도구 정책을 가질 수 있습니다. 이를 사용하여 하나의 Gateway에서 액세스 수준을 혼합합니다:

• 전체 액세스(개인 에이전트)
• 읽기 전용 도구 + 작업 공간
• 파일 시스템 액세스 없음(메시징/세션 도구만)

우선 순위 및 추가 예제는 다중 에이전트 샌드박스 및 도구를 참조하세요.

전체 액세스(샌드박스 없음):

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" }
      }
    ]
  }
}

읽기 전용 도구 + 읽기 전용 작업 공간:

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",
          scope: "agent",
          workspaceAccess: "ro"
        },
        tools: {
          allow: ["read", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"]
        }
      }
    ]
  }
}

파일 시스템 액세스 없음(메시징/세션 도구 활성화):

{
  agents: {
    list: [
      {
        id: "public",
        workspace: "~/.openclaw/workspace-public",
        sandbox: {
          mode: "all",
          scope: "agent",
          workspaceAccess: "none"
        },
        tools: {
          allow: ["sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status", "whatsapp", "telegram", "slack", "discord", "gateway"],
          deny: ["read", "write", "edit", "apply_patch", "exec", "process", "browser", "canvas", "nodes", "cron", "gateway", "image"]
        }
      }
    ]
  }
}

예제: 두 개의 WhatsApp 계정 → 두 개의 에이전트:

{
  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" } }
  ],
  channels: {
    whatsapp: {
      accounts: {
        personal: {},
        biz: {},
      }
    }
  }
}

tools.agentToAgent (선택 사항)

에이전트 간 메시징은 옵트인입니다:

{
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"]
    }
  }
}

messages.queue

에이전트 실행이 이미 활성화된 경우 인바운드 메시지가 어떻게 작동하는지 제어합니다.

{
  messages: {
    queue: {
      mode: "collect", // steer | followup | collect | steer-backlog (steer+backlog ok) | interrupt (queue=steer legacy)
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
        discord: "collect",
        imessage: "collect",
        webchat: "collect"
      }
    }
  }
}

messages.inbound

동일한 발신자의 빠른 인바운드 메시지를 디바운스하여 여러 개의 연속 메시지가 단일 에이전트 턴이 되도록 합니다. 디바운싱은 채널 + 대화별로 범위가 지정되며 답장 스레딩/ID에 가장 최근 메시지를 사용합니다.

{
  messages: {
    inbound: {
      debounceMs: 2000, // 0은 비활성화
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
        discord: 1500
      }
    }
  }
}

참고:

• 디바운스는 텍스트 전용 메시지를 일괄 처리합니다; 미디어/첨부 파일은 즉시 플러시됩니다.
• 제어 명령(예: /queue, /new)은 디바운싱을 우회하여 독립적으로 유지됩니다.

commands (채팅 명령 처리)

커넥터 전체에서 채팅 명령이 활성화되는 방법을 제어합니다.

{
  commands: {
    native: "auto",         // 지원되는 경우 네이티브 명령 등록(auto)
    text: true,             // 채팅 메시지에서 슬래시 명령 파싱
    bash: false,            // ! (별칭: /bash) 허용(호스트 전용; tools.elevated 허용 목록 필요)
    bashForegroundMs: 2000, // bash 포그라운드 윈도우(0은 즉시 백그라운드)
    config: false,          // /config 허용(디스크에 작성)
    debug: false,           // /debug 허용(런타임 전용 재정의)
    restart: false,         // /restart + gateway restart 도구 허용
    useAccessGroups: true   // 명령에 대한 액세스 그룹 허용 목록/정책 적용
  }
}

참고:

• 텍스트 명령은 독립적인 메시지로 전송되어야 하며 선행 /를 사용해야 합니다(일반 텍스트 별칭 없음).
• commands.text: false는 명령에 대한 채팅 메시지 파싱을 비활성화합니다.
• commands.native: "auto"(기본값)는 Discord/Telegram에 대해 네이티브 명령을 켜고 Slack은 끕니다; 지원되지 않는 채널은 텍스트 전용으로 유지됩니다.
• commands.native: true|false를 설정하여 모두 강제하거나 채널별로 channels.discord.commands.native, channels.telegram.commands.native, channels.slack.commands.native로 재정의합니다(bool 또는 "auto"). false는 시작 시 Discord/Telegram에서 이전에 등록된 명령을 지웁니다; Slack 명령은 Slack 앱에서 관리됩니다.
• channels.telegram.customCommands는 추가 Telegram 봇 메뉴 항목을 추가합니다. 이름은 정규화됩니다; 네이티브 명령과 충돌하면 무시됩니다.
• commands.bash: true는 ! <cmd>를 활성화하여 호스트 셸 명령을 실행합니다(/bash <cmd>도 별칭으로 작동). tools.elevated.enabled 및 tools.elevated.allowFrom.<channel>에서 발신자를 허용 목록에 추가해야 합니다.
• commands.bashForegroundMs는 백그라운드로 전환하기 전에 bash가 대기하는 시간을 제어합니다. bash 작업이 실행되는 동안 새 ! <cmd> 요청은 거부됩니다(한 번에 하나씩).
• commands.config: true는 /config를 활성화합니다(openclaw.json 읽기/쓰기).
• channels.<provider>.configWrites는 해당 채널에서 시작된 구성 변경을 게이트합니다(기본값: true). 이는 /config set|unset 및 공급자별 자동 마이그레이션(Telegram 슈퍼그룹 ID 변경, Slack 채널 ID 변경)에 적용됩니다.
• commands.debug: true는 /debug를 활성화합니다(런타임 전용 재정의).
• commands.restart: true는 /restart 및 게이트웨이 도구 재시작 작업을 활성화합니다.
• commands.useAccessGroups: false는 명령이 액세스 그룹 허용 목록/정책을 우회하도록 허용합니다.
• 슬래시 명령 및 지시문은 승인된 발신자에 대해서만 존중됩니다. 승인은 채널 허용 목록/페어링과 commands.useAccessGroups에서 파생됩니다.

web (WhatsApp 웹 채널 런타임)

WhatsApp은 게이트웨이의 웹 채널(Baileys Web)을 통해 실행됩니다. 링크된 세션이 있으면 자동으로 시작됩니다. 기본적으로 끄려면 web.enabled: false로 설정하세요.

{
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0
    }
  }
}

channels.telegram (봇 전송)

OpenClaw는 channels.telegram 구성 섹션이 있을 때만 Telegram을 시작합니다. 봇 토큰은 channels.telegram.botToken(또는 channels.telegram.tokenFile)에서 해석되며, 기본 계정의 경우 TELEGRAM_BOT_TOKEN이 대체됩니다. 자동 시작을 비활성화하려면 channels.telegram.enabled: false로 설정하세요. 다중 계정 지원은 channels.telegram.accounts 아래에 있습니다(위의 다중 계정 섹션 참조). 환경 토큰은 기본 계정에만 적용됩니다. Telegram에서 시작된 구성 쓰기(슈퍼그룹 ID 마이그레이션 및 /config set|unset 포함)를 차단하려면 channels.telegram.configWrites: false로 설정하세요.

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",                 // pairing | allowlist | open | disabled
      allowFrom: ["tg:123456789"],         // 선택 사항; "open"은 ["*"] 필요
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic."
            }
          }
        }
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" }
      ],
      historyLimit: 50,                     // 컨텍스트로 마지막 N개의 그룹 메시지 포함(0은 비활성화)
      replyToMode: "first",                 // off | first | all
      linkPreview: true,                   // 아웃바운드 링크 미리보기 토글
      streamMode: "partial",               // off | partial | block (드래프트 스트리밍; 블록 스트리밍과 별개)
      draftChunk: {                        // 선택 사항; streamMode=block에만 해당
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph"       // paragraph | newline | sentence
      },
      actions: { reactions: true, sendMessage: true }, // 도구 작업 게이트(false는 비활성화)
      reactionNotifications: "own",   // off | own | all
      mediaMaxMb: 5,
      retry: {                             // 아웃바운드 재시도 정책
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1
      },
      network: {                           // 전송 재정의
        autoSelectFamily: false
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook"
    }
  }
}

드래프트 스트리밍 참고 사항:

• Telegram sendMessageDraft를 사용합니다(드래프트 버블, 실제 메시지 아님).
• 비공개 채팅 토픽 필요(DM의 message_thread_id; 봇에 토픽 활성화).
• /reasoning stream은 드래프트로 추론을 스트리밍한 다음 최종 답변을 보냅니다. 재시도 정책 기본값 및 동작은 재시도 정책에 문서화되어 있습니다.

channels.discord (봇 전송)

봇 토큰 및 선택적 게이팅을 설정하여 Discord 봇을 구성합니다: 다중 계정 지원은 channels.discord.accounts 아래에 있습니다(위의 다중 계정 섹션 참조). 환경 토큰은 기본 계정에만 적용됩니다.

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 8,                          // 인바운드 미디어 크기 제한
      allowBots: false,                       // 봇 작성 메시지 허용
      actions: {                              // 도구 작업 게이트(false는 비활성화)
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false
      },
      replyToMode: "off",                     // off | first | all
      dm: {
        enabled: true,                        // false일 때 모든 DM 비활성화
        policy: "pairing",                    // pairing | allowlist | open | disabled
        allowFrom: ["1234567890", "steipete"], // 선택적 DM 허용 목록("open"은 ["*"] 필요)
        groupEnabled: false,                 // 그룹 DM 활성화
        groupChannels: ["openclaw-dm"]          // 선택적 그룹 DM 허용 목록
      },
      guilds: {
        "123456789012345678": {               // 길드 ID(권장) 또는 슬러그
          slug: "friends-of-openclaw",
          requireMention: false,              // 길드별 기본값
          reactionNotifications: "own",       // off | own | all | allowlist
          users: ["987654321098765432"],      // 선택적 길드별 사용자 허용 목록
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only."
            }
          }
        }
      },
      historyLimit: 20,                       // 컨텍스트로 마지막 N개의 길드 메시지 포함
      textChunkLimit: 2000,                   // 선택적 아웃바운드 텍스트 청크 크기(문자)
      chunkMode: "length",                    // 선택적 청킹 모드(length | newline)
      maxLinesPerMessage: 17,                 // 메시지당 소프트 최대 줄 수(Discord UI 클리핑)
      retry: {                                // 아웃바운드 재시도 정책
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1
      }
    }
  }
}

OpenClaw는 channels.discord 구성 섹션이 있을 때만 Discord를 시작합니다. 토큰은 channels.discord.token에서 해석되며, 기본 계정의 경우 DISCORD_BOT_TOKEN이 대체됩니다(channels.discord.enabled가 false가 아닌 한). cron/CLI 명령의 전달 대상을 지정할 때 user:<id>(DM) 또는 channel:<id>(길드 채널)를 사용하세요; 단순 숫자 ID는 모호하며 거부됩니다. 길드 슬러그는 소문자이며 공백이 -로 대체됩니다; 채널 키는 슬러그된 채널 이름을 사용합니다(선행 # 없음). 이름 변경 모호성을 피하려면 길드 ID를 키로 사용하는 것이 좋습니다. 봇 작성 메시지는 기본적으로 무시됩니다. channels.discord.allowBots로 활성화하세요(자체 메시지는 여전히 필터링되어 자체 응답 루프를 방지합니다). 반응 알림 모드:

• off: 반응 이벤트 없음.
• own: 봇 자체 메시지에 대한 반응(기본값).
• all: 모든 메시지의 모든 반응.
• allowlist: 모든 메시지의 guilds.<id>.users의 반응(빈 목록은 비활성화). 아웃바운드 텍스트는 channels.discord.textChunkLimit(기본값 2000)로 청크됩니다. 길이 청킹 전에 빈 줄(단락 경계)에서 분할하려면 channels.discord.chunkMode="newline"로 설정하세요. Discord 클라이언트는 매우 높은 메시지를 클리핑할 수 있으므로 channels.discord.maxLinesPerMessage(기본값 17)는 2000자 미만이더라도 긴 여러 줄 응답을 분할합니다. 재시도 정책 기본값 및 동작은 재시도 정책에 문서화되어 있습니다.

channels.googlechat (Chat API 웹훅)

Google Chat은 앱 수준 인증(서비스 계정)과 함께 HTTP 웹훅을 통해 실행됩니다. 다중 계정 지원은 channels.googlechat.accounts 아래에 있습니다(위의 다중 계정 섹션 참조). 환경 변수는 기본 계정에만 적용됩니다.

{
  channels: {
    "googlechat": {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url",             // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",        // 선택 사항; 멘션 감지 개선
      dm: {
        enabled: true,
        policy: "pairing",                // pairing | allowlist | open | disabled
        allowFrom: ["users/1234567890"]   // 선택 사항; "open"은 ["*"] 필요
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true }
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20
    }
  }
}

참고:

• 서비스 계정 JSON은 인라인(serviceAccount) 또는 파일 기반(serviceAccountFile)일 수 있습니다.
• 기본 계정의 환경 대체: GOOGLE_CHAT_SERVICE_ACCOUNT 또는 GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• audienceType + audience는 Chat 앱의 웹훅 인증 구성과 일치해야 합니다.
• 전달 대상을 설정할 때 spaces/<spaceId> 또는 users/<userId|email>을 사용하세요.

channels.slack (socket mode)

Slack은 Socket Mode로 실행되며 bot token과 app token이 모두 필요합니다:

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dm: {
        enabled: true,
        policy: "pairing", // pairing | allowlist | open | disabled
        allowFrom: ["U123", "U456", "*"], // optional; "open" requires ["*"]
        groupEnabled: false,
        groupChannels: ["G123"]
      },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only."
        }
      },
      historyLimit: 50,          // include last N channel/group messages as context (0 disables)
      allowBots: false,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["U123"],
      replyToMode: "off",           // off | first | all
      thread: {
        historyScope: "thread",     // thread | channel
        inheritParent: false
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true
      },
      textChunkLimit: 4000,
      chunkMode: "length",
      mediaMaxMb: 20
    }
  }
}

다중 계정 지원은 channels.slack.accounts 아래에 있습니다 (위의 다중 계정 섹션 참조). 환경변수 token은 기본 계정에만 적용됩니다.

OpenClaw는 provider가 활성화되고 두 token이 설정되면 (config 또는 SLACK_BOT_TOKEN + SLACK_APP_TOKEN을 통해) Slack을 시작합니다. cron/CLI 명령의 전송 대상을 지정할 때는 user:<id> (DM) 또는 channel:<id>를 사용하세요. Slack에서 시작된 config 쓰기를 차단하려면 (channel ID 마이그레이션 및 /config set|unset 포함) channels.slack.configWrites: false로 설정하세요.

Bot이 작성한 메시지는 기본적으로 무시됩니다. channels.slack.allowBots 또는 channels.slack.channels.<id>.allowBots로 활성화하세요.

반응 알림 모드:

• off: 반응 이벤트 없음.
• own: bot 자신의 메시지에 대한 반응만 (기본값).
• all: 모든 메시지의 모든 반응.
• allowlist: 모든 메시지에서 channels.slack.reactionAllowlist의 반응만 (빈 목록은 비활성화).

Thread 세션 격리:

• channels.slack.thread.historyScope는 thread 히스토리가 thread별로 분리되는지 (thread, 기본값) 또는 채널 전체에서 공유되는지 (channel) 제어합니다.
• channels.slack.thread.inheritParent는 새 thread 세션이 부모 채널 transcript를 상속받는지 제어합니다 (기본값: false).

Slack action 그룹 (slack tool action 제어):

channels.mattermost (bot token)

Mattermost는 plugin으로 제공되며 core 설치에 번들로 포함되지 않습니다. 먼저 설치하세요: openclaw plugins install @openclaw/mattermost (또는 git checkout에서 ./extensions/mattermost).

Mattermost는 bot token과 서버의 base URL이 필요합니다:

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      textChunkLimit: 4000,
      chunkMode: "length"
    }
  }
}

OpenClaw는 계정이 구성되고 (bot token + base URL) 활성화되면 Mattermost를 시작합니다. token + base URL은 channels.mattermost.botToken + channels.mattermost.baseUrl 또는 기본 계정의 MATTERMOST_BOT_TOKEN + MATTERMOST_URL에서 확인됩니다 (channels.mattermost.enabled가 false가 아닌 경우).

채팅 모드:

• oncall (기본값): @멘션된 경우에만 채널 메시지에 응답합니다.
• onmessage: 모든 채널 메시지에 응답합니다.
• onchar: 메시지가 트리거 접두사로 시작할 때 응답합니다 (channels.mattermost.oncharPrefixes, 기본값 [">", "!"]).

접근 제어:

• 기본 DM: channels.mattermost.dmPolicy="pairing" (알 수 없는 발신자는 pairing code를 받습니다).
• 공개 DM: channels.mattermost.dmPolicy="open" + channels.mattermost.allowFrom=["*"].
• 그룹: 기본적으로 channels.mattermost.groupPolicy="allowlist" (멘션 게이트). 발신자를 제한하려면 channels.mattermost.groupAllowFrom을 사용하세요.

다중 계정 지원은 channels.mattermost.accounts 아래에 있습니다 (위의 다중 계정 섹션 참조). 환경변수는 기본 계정에만 적용됩니다. 전송 대상을 지정할 때 channel:<id> 또는 user:<id> (또는 @username)를 사용하세요; 단순 id는 channel id로 처리됩니다.

channels.signal (signal-cli)

Signal 반응은 시스템 이벤트를 발생시킬 수 있습니다 (공유 반응 도구):

{
  channels: {
    signal: {
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50 // include last N group messages as context (0 disables)
    }
  }
}

반응 알림 모드:

• off: 반응 이벤트 없음.
• own: bot 자신의 메시지에 대한 반응만 (기본값).
• all: 모든 메시지의 모든 반응.
• allowlist: 모든 메시지에서 channels.signal.reactionAllowlist의 반응만 (빈 목록은 비활성화).

channels.imessage (imsg CLI)

OpenClaw는 imsg rpc (stdio를 통한 JSON-RPC)를 실행합니다. 데몬이나 포트가 필요하지 않습니다.

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host", // SCP for remote attachments when using SSH wrapper
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "[email protected]", "chat_id:123"],
      historyLimit: 50,    // include last N group messages as context (0 disables)
      includeAttachments: false,
      mediaMaxMb: 16,
      service: "auto",
      region: "US"
    }
  }
}

다중 계정 지원은 channels.imessage.accounts 아래에 있습니다 (위의 다중 계정 섹션 참조).

참고 사항:

• Messages DB에 대한 Full Disk Access 권한이 필요합니다.
• 첫 전송 시 Messages 자동화 권한을 요청합니다.
• chat_id:<id> 대상을 선호하세요. 채팅 목록을 보려면 imsg chats --limit 20을 사용하세요.
• channels.imessage.cliPath는 wrapper 스크립트를 가리킬 수 있습니다 (예: imsg rpc를 실행하는 다른 Mac으로 ssh); 비밀번호 프롬프트를 피하려면 SSH 키를 사용하세요.
• 원격 SSH wrapper의 경우, includeAttachments가 활성화되었을 때 SCP를 통해 첨부 파일을 가져오도록 channels.imessage.remoteHost를 설정하세요.

Wrapper 예시:

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

agents.defaults.workspace

agent가 파일 작업에 사용하는 단일 전역 workspace 디렉토리를 설정합니다.

기본값: ~/.openclaw/workspace.

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } }
}

agents.defaults.sandbox가 활성화된 경우, non-main 세션은 agents.defaults.sandbox.workspaceRoot 아래의 자체 scope별 workspace로 이를 재정의할 수 있습니다.

agents.defaults.repoRoot

시스템 프롬프트의 Runtime 줄에 표시할 선택적 repository root입니다. 설정하지 않으면 OpenClaw는 workspace (및 현재 작업 디렉토리)에서 위쪽으로 .git 디렉토리를 찾습니다. 경로는 사용되려면 존재해야 합니다.

{
  agents: { defaults: { repoRoot: "~/Projects/openclaw" } }
}

agents.defaults.skipBootstrap

workspace bootstrap 파일 (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, BOOTSTRAP.md)의 자동 생성을 비활성화합니다.

workspace 파일이 repository에서 제공되는 pre-seeded 배포에 이를 사용하세요.

{
  agents: { defaults: { skipBootstrap: true } }
}

agents.defaults.bootstrapMaxChars

잘림 전에 시스템 프롬프트에 주입되는 각 workspace bootstrap 파일의 최대 문자 수입니다. 기본값: 20000.

파일이 이 제한을 초과하면 OpenClaw는 경고를 기록하고 마커가 있는 잘린 head/tail을 주입합니다.

{
  agents: { defaults: { bootstrapMaxChars: 20000 } }
}

agents.defaults.userTimezone

시스템 프롬프트 컨텍스트를 위한 사용자의 timezone을 설정합니다 (메시지 envelope의 타임스탬프용이 아님). 설정하지 않으면 OpenClaw는 런타임에 호스트 timezone을 사용합니다.

{
  agents: { defaults: { userTimezone: "America/Chicago" } }
}

agents.defaults.timeFormat

시스템 프롬프트의 Current Date & Time 섹션에 표시되는 시간 형식을 제어합니다. 기본값: auto (OS 기본 설정).

{
  agents: { defaults: { timeFormat: "auto" } } // auto | 12 | 24
}

messages

인바운드/아웃바운드 접두사 및 선택적 ack 반응을 제어합니다. 대기열, 세션 및 스트리밍 컨텍스트는 Messages를 참조하세요.

{
  messages: {
    responsePrefix: "🦞", // or "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions",
    removeAckAfterReply: false
  }
}

responsePrefix는 이미 있지 않은 경우 채널 전반에 걸쳐 모든 아웃바운드 응답 (tool 요약, 블록 스트리밍, 최종 응답)에 적용됩니다.

messages.responsePrefix가 설정되지 않으면 기본적으로 접두사가 적용되지 않습니다. WhatsApp self-chat 응답은 예외입니다: 설정된 경우 [{identity.name}]이 기본값이며, 그렇지 않으면 [openclaw]이므로 동일 전화 대화가 읽기 쉽게 유지됩니다. 라우팅된 agent의 [{identity.name}]를 파생하려면 "auto"로 설정하세요 (설정된 경우).

Template 변수

responsePrefix 문자열은 동적으로 해결되는 template 변수를 포함할 수 있습니다:

변수는 대소문자를 구분하지 않습니다 ({MODEL} = {model}). {think}는 {thinkingLevel}의 별칭입니다. 해결되지 않은 변수는 리터럴 텍스트로 남습니다.

{
  messages: {
    responsePrefix: "[{model} | think:{thinkingLevel}]"
  }
}

예시 출력: [claude-opus-4-5 | think:high] Here's my response...

WhatsApp 인바운드 접두사는 channels.whatsapp.messagePrefix를 통해 구성됩니다 (deprecated: messages.messagePrefix). 기본값은 변경되지 않음: channels.whatsapp.allowFrom이 비어 있으면 "[openclaw]", 그렇지 않으면 "" (접두사 없음). "[openclaw]"를 사용할 때 라우팅된 agent에 identity.name이 설정되어 있으면 OpenClaw는 대신 [{identity.name}]를 사용합니다.

ackReaction은 반응을 지원하는 채널 (Slack/Discord/Telegram/Google Chat)에서 인바운드 메시지를 확인하기 위해 best-effort 이모지 반응을 보냅니다. 설정된 경우 활성 agent의 identity.emoji가 기본값이며, 그렇지 않으면 "👀"입니다. 비활성화하려면 ""로 설정하세요.

ackReactionScope는 반응이 발생하는 시기를 제어합니다:

• group-mentions (기본값): 그룹/room이 멘션을 요구하고 그리고 bot이 멘션된 경우에만
• group-all: 모든 그룹/room 메시지
• direct: 직접 메시지만
• all: 모든 메시지

removeAckAfterReply는 응답이 전송된 후 bot의 ack 반응을 제거합니다 (Slack/Discord/Telegram/Google Chat만 해당). 기본값: false.

messages.tts

아웃바운드 응답에 대한 text-to-speech를 활성화합니다. 활성화되면 OpenClaw는 ElevenLabs 또는 OpenAI를 사용하여 오디오를 생성하고 응답에 첨부합니다. Telegram은 Opus voice note를 사용하고 다른 채널은 MP3 오디오를 전송합니다.

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all (include tool/block replies)
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true
      },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      elevenlabs: {
        apiKey: "elevenlabs_api_key",
        baseUrl: "https://api.elevenlabs.io",
        voiceId: "voice_id",
        modelId: "eleven_multilingual_v2",
        seed: 42,
        applyTextNormalization: "auto",
        languageCode: "en",
        voiceSettings: {
          stability: 0.5,
          similarityBoost: 0.75,
          style: 0.0,
          useSpeakerBoost: true,
          speed: 1.0
        }
      },
      openai: {
        apiKey: "openai_api_key",
        model: "gpt-4o-mini-tts",
        voice: "alloy"
      }
    }
  }
}

참고 사항:

• messages.tts.auto는 auto‑TTS를 제어합니다 (off, always, inbound, tagged).
• /tts off|always|inbound|tagged는 세션별 auto 모드를 설정합니다 (config를 재정의).
• messages.tts.enabled는 레거시이며; doctor가 이를 messages.tts.auto로 마이그레이션합니다.
• prefsPath는 로컬 재정의 (provider/limit/summarize)를 저장합니다.
• maxTextLength는 TTS 입력의 hard cap입니다; 요약은 맞추기 위해 잘립니다.
• summaryModel은 auto-summary를 위해 agents.defaults.model.primary를 재정의합니다.
  • provider/model 또는 agents.defaults.models의 별칭을 허용합니다.
• modelOverrides는 [[tts:...]] 태그와 같은 모델 기반 재정의를 활성화합니다 (기본적으로 활성화).
• /tts limit과 /tts summary는 사용자별 요약 설정을 제어합니다.
• apiKey 값은 ELEVENLABS_API_KEY/XI_API_KEY 및 OPENAI_API_KEY로 폴백됩니다.
• elevenlabs.baseUrl은 ElevenLabs API base URL을 재정의합니다.
• elevenlabs.voiceSettings는 stability/similarityBoost/style (0..1), useSpeakerBoost, speed (0.5..2.0)를 지원합니다.

talk

Talk 모드의 기본값 (macOS/iOS/Android). Voice ID는 설정되지 않으면 ELEVENLABS_VOICE_ID 또는 SAG_VOICE_ID로 폴백됩니다. apiKey는 설정되지 않으면 ELEVENLABS_API_KEY (또는 gateway의 shell profile)로 폴백됩니다. voiceAliases는 Talk 지시문이 친근한 이름을 사용할 수 있도록 합니다 (예: "voice":"Clawd").

{
  talk: {
    voiceId: "elevenlabs_voice_id",
    voiceAliases: {
      Clawd: "EXAVITQu4vr4xnSDxMaL",
      Roger: "CwhRBWXzGAHq8TQ4Fs17"
    },
    modelId: "eleven_v3",
    outputFormat: "mp3_44100_128",
    apiKey: "elevenlabs_api_key",
    interruptOnSpeech: true
  }
}

agents.defaults

내장 agent 런타임 (model/thinking/verbose/timeout)을 제어합니다. agents.defaults.models는 구성된 모델 카탈로그를 정의합니다 (그리고 /model의 allowlist 역할을 함). agents.defaults.model.primary는 기본 모델을 설정합니다; agents.defaults.model.fallbacks는 전역 failover입니다. agents.defaults.imageModel은 선택 사항이며 primary 모델에 image 입력이 없는 경우에만 사용됩니다. 각 agents.defaults.models 항목은 다음을 포함할 수 있습니다:

• alias (선택적 모델 단축키, 예: /opus).
• params (모델 요청에 전달되는 선택적 provider별 API 매개변수).

params는 스트리밍 실행 (내장 agent + 압축)에도 적용됩니다. 현재 지원되는 키: temperature, maxTokens. 이들은 호출 시점 옵션과 병합되며; 호출자가 제공한 값이 우선합니다. temperature는 고급 노브입니다—모델의 기본값을 알고 변경이 필요한 경우가 아니면 설정하지 마세요.

예시:

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-sonnet-4-5-20250929": {
          params: { temperature: 0.6 }
        },
        "openai/gpt-5.2": {
          params: { maxTokens: 8192 }
        }
      }
    }
  }
}

Z.AI GLM-4.x 모델은 다음 경우가 아니면 자동으로 thinking 모드를 활성화합니다:

• --thinking off를 설정하거나
• 직접 agents.defaults.models["zai/<model>"].params.thinking을 정의하는 경우.

OpenClaw는 또한 몇 가지 내장 별칭 단축어를 제공합니다. 기본값은 모델이 이미 agents.defaults.models에 있는 경우에만 적용됩니다:

• opus -> anthropic/claude-opus-4-5
• sonnet -> anthropic/claude-sonnet-4-5
• gpt -> openai/gpt-5.2
• gpt-mini -> openai/gpt-5-mini
• gemini -> google/gemini-3-pro-preview
• gemini-flash -> google/gemini-3-flash-preview

동일한 별칭 이름을 (대소문자 구분 없이) 직접 구성하면 귀하의 값이 우선합니다 (기본값은 재정의하지 않음).

예시: Opus 4.5 primary와 MiniMax M2.1 fallback (호스팅된 MiniMax):

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-5": { alias: "opus" },
        "minimax/MiniMax-M2.1": { alias: "minimax" }
      },
      model: {
        primary: "anthropic/claude-opus-4-5",
        fallbacks: ["minimax/MiniMax-M2.1"]
      }
    }
  }
}

MiniMax 인증: MINIMAX_API_KEY (env)를 설정하거나 models.providers.minimax를 구성하세요.

agents.defaults.cliBackends (CLI fallback)

텍스트 전용 fallback 실행 (tool 호출 없음)을 위한 선택적 CLI backend입니다. API provider가 실패할 때 백업 경로로 유용합니다. 파일 경로를 허용하는 imageArg를 구성하면 image pass-through가 지원됩니다.

참고 사항:

• CLI backend는 텍스트 우선이며; tool은 항상 비활성화됩니다.
• sessionArg가 설정되면 세션이 지원됩니다; 세션 id는 backend별로 유지됩니다.
• claude-cli의 경우 기본값이 내장되어 있습니다. PATH가 최소한 (launchd/systemd)인 경우 command 경로를 재정의하세요.

예시:

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude"
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          modelArg: "--model",
          sessionArg: "--session",
          sessionMode: "existing",
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat"
        }
      }
    }
  }
}

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-5": { alias: "Opus" },
        "anthropic/claude-sonnet-4-1": { alias: "Sonnet" },
        "openrouter/deepseek/deepseek-r1:free": {},
        "zai/glm-4.7": {
          alias: "GLM",
          params: {
            thinking: {
              type: "enabled",
              clear_thinking: false
            }
          }
        }
      },
      model: {
        primary: "anthropic/claude-opus-4-5",
        fallbacks: [
          "openrouter/deepseek/deepseek-r1:free",
          "openrouter/meta-llama/llama-3.3-70b-instruct:free"
        ]
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: [
          "openrouter/google/gemini-2.0-flash-vision:free"
        ]
      },
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      heartbeat: {
        every: "30m",
        target: "last"
      },
      maxConcurrent: 3,
      subagents: {
        model: "minimax/MiniMax-M2.1",
        maxConcurrent: 1,
        archiveAfterMinutes: 60
      },
      exec: {
        backgroundMs: 10000,
        timeoutSec: 1800,
        cleanupMs: 1800000
      },
      contextTokens: 200000
    }
  }
}

agents.defaults.contextPruning (tool-result 정리)

agents.defaults.contextPruning은 요청이 LLM에 전송되기 직전에 메모리 내 컨텍스트에서 오래된 tool 결과를 정리합니다. 디스크의 세션 히스토리는 수정하지 않습니다 (*.jsonl은 완전히 유지됨).

이는 시간이 지남에 따라 큰 tool 출력을 축적하는 수다스러운 agent의 token 사용량을 줄이기 위한 것입니다.

상위 레벨:

• user/assistant 메시지는 건드리지 않습니다.
• 마지막 keepLastAssistants assistant 메시지를 보호합니다 (그 시점 이후의 tool 결과는 정리되지 않음).
• bootstrap 접두사를 보호합니다 (첫 번째 user 메시지 이전의 것은 정리되지 않음).
• 모드:
  • adaptive: 예상 컨텍스트 비율이 softTrimRatio를 넘으면 초과 크기 tool 결과를 soft-trim합니다 (head/tail 유지). 그런 다음 예상 컨텍스트 비율이 hardClearRatio를 넘고 그리고 정리 가능한 tool-result 볼륨이 충분할 때 (minPrunableToolChars) 가장 오래된 적격 tool 결과를 hard-clear합니다.
  • aggressive: 컷오프 이전의 적격 tool 결과를 항상 hardClear.placeholder로 대체합니다 (비율 검사 없음).

Soft vs hard 정리 (LLM에 전송되는 컨텍스트에서 변경되는 내용):

• Soft-trim: 초과 크기 tool 결과만 해당. 시작 + 끝을 유지하고 중간에 ...을 삽입합니다.
  • 이전: toolResult("…매우 긴 출력…")
  • 이후: toolResult("HEAD…\n...\n…TAIL\n\n[Tool result trimmed: …]")
• Hard-clear: 전체 tool 결과를 placeholder로 대체합니다.
  • 이전: toolResult("…매우 긴 출력…")
  • 이후: toolResult("[Old tool result content cleared]")

참고 사항 / 현재 제한 사항:

• image 블록을 포함하는 tool 결과는 현재 건너뜁니다 (trim/clear되지 않음).
• 예상 "컨텍스트 비율"은 문자 (근사치)를 기반으로 하며, 정확한 token이 아닙니다.
• 세션이 아직 최소 keepLastAssistants assistant 메시지를 포함하지 않으면 정리가 건너뜁니다.
• aggressive 모드에서는 hardClear.enabled가 무시됩니다 (적격 tool 결과는 항상 hardClear.placeholder로 대체됨).

기본값 (adaptive):

{
  agents: { defaults: { contextPruning: { mode: "adaptive" } } }
}

비활성화하려면:

{
  agents: { defaults: { contextPruning: { mode: "off" } } }
}

기본값 (mode가 "adaptive" 또는 "aggressive"인 경우):

• keepLastAssistants: 3
• softTrimRatio: 0.3 (adaptive만 해당)
• hardClearRatio: 0.5 (adaptive만 해당)
• minPrunableToolChars: 50000 (adaptive만 해당)
• softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 } (adaptive만 해당)
• hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }

예시 (aggressive, 최소):

{
  agents: { defaults: { contextPruning: { mode: "aggressive" } } }
}

예시 (adaptive 조정):

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "adaptive",
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" },
        // 선택 사항: 특정 tool로 정리 제한 (deny가 우선; "*" 와일드카드 지원)
        tools: { deny: ["browser", "canvas"] },
      }
    }
  }
}

동작 세부 사항은 /concepts/session-pruning을 참조하세요.

agents.defaults.compaction (reserve headroom + memory flush)

agents.defaults.compaction.mode는 compaction 요약 전략을 선택합니다. 기본값은 default이며; 매우 긴 히스토리에 대한 청크 요약을 활성화하려면 safeguard로 설정하세요. /concepts/compaction을 참조하세요.

agents.defaults.compaction.reserveTokensFloor는 Pi compaction에 대한 최소 reserveTokens 값을 강제합니다 (기본값: 20000). floor를 비활성화하려면 0으로 설정하세요.

agents.defaults.compaction.memoryFlush는 auto-compaction 전에 silent agentic turn을 실행하여 모델이 디스크에 영구 메모리를 저장하도록 지시합니다 (예: memory/YYYY-MM-DD.md). 세션 token 추정이 compaction 제한 아래의 soft threshold를 넘으면 트리거됩니다.

레거시 기본값:

• memoryFlush.enabled: true
• memoryFlush.softThresholdTokens: 4000
• memoryFlush.prompt / memoryFlush.systemPrompt: NO_REPLY가 있는 내장 기본값
• 참고: 세션 workspace가 읽기 전용인 경우 memory flush는 건너뜁니다 (agents.defaults.sandbox.workspaceAccess: "ro" 또는 "none").

예시 (조정):

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard",
        reserveTokensFloor: 24000,
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
        }
      }
    }
  }
}

블록 스트리밍:

• agents.defaults.blockStreamingDefault: "on"/"off" (기본값 off).
• Channel 재정의: *.blockStreaming (및 계정별 변형)으로 block streaming을 강제로 on/off합니다. Telegram이 아닌 채널은 block 응답을 활성화하려면 명시적인 *.blockStreaming: true가 필요합니다.
• agents.defaults.blockStreamingBreak: "text_end" 또는 "message_end" (기본값: text_end).
• agents.defaults.blockStreamingChunk: 스트리밍된 블록에 대한 soft 청킹. 기본값은 800–1200 문자이며, 단락 구분 (\n\n)을 선호하고, 그 다음 줄 바꿈, 그 다음 문장을 선호합니다. 예시:

  {
    agents: { defaults: { blockStreamingChunk: { minChars: 800, maxChars: 1200 } } }
  }
  

• agents.defaults.blockStreamingCoalesce: 전송 전에 스트리밍된 블록을 병합합니다. 기본값은 { idleMs: 1000 }이고 blockStreamingChunk에서 minChars를 상속하며 maxChars는 channel 텍스트 제한으로 제한됩니다. Signal/Slack/Discord/Google Chat은 기본적으로 minChars: 1500이며 재정의되지 않는 한 유지됩니다. Channel 재정의: channels.whatsapp.blockStreamingCoalesce, channels.telegram.blockStreamingCoalesce, channels.discord.blockStreamingCoalesce, channels.slack.blockStreamingCoalesce, channels.mattermost.blockStreamingCoalesce, channels.signal.blockStreamingCoalesce, channels.imessage.blockStreamingCoalesce, channels.msteams.blockStreamingCoalesce, channels.googlechat.blockStreamingCoalesce (및 계정별 변형).
• agents.defaults.humanDelay: 첫 번째 이후 블록 응답 사이의 무작위 일시 중지. 모드: off (기본값), natural (800–2500ms), custom (minMs/maxMs 사용). Agent별 재정의: agents.list[].humanDelay. 예시:

  {
    agents: { defaults: { humanDelay: { mode: "natural" } } }
  }
  

동작 + 청킹 세부 사항은 /concepts/streaming을 참조하세요.

타이핑 표시:

• agents.defaults.typingMode: "never" | "instant" | "thinking" | "message". 기본값은 직접 채팅 / 멘션의 경우 instant이고 멘션되지 않은 그룹 채팅의 경우 message입니다.
• session.typingMode: 모드에 대한 세션별 재정의.
• agents.defaults.typingIntervalSeconds: 타이핑 신호가 새로 고쳐지는 빈도 (기본값: 6초).
• session.typingIntervalSeconds: 새로 고침 간격에 대한 세션별 재정의. 동작 세부 사항은 /concepts/typing-indicators를 참조하세요.

agents.defaults.model.primary는 provider/model로 설정해야 합니다 (예: anthropic/claude-opus-4-5). 별칭은 agents.defaults.models.*.alias에서 제공됩니다 (예: Opus). provider를 생략하면 OpenClaw는 현재 임시 deprecation fallback으로 anthropic을 가정합니다. Z.AI 모델은 zai/<model>로 사용할 수 있으며 (예: zai/glm-4.7) 환경에 ZAI_API_KEY (또는 레거시 Z_AI_API_KEY)가 필요합니다.

agents.defaults.heartbeat는 주기적인 heartbeat 실행을 구성합니다:

• every: 기간 문자열 (ms, s, m, h); 기본 단위는 분입니다. 기본값: 30m. 비활성화하려면 0m로 설정하세요.
• model: heartbeat 실행을 위한 선택적 재정의 모델 (provider/model).
• includeReasoning: true이면 heartbeat는 사용 가능한 경우 별도의 Reasoning: 메시지도 전달합니다 (/reasoning on과 동일한 형태). 기본값: false.
• session: heartbeat가 실행되는 세션을 제어하는 선택적 세션 키. 기본값: main.
• to: 선택적 수신자 재정의 (채널별 id, 예: WhatsApp의 E.164, Telegram의 chat id).
• target: 선택적 전송 채널 (last, whatsapp, telegram, discord, slack, msteams, signal, imessage, none). 기본값: last.
• prompt: heartbeat 본문에 대한 선택적 재정의 (기본값: Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.). 재정의는 그대로 전송됩니다; 파일을 여전히 읽으려면 Read HEARTBEAT.md 줄을 포함하세요.
• ackMaxChars: 전송 전에 HEARTBEAT_OK 이후 허용되는 최대 문자 수 (기본값: 300).

Agent별 heartbeat:

• agents.list[].heartbeat를 설정하여 특정 agent에 대한 heartbeat 설정을 활성화하거나 재정의합니다.
• agent 항목이 heartbeat를 정의하면 해당 agent만 heartbeat를 실행합니다; 기본값은 해당 agent에 대한 공유 기준이 됩니다.

Heartbeat는 전체 agent turn을 실행합니다. 짧은 간격은 더 많은 token을 소모합니다; every를 유념하고, HEARTBEAT.md를 작게 유지하고, 그리고/또는 더 저렴한 model을 선택하세요.

tools.exec는 background exec 기본값을 구성합니다:

• backgroundMs: auto-background 전 시간 (ms, 기본값 10000)
• timeoutSec: 이 런타임 후 자동 종료 (초, 기본값 1800)
• cleanupMs: 완료된 세션을 메모리에 유지하는 시간 (ms, 기본값 1800000)
• notifyOnExit: background exec이 종료될 때 시스템 이벤트를 enqueue하고 heartbeat를 요청 (기본값 true)
• applyPatch.enabled: 실험적 apply_patch 활성화 (OpenAI/OpenAI Codex만 해당; 기본값 false)
• applyPatch.allowModels: 모델 id의 선택적 allowlist (예: gpt-5.2 또는 openai/gpt-5.2) 참고: applyPatch는 tools.exec 아래에만 있습니다.

tools.web은 web search + fetch tool을 구성합니다:

• tools.web.search.enabled (기본값: 키가 있으면 true)
• tools.web.search.apiKey (권장: openclaw configure --section web을 통해 설정하거나 BRAVE_API_KEY env var 사용)
• tools.web.search.maxResults (1–10, 기본값 5)
• tools.web.search.timeoutSeconds (기본값 30)
• tools.web.search.cacheTtlMinutes (기본값 15)
• tools.web.fetch.enabled (기본값 true)
• tools.web.fetch.maxChars (기본값 50000)
• tools.web.fetch.timeoutSeconds (기본값 30)
• tools.web.fetch.cacheTtlMinutes (기본값 15)
• tools.web.fetch.userAgent (선택적 재정의)
• tools.web.fetch.readability (기본값 true; 비활성화하여 기본 HTML 정리만 사용)
• tools.web.fetch.firecrawl.enabled (기본값 API 키가 설정되면 true)
• tools.web.fetch.firecrawl.apiKey (선택 사항; 기본값은 FIRECRAWL_API_KEY)
• tools.web.fetch.firecrawl.baseUrl (기본값 https://api.firecrawl.dev)
• tools.web.fetch.firecrawl.onlyMainContent (기본값 true)
• tools.web.fetch.firecrawl.maxAgeMs (선택 사항)
• tools.web.fetch.firecrawl.timeoutSeconds (선택 사항)

tools.media는 인바운드 미디어 이해 (image/audio/video)를 구성합니다:

• tools.media.models: 공유 모델 목록 (capability 태그; capability별 목록 이후 사용).
• tools.media.concurrency: 최대 동시 capability 실행 (기본값 2).
• tools.media.image / tools.media.audio / tools.media.video:
  • enabled: opt-out 스위치 (모델이 구성되면 기본값 true).
  • prompt: 선택적 프롬프트 재정의 (image/video는 자동으로 maxChars 힌트 추가).
  • maxChars: 최대 출력 문자 수 (기본값 image/video는 500; audio는 설정 안 됨).
  • maxBytes: 전송할 최대 미디어 크기 (기본값: image 10MB, audio 20MB, video 50MB).
  • timeoutSeconds: 요청 타임아웃 (기본값: image 60초, audio 60초, video 120초).
  • language: 선택적 audio 힌트.
  • attachments: 첨부 파일 정책 (mode, maxAttachments, prefer).
  • scope: 선택적 gating (첫 번째 일치가 우선) with match.channel, match.chatType, or match.keyPrefix.
  • models: 모델 항목의 순서 목록; 실패 또는 초과 크기 미디어는 다음 항목으로 fallback합니다.
• 각 models[] 항목:
  • Provider 항목 (type: "provider" 또는 생략):
    • provider: API provider id (openai, anthropic, google/gemini, groq 등).
    • model: 모델 id 재정의 (image에 필요; audio provider의 경우 기본값은 gpt-4o-mini-transcribe/whisper-large-v3-turbo, video의 경우 gemini-3-flash-preview).
    • profile / preferredProfile: auth profile 선택.
  • CLI 항목 (type: "cli"):
    • command: 실행할 실행 파일.
    • args: 템플릿 args ({{MediaPath}}, {{Prompt}}, {{MaxChars}} 등 지원).
  • capabilities: 공유 항목을 게이트하는 선택적 목록 (image, audio, video). 생략 시 기본값: openai/anthropic/minimax → image, google → image+audio+video, groq → audio.
  • prompt, maxChars, maxBytes, timeoutSeconds, language는 항목별로 재정의될 수 있습니다.

모델이 구성되지 않았거나 (enabled: false인 경우) 이해를 건너뜁니다; 모델은 여전히 원본 첨부 파일을 받습니다.

Provider auth는 표준 모델 auth 순서를 따릅니다 (auth profile, OPENAI_API_KEY/GROQ_API_KEY/GEMINI_API_KEY와 같은 env var, 또는 models.providers.*.apiKey).

예시:

{
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,
        scope: {
          default: "deny",
          rules: [{ action: "allow", match: { chatType: "direct" } }]
        },
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }
        ]
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }]
      }
    }
  }
}

agents.defaults.subagents는 sub-agent 기본값을 구성합니다:

• model: 생성된 sub-agent의 기본 모델 (문자열 또는 { primary, fallbacks }). 생략하면 sub-agent는 agent별 또는 호출별로 재정의되지 않는 한 호출자의 모델을 상속합니다.
• maxConcurrent: 최대 동시 sub-agent 실행 (기본값 1)
• archiveAfterMinutes: N분 후 sub-agent 세션 자동 아카이브 (기본값 60; 비활성화하려면 0으로 설정)
• Subagent별 tool 정책: tools.subagents.tools.allow / tools.subagents.tools.deny (deny가 우선)

tools.profile은 tools.allow/tools.deny 전에 기본 tool allowlist를 설정합니다:

• minimal: session_status만
• coding: group:fs, group:runtime, group:sessions, group:memory, image
• messaging: group:messaging, sessions_list, sessions_history, sessions_send, session_status
• full: 제한 없음 (설정 안 한 것과 동일)

Agent별 재정의: agents.list[].tools.profile.

예시 (기본적으로 messaging만, Slack + Discord tool도 허용):

{
  tools: {
    profile: "messaging",
    allow: ["slack", "discord"]
  }
}

예시 (coding profile, 하지만 어디서나 exec/process 거부):

{
  tools: {
    profile: "coding",
    deny: ["group:runtime"]
  }
}

tools.byProvider는 특정 provider (또는 단일 provider/model)에 대한 tool을 추가로 제한할 수 있습니다. Agent별 재정의: agents.list[].tools.byProvider.

순서: 기본 profile → provider profile → allow/deny 정책. Provider 키는 provider (예: google-antigravity) 또는 provider/model (예: openai/gpt-5.2)를 허용합니다.

예시 (전역 coding profile 유지, 하지만 Google Antigravity는 최소 tool):

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" }
    }
  }
}

예시 (provider/model별 allowlist):

{
  tools: {
    allow: ["group:fs", "group:runtime", "sessions_list"],
    byProvider: {
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] }
    }
  }
}

tools.allow / tools.deny는 전역 tool allow/deny 정책을 구성합니다 (deny가 우선). 매칭은 대소문자를 구분하지 않으며 * 와일드카드를 지원합니다 ("*"는 모든 tool을 의미). 이것은 Docker sandbox가 off인 경우에도 적용됩니다.

예시 (어디서나 browser/canvas 비활성화):

{
  tools: { deny: ["browser", "canvas"] }
}

Tool 그룹 (단축어)은 전역 및 agent별 tool 정책에서 작동합니다:

• group:runtime: exec, bash, process
• group:fs: read, write, edit, apply_patch
• group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
• group:memory: memory_search, memory_get
• group:web: web_search, web_fetch
• group:ui: browser, canvas
• group:automation: cron, gateway
• group:messaging: message
• group:nodes: nodes
• group:openclaw: 모든 내장 OpenClaw tool (provider plugin 제외)

tools.elevated는 elevated (host) exec 접근을 제어합니다:

• enabled: elevated 모드 허용 (기본값 true)
• allowFrom: 채널별 allowlist (비어 있음 = 비활성화)
  • whatsapp: E.164 번호
  • telegram: chat id 또는 username
  • discord: user id 또는 username (channels.discord.dm.allowFrom으로 폴백, 생략 시)
  • signal: E.164 번호
  • imessage: handle/chat id
  • webchat: session id 또는 username

예시:

{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        discord: ["steipete", "1234567890123"]
      }
    }
  }
}

Agent별 재정의 (추가 제한):

{
  agents: {
    list: [
      {
        id: "family",
        tools: {
          elevated: { enabled: false }
        }
      }
    ]
  }
}

참고 사항:

• tools.elevated는 전역 기준입니다. agents.list[].tools.elevated는 추가로만 제한할 수 있습니다 (둘 다 허용해야 함).
• /elevated on|off|ask|full은 세션 키별로 상태를 저장합니다; 인라인 지시문은 단일 메시지에 적용됩니다.
• Elevated exec는 호스트에서 실행되고 sandboxing을 우회합니다.
• Tool 정책은 여전히 적용됩니다; exec가 거부되면 elevated를 사용할 수 없습니다.

agents.defaults.maxConcurrent는 세션 전반에 걸쳐 병렬로 실행할 수 있는 최대 내장 agent 실행 수를 설정합니다. 각 세션은 여전히 직렬화됩니다 (세션 키당 한 번에 하나의 실행). 기본값: 1.

agents.defaults.sandbox

내장 agent를 위한 선택적 Docker sandboxing입니다. non-main 세션이 호스트 시스템에 접근할 수 없도록 의도되었습니다.

세부 사항: Sandboxing

기본값 (활성화된 경우):

• scope: "agent" (agent당 하나의 컨테이너 + workspace)
• Debian bookworm-slim 기반 이미지
• agent workspace 접근: workspaceAccess: "none" (기본값)
  • "none": ~/.openclaw/sandboxes 아래의 scope별 sandbox workspace 사용
• "ro": sandbox workspace를 /workspace에 유지하고, agent workspace를 /agent에 읽기 전용으로 마운트 (write/edit/apply_patch 비활성화)
  • "rw": agent workspace를 /workspace에 읽기/쓰기로 마운트
• auto-prune: idle > 24시간 또는 age > 7일
• tool 정책: exec, process, read, write, edit, apply_patch, sessions_list, sessions_history, sessions_send, sessions_spawn, session_status만 허용 (deny가 우선)
  • tools.sandbox.tools를 통해 구성, agent별로 agents.list[].tools.sandbox.tools를 통해 재정의
  • sandbox 정책에서 지원되는 tool 그룹 단축어: group:runtime, group:fs, group:sessions, group:memory (Sandbox vs Tool Policy vs Elevated 참조)
• 선택적 sandboxed browser (Chromium + CDP, noVNC 관찰자)
• 강화 노브: network, user, pidsLimit, memory, cpus, ulimits, seccompProfile, apparmorProfile

경고: scope: "shared"는 공유 컨테이너와 공유 workspace를 의미합니다. 세션 간 격리가 없습니다. 세션별 격리를 위해 scope: "session"을 사용하세요.

레거시: perSession은 여전히 지원됩니다 (true → scope: "session", false → scope: "shared").

setupCommand는 컨테이너가 생성된 후 한 번 실행됩니다 (컨테이너 내부에서 sh -lc를 통해). 패키지 설치의 경우 네트워크 egress, 쓰기 가능한 root FS 및 root 사용자를 확인하세요.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (agent is default)
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          // Agent별 재정의 (multi-agent): agents.list[].sandbox.docker.*
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/var/run/docker.sock:/var/run/docker.sock", "/home/user/source:/source:rw"]
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          containerPrefix: "openclaw-sbx-browser-",
          cdpPort: 9222,
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          allowedControlUrls: ["http://10.0.0.42:18791"],
          allowedControlHosts: ["browser.lab.local", "10.0.0.42"],
          allowedControlPorts: [18791],
          autoStart: true,
          autoStartTimeoutMs: 12000
        },
        prune: {
          idleHours: 24,  // 0 disables idle pruning
          maxAgeDays: 7   // 0 disables max-age pruning
        }
      }
    }
  },
  tools: {
    sandbox: {
      tools: {
        allow: ["exec", "process", "read", "write", "edit", "apply_patch", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"]
      }
    }
  }
}

다음을 사용하여 기본 sandbox 이미지를 한 번 빌드하세요:

scripts/sandbox-setup.sh

참고: sandbox 컨테이너는 기본적으로 network: "none"입니다; agent가 아웃바운드 접근이 필요한 경우 agents.defaults.sandbox.docker.network를 "bridge" (또는 커스텀 네트워크)로 설정하세요.

참고: 인바운드 첨부 파일은 media/inbound/*의 활성 workspace로 스테이징됩니다. workspaceAccess: "rw"를 사용하면 파일이 agent workspace에 작성됩니다.

참고: docker.binds는 추가 호스트 디렉토리를 마운트합니다; 전역 및 agent별 bind가 병합됩니다.

다음을 사용하여 선택적 browser 이미지를 빌드하세요:

scripts/sandbox-browser-setup.sh

agents.defaults.sandbox.browser.enabled=true일 때 browser tool은 sandboxed Chromium 인스턴스 (CDP)를 사용합니다. noVNC가 활성화되면 (headless=false일 때 기본값), noVNC URL이 시스템 프롬프트에 주입되므로 agent가 참조할 수 있습니다. 이것은 main config에서 browser.enabled를 필요로 하지 않습니다; sandbox 제어 URL은 세션별로 주입됩니다.

agents.defaults.sandbox.browser.allowHostControl (기본값: false)은 sandboxed 세션이 browser tool을 통해 호스트 browser 제어 서버를 명시적으로 대상으로 하도록 허용합니다 (target: "host"). 엄격한 sandbox 격리를 원하면 이것을 꺼두세요.

원격 제어를 위한 Allowlist:

• allowedControlUrls: target: "custom"에 허용되는 정확한 제어 URL.
• allowedControlHosts: 허용되는 호스트 이름 (호스트 이름만, 포트 제외).
• allowedControlPorts: 허용되는 포트 (기본값: http=80, https=443). 기본값: 모든 allowlist가 설정되지 않음 (제한 없음). allowHostControl은 기본적으로 false입니다.

models (사용자 정의 provider + base URL)

OpenClaw는 pi-coding-agent 모델 카탈로그를 사용합니다. LiteLLM, 로컬 OpenAI 호환 서버, Anthropic 프록시 등의 사용자 정의 provider를 추가하려면 ~/.openclaw/agents/<agentId>/agent/models.json 파일을 작성하거나 OpenClaw 설정 내에서 models.providers 아래에 동일한 스키마를 정의하면 됩니다. Provider별 개요 및 예제: /concepts/model-providers.

models.providers가 있으면 OpenClaw는 시작 시 ~/.openclaw/agents/<agentId>/agent/에 models.json을 작성/병합합니다:

• 기본 동작: 병합 (기존 provider를 유지하고 이름으로 덮어씁니다)
• models.mode: "replace"로 설정하면 파일 내용을 완전히 덮어씁니다

모델은 agents.defaults.model.primary (provider/model)를 통해 선택합니다.

{
  agents: {
    defaults: {
      model: { primary: "custom-proxy/llama-3.1-8b" },
      models: {
        "custom-proxy/llama-3.1-8b": {}
      }
    }
  },
  models: {
    mode: "merge",
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-completions",
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 32000
          }
        ]
      }
    }
  }
}

OpenCode Zen (멀티 모델 프록시)

OpenCode Zen은 모델별 엔드포인트를 제공하는 멀티 모델 게이트웨이입니다. OpenClaw는 pi-ai의 내장 opencode provider를 사용하며, https://opencode.ai/auth 에서 OPENCODE_API_KEY (또는 OPENCODE_ZEN_API_KEY)를 설정해야 합니다.

참고사항:

• 모델 참조는 opencode/<modelId> 형식을 사용합니다 (예: opencode/claude-opus-4-5).
• agents.defaults.models를 통해 허용 목록을 활성화하면 사용하려는 각 모델을 추가해야 합니다.
• 단축키: openclaw onboard --auth-choice opencode-zen.

{
  agents: {
    defaults: {
      model: { primary: "opencode/claude-opus-4-5" },
      models: { "opencode/claude-opus-4-5": { alias: "Opus" } }
    }
  }
}

Z.AI (GLM-4.7) — provider 별칭 지원

Z.AI 모델은 내장 zai provider를 통해 사용할 수 있습니다. 환경에 ZAI_API_KEY를 설정하고 provider/model로 모델을 참조하세요.

단축키: openclaw onboard --auth-choice zai-api-key.

{
  agents: {
    defaults: {
      model: { primary: "zai/glm-4.7" },
      models: { "zai/glm-4.7": {} }
    }
  }
}

참고사항:

• z.ai/* 및 z-ai/*는 허용되는 별칭이며 zai/*로 정규화됩니다.
• ZAI_API_KEY가 없으면 zai/* 요청은 런타임에 인증 오류로 실패합니다.
• 예제 오류: No API key found for provider "zai".
• Z.AI의 일반 API 엔드포인트는 https://api.z.ai/api/paas/v4입니다. GLM 코딩 요청은 전용 Coding 엔드포인트 https://api.z.ai/api/coding/paas/v4를 사용합니다. 내장 zai provider는 Coding 엔드포인트를 사용합니다. 일반 엔드포인트가 필요하면 models.providers에 base URL을 재정의한 사용자 정의 provider를 정의하세요 (위의 사용자 정의 provider 섹션 참조).
• 문서/설정에서는 가짜 플레이스홀더를 사용하고 실제 API key는 절대 커밋하지 마세요.

Moonshot AI (Kimi)

Moonshot의 OpenAI 호환 엔드포인트를 사용하세요:

{
  env: { MOONSHOT_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "moonshot/kimi-k2.5" },
      models: { "moonshot/kimi-k2.5": { alias: "Kimi K2.5" } }
    }
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "kimi-k2.5",
            name: "Kimi K2.5",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 256000,
            maxTokens: 8192
          }
        ]
      }
    }
  }
}

참고사항:

• 환경에 MOONSHOT_API_KEY를 설정하거나 openclaw onboard --auth-choice moonshot-api-key를 사용하세요.
• 모델 참조: moonshot/kimi-k2.5.
• 중국 엔드포인트가 필요하면 https://api.moonshot.cn/v1을 사용하세요.

Kimi Code

Kimi Code의 전용 OpenAI 호환 엔드포인트를 사용하세요 (Moonshot과 별개):

{
  env: { KIMICODE_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "kimi-code/kimi-for-coding" },
      models: { "kimi-code/kimi-for-coding": { alias: "Kimi Code" } }
    }
  },
  models: {
    mode: "merge",
    providers: {
      "kimi-code": {
        baseUrl: "https://api.kimi.com/coding/v1",
        apiKey: "${KIMICODE_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "kimi-for-coding",
            name: "Kimi For Coding",
            reasoning: true,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 262144,
            maxTokens: 32768,
            headers: { "User-Agent": "KimiCLI/0.77" },
            compat: { supportsDeveloperRole: false }
          }
        ]
      }
    }
  }
}

참고사항:

• 환경에 KIMICODE_API_KEY를 설정하거나 openclaw onboard --auth-choice kimi-code-api-key를 사용하세요.
• 모델 참조: kimi-code/kimi-for-coding.

Synthetic (Anthropic 호환)

Synthetic의 Anthropic 호환 엔드포인트를 사용하세요:

{
  env: { SYNTHETIC_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.1" },
      models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.1": { alias: "MiniMax M2.1" } }
    }
  },
  models: {
    mode: "merge",
    providers: {
      synthetic: {
        baseUrl: "https://api.synthetic.new/anthropic",
        apiKey: "${SYNTHETIC_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "hf:MiniMaxAI/MiniMax-M2.1",
            name: "MiniMax M2.1",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 192000,
            maxTokens: 65536
          }
        ]
      }
    }
  }
}

참고사항:

• SYNTHETIC_API_KEY를 설정하거나 openclaw onboard --auth-choice synthetic-api-key를 사용하세요.
• 모델 참조: synthetic/hf:MiniMaxAI/MiniMax-M2.1.
• Anthropic 클라이언트가 /v1을 추가하므로 Base URL에서 /v1을 생략해야 합니다.

로컬 모델 (LM Studio) — 권장 설정

현재 로컬 가이드는 /gateway/local-models를 참조하세요. 요약: 강력한 하드웨어에서 LM Studio Responses API를 통해 MiniMax M2.1을 실행하고, 폴백을 위해 호스팅 모델을 병합해 두세요.

MiniMax M2.1

LM Studio 없이 MiniMax M2.1을 직접 사용하세요:

{
  agent: {
    model: { primary: "minimax/MiniMax-M2.1" },
    models: {
      "anthropic/claude-opus-4-5": { alias: "Opus" },
      "minimax/MiniMax-M2.1": { alias: "Minimax" }
    }
  },
  models: {
    mode: "merge",
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        apiKey: "${MINIMAX_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "MiniMax-M2.1",
            name: "MiniMax M2.1",
            reasoning: false,
            input: ["text"],
            // 가격: 정확한 비용 추적이 필요하면 models.json에서 업데이트하세요.
            cost: { input: 15, output: 60, cacheRead: 2, cacheWrite: 10 },
            contextWindow: 200000,
            maxTokens: 8192
          }
        ]
      }
    }
  }
}

참고사항:

• MINIMAX_API_KEY 환경 변수를 설정하거나 openclaw onboard --auth-choice minimax-api를 사용하세요.
• 사용 가능한 모델: MiniMax-M2.1 (기본값).
• 정확한 비용 추적이 필요하면 models.json에서 가격을 업데이트하세요.

Cerebras (GLM 4.6 / 4.7)

Cerebras의 OpenAI 호환 엔드포인트를 사용하세요:

{
  env: { CEREBRAS_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: {
        primary: "cerebras/zai-glm-4.7",
        fallbacks: ["cerebras/zai-glm-4.6"]
      },
      models: {
        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },
        "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (Cerebras)" }
      }
    }
  },
  models: {
    mode: "merge",
    providers: {
      cerebras: {
        baseUrl: "https://api.cerebras.ai/v1",
        apiKey: "${CEREBRAS_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },
          { id: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" }
        ]
      }
    }
  }
}

참고사항:

• Cerebras의 경우 cerebras/zai-glm-4.7을 사용하고, Z.AI 직접 연결의 경우 zai/glm-4.7을 사용하세요.
• 환경이나 설정에 CEREBRAS_API_KEY를 설정하세요.

참고사항:

• 지원되는 API: openai-completions, openai-responses, anthropic-messages, google-generative-ai
• 사용자 정의 인증이 필요하면 authHeader: true + headers를 사용하세요.
• models.json를 다른 곳에 저장하려면 OPENCLAW_AGENT_DIR (또는 PI_CODING_AGENT_DIR)로 agent 설정 루트를 재정의하세요 (기본값: ~/.openclaw/agents/main/agent).

session

세션 범위 지정, 재설정 정책, 재설정 트리거 및 세션 저장소 위치를 제어합니다.

{
  session: {
    scope: "per-sender",
    dmScope: "main",
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"]
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 60
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      dm: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 }
    },
    resetTriggers: ["/new", "/reset"],
    // 기본값은 이미 ~/.openclaw/agents/<agentId>/sessions/sessions.json 아래의 agent별 경로입니다
    // {agentId} 템플릿으로 재정의할 수 있습니다:
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    // 직접 채팅은 agent:<agentId>:<mainKey>로 축소됩니다 (기본값: "main").
    mainKey: "main",
    agentToAgent: {
      // 요청자/대상 간 최대 핑퐁 응답 턴 수 (0–5).
      maxPingPongTurns: 5
    },
    sendPolicy: {
      rules: [
        { action: "deny", match: { channel: "discord", chatType: "group" } }
      ],
      default: "allow"
    }
  }
}

필드:

• mainKey: 직접 채팅 버킷 키 (기본값: "main"). agentId를 변경하지 않고 기본 DM 스레드의 "이름을 변경"하고 싶을 때 유용합니다.
  • Sandbox 참고: agents.defaults.sandbox.mode: "non-main"은 이 키를 사용하여 메인 세션을 감지합니다. mainKey와 일치하지 않는 세션 키 (그룹/채널)는 샌드박스 처리됩니다.
• dmScope: DM 세션 그룹화 방식 (기본값: "main").
  • main: 모든 DM이 연속성을 위해 메인 세션을 공유합니다.
  • per-peer: 채널 전체에서 발신자 ID별로 DM을 격리합니다.
  • per-channel-peer: 채널 + 발신자별로 DM을 격리합니다 (멀티 사용자 받은편지함에 권장).
  • per-account-channel-peer: 계정 + 채널 + 발신자별로 DM을 격리합니다 (멀티 계정 받은편지함에 권장).
• identityLinks: 표준 ID를 provider 접두사가 붙은 피어에 매핑하여 per-peer, per-channel-peer 또는 per-account-channel-peer를 사용할 때 동일한 사람이 채널 간에 DM 세션을 공유하도록 합니다.
  • 예제: alice: ["telegram:123456789", "discord:987654321012345678"].
• reset: 기본 재설정 정책. 기본적으로 게이트웨이 호스트의 현지 시간으로 오전 4시에 매일 재설정됩니다.
  • mode: daily 또는 idle (기본값: reset이 있을 때 daily).
  • atHour: 일일 재설정 경계의 현지 시간 (0-23).
  • idleMinutes: 슬라이딩 유휴 윈도우 (분). daily와 idle이 모두 구성되면 먼저 만료되는 것이 적용됩니다.
• resetByType: dm, group, thread에 대한 세션별 재정의.
  • reset/resetByType 없이 레거시 session.idleMinutes만 설정하면 OpenClaw는 하위 호환성을 위해 유휴 전용 모드로 유지됩니다.
• heartbeatIdleMinutes: 하트비트 확인에 대한 선택적 유휴 재정의 (일일 재설정이 활성화되어 있으면 여전히 적용됨).
• agentToAgent.maxPingPongTurns: 요청자/대상 간 최대 응답 턴 수 (0–5, 기본값 5).
• sendPolicy.default: 규칙이 일치하지 않을 때 allow 또는 deny 폴백.
• sendPolicy.rules[]: channel, chatType (direct|group|room) 또는 keyPrefix (예: cron:)로 일치. 첫 번째 거부가 우선하고, 그렇지 않으면 허용합니다.

skills (skills 설정)

번들 허용 목록, 설치 기본 설정, 추가 skill 폴더 및 skill별 재정의를 제어합니다. 번들 skill과 ~/.openclaw/skills에 적용됩니다 (워크스페이스 skill은 이름 충돌 시 여전히 우선합니다).

필드:

• allowBundled: 번들 skill 전용 선택적 허용 목록. 설정하면 해당 번들 skill만 적격입니다 (관리형/워크스페이스 skill은 영향을 받지 않습니다).
• load.extraDirs: 스캔할 추가 skill 디렉토리 (가장 낮은 우선순위).
• install.preferBrew: 가능한 경우 brew 설치 프로그램 선호 (기본값: true).
• install.nodeManager: node 설치 프로그램 기본 설정 (npm | pnpm | yarn, 기본값: npm).
• entries.<skillKey>: skill별 설정 재정의.

skill별 필드:

• enabled: skill이 번들/설치되어 있어도 비활성화하려면 false로 설정합니다.
• env: agent 실행에 주입되는 환경 변수 (이미 설정되지 않은 경우에만).
• apiKey: 기본 환경 변수를 선언하는 skill을 위한 선택적 편의 기능 (예: nano-banana-pro → GEMINI_API_KEY).

예제:

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: [
        "~/Projects/agent-scripts/skills",
        "~/Projects/oss/some-skill-pack/skills"
      ]
    },
    install: {
      preferBrew: true,
      nodeManager: "npm"
    },
    entries: {
      "nano-banana-pro": {
        apiKey: "GEMINI_KEY_HERE",
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE"
        }
      },
      peekaboo: { enabled: true },
      sag: { enabled: false }
    }
  }
}

plugins (확장 프로그램)

플러그인 검색, 허용/거부 및 플러그인별 설정을 제어합니다. 플러그인은 ~/.openclaw/extensions, <workspace>/.openclaw/extensions 및 모든 plugins.load.paths 항목에서 로드됩니다. 설정 변경 시 게이트웨이 재시작이 필요합니다. 전체 사용법은 /plugin을 참조하세요.

필드:

• enabled: 플러그인 로딩을 위한 마스터 토글 (기본값: true).
• allow: 플러그인 ID의 선택적 허용 목록; 설정하면 나열된 플러그인만 로드됩니다.
• deny: 플러그인 ID의 선택적 거부 목록 (거부가 우선합니다).
• load.paths: 로드할 추가 플러그인 파일 또는 디렉토리 (절대 경로 또는 ~).
• entries.<pluginId>: 플러그인별 재정의.
  • enabled: 비활성화하려면 false로 설정합니다.
  • config: 플러그인별 설정 객체 (제공된 경우 플러그인에 의해 검증됨).

예제:

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    load: {
      paths: ["~/Projects/oss/voice-call-extension"]
    },
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio"
        }
      }
    }
  }
}

browser (openclaw 관리 브라우저)

OpenClaw는 openclaw를 위한 전용 격리된 Chrome/Brave/Edge/Chromium 인스턴스를 시작하고 작은 루프백 제어 서비스를 노출할 수 있습니다. 프로필은 profiles.<name>.cdpUrl을 통해 원격 Chromium 기반 브라우저를 가리킬 수 있습니다. 원격 프로필은 연결 전용입니다 (시작/중지/재설정은 비활성화됨).

browser.cdpUrl은 레거시 단일 프로필 설정과 cdpPort만 설정하는 프로필의 기본 스키마/호스트로 남아 있습니다.

기본값:

• enabled: true
• evaluateEnabled: true (act:evaluate 및 wait --fn을 비활성화하려면 false로 설정)
• 제어 서비스: 루프백 전용 (포트는 gateway.port에서 파생됨, 기본값 18791)
• CDP URL: http://127.0.0.1:18792 (제어 서비스 + 1, 레거시 단일 프로필)
• 프로필 색상: #FF4500 (랍스터 오렌지)
• 참고: 제어 서버는 실행 중인 게이트웨이 (OpenClaw.app 메뉴바 또는 openclaw gateway)에 의해 시작됩니다.
• 자동 감지 순서: 기본 브라우저가 Chromium 기반이면 그것을 사용하고, 그렇지 않으면 Chrome → Brave → Edge → Chromium → Chrome Canary.

{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    // cdpUrl: "http://127.0.0.1:18792", // 레거시 단일 프로필 재정의
    defaultProfile: "chrome",
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" }
    },
    color: "#FF4500",
    // 고급:
    // headless: false,
    // noSandbox: false,
    // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    // attachOnly: false, // 원격 CDP를 localhost로 터널링할 때 true로 설정
  }
}

ui (모양)

네이티브 앱이 UI 크롬 (예: Talk Mode 버블 색조)에 사용하는 선택적 강조 색상입니다.

설정하지 않으면 클라이언트는 은은한 연한 파란색으로 폴백합니다.

{
  ui: {
    seamColor: "#FF4500", // hex (RRGGBB 또는 #RRGGBB)
    // 선택사항: Control UI 어시스턴트 아이덴티티 재정의 제어.
    // 설정하지 않으면 Control UI는 활성 agent 아이덴티티 (설정 또는 IDENTITY.md)를 사용합니다.
    assistant: {
      name: "OpenClaw",
      avatar: "CB" // 이모지, 짧은 텍스트 또는 이미지 URL/data URI
    }
  }
}

gateway (Gateway 서버 모드 + bind)

gateway.mode를 사용하여 이 머신이 Gateway를 실행해야 하는지 명시적으로 선언합니다.

기본값:

• mode: 설정되지 않음 ("자동 시작 안 함"으로 처리됨)
• bind: loopback
• port: 18789 (WS + HTTP용 단일 포트)

{
  gateway: {
    mode: "local", // 또는 "remote"
    port: 18789, // WS + HTTP 다중화
    bind: "loopback",
    // controlUi: { enabled: true, basePath: "/openclaw" }
    // auth: { mode: "token", token: "your-token" } // token으로 WS + Control UI 액세스 게이팅
    // tailscale: { mode: "off" | "serve" | "funnel" }
  }
}

Control UI 기본 경로:

• gateway.controlUi.basePath는 Control UI가 제공되는 URL 접두사를 설정합니다.
• 예제: "/ui", "/openclaw", "/apps/openclaw".
• 기본값: 루트 (/) (변경되지 않음).
• gateway.controlUi.allowInsecureAuth는 장치 아이덴티티가 생략된 경우 (일반적으로 HTTP를 통해) Control UI에 대한 token 전용 인증을 허용합니다. 기본값: false. HTTPS (Tailscale Serve) 또는 127.0.0.1을 선호하세요.
• gateway.controlUi.dangerouslyDisableDeviceAuth는 Control UI에 대한 장치 아이덴티티 확인을 비활성화합니다 (token/password만). 기본값: false. 비상시에만 사용하세요.

관련 문서:

• Control UI
• Web 개요
• Tailscale
• 원격 액세스

신뢰할 수 있는 프록시:

• gateway.trustedProxies: Gateway 앞에서 TLS를 종료하는 역방향 프록시 IP 목록.
• 이러한 IP 중 하나에서 연결이 오면 OpenClaw는 x-forwarded-for (또는 x-real-ip)를 사용하여 로컬 페어링 확인 및 HTTP 인증/로컬 확인을 위한 클라이언트 IP를 결정합니다.
• 완전히 제어하는 프록시만 나열하고 들어오는 x-forwarded-for를 덮어쓰는지 확인하세요.

참고사항:

• openclaw gateway는 gateway.mode가 local로 설정되지 않으면 (또는 재정의 플래그를 전달하지 않으면) 시작을 거부합니다.
• gateway.port는 WebSocket + HTTP (control UI, hooks, A2UI)에 사용되는 단일 다중화 포트를 제어합니다.
• OpenAI Chat Completions 엔드포인트: 기본적으로 비활성화됨; gateway.http.endpoints.chatCompletions.enabled: true로 활성화합니다.
• 우선순위: --port > OPENCLAW_GATEWAY_PORT > gateway.port > 기본값 18789.
• Gateway 인증은 기본적으로 필수입니다 (token/password 또는 Tailscale Serve 아이덴티티). 루프백이 아닌 바인드는 공유 token/password가 필요합니다.
• 온보딩 마법사는 기본적으로 (루프백에서도) 게이트웨이 token을 생성합니다.
• gateway.remote.token은 원격 CLI 호출 전용입니다; 로컬 게이트웨이 인증을 활성화하지 않습니다. gateway.token은 무시됩니다.

인증 및 Tailscale:

• gateway.auth.mode는 핸드셰이크 요구사항을 설정합니다 (token 또는 password). 설정하지 않으면 token 인증이 가정됩니다.
• gateway.auth.token은 token 인증을 위한 공유 token을 저장합니다 (동일한 머신의 CLI에서 사용).
• gateway.auth.mode가 설정되면 해당 방법만 허용됩니다 (선택적 Tailscale 헤더 추가).
• gateway.auth.password는 여기에 설정하거나 OPENCLAW_GATEWAY_PASSWORD를 통해 설정할 수 있습니다 (권장).
• gateway.auth.allowTailscale은 x-forwarded-for, x-forwarded-proto 및 x-forwarded-host와 함께 루프백에 도착하는 요청에 대해 Tailscale Serve 아이덴티티 헤더 (tailscale-user-login)가 인증을 충족하도록 허용합니다. OpenClaw는 수락하기 전에 tailscale whois를 통해 x-forwarded-for 주소를 확인하여 아이덴티티를 검증합니다. true이면 Serve 요청에 token/password가 필요하지 않습니다; token/password 명시적 자격 증명을 요구하려면 false로 설정합니다. tailscale.mode = "serve"이고 인증 모드가 password가 아닐 때 기본값은 true입니다.
• gateway.tailscale.mode: "serve"는 Tailscale Serve를 사용합니다 (tailnet 전용, 루프백 바인드).
• gateway.tailscale.mode: "funnel"은 대시보드를 공개적으로 노출합니다; 인증이 필요합니다.
• gateway.tailscale.resetOnExit은 종료 시 Serve/Funnel 설정을 재설정합니다.

원격 클라이언트 기본값 (CLI):

• gateway.remote.url은 gateway.mode = "remote"일 때 CLI 호출에 대한 기본 Gateway WebSocket URL을 설정합니다.
• gateway.remote.transport는 macOS 원격 전송을 선택합니다 (ssh 기본값, ws/wss의 경우 direct). direct일 때 gateway.remote.url은 ws:// 또는 wss://여야 합니다. ws://host는 기본적으로 포트 18789를 사용합니다.
• gateway.remote.token은 원격 호출을 위한 token을 제공합니다 (인증이 없으면 설정하지 않음).
• gateway.remote.password는 원격 호출을 위한 password를 제공합니다 (인증이 없으면 설정하지 않음).

macOS 앱 동작:

• OpenClaw.app은 ~/.openclaw/openclaw.json을 감시하고 gateway.mode 또는 gateway.remote.url이 변경되면 실시간으로 모드를 전환합니다.
• gateway.mode가 설정되지 않았지만 gateway.remote.url이 설정되어 있으면 macOS 앱은 이를 원격 모드로 처리합니다.
• macOS 앱에서 연결 모드를 변경하면 gateway.mode (및 원격 모드에서 gateway.remote.url + gateway.remote.transport)를 설정 파일에 다시 작성합니다.

{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://gateway.tailnet:18789",
      token: "your-token",
      password: "your-password"
    }
  }
}

Direct 전송 예제 (macOS 앱):

{
  gateway: {
    mode: "remote",
    remote: {
      transport: "direct",
      url: "wss://gateway.example.ts.net",
      token: "your-token"
    }
  }
}

gateway.reload (설정 핫 리로드)

Gateway는 ~/.openclaw/openclaw.json (또는 OPENCLAW_CONFIG_PATH)을 감시하고 변경 사항을 자동으로 적용합니다.

모드:

• hybrid (기본값): 안전한 변경 사항은 즉시 적용하고, 중요한 변경 사항에 대해서는 Gateway를 재시작합니다.
• hot: 핫 안전 변경 사항만 적용하고, 재시작이 필요할 때 로그를 기록합니다.
• restart: 설정 변경 시 Gateway를 재시작합니다.
• off: 핫 리로드를 비활성화합니다.

{
  gateway: {
    reload: {
      mode: "hybrid",
      debounceMs: 300
    }
  }
}

핫 리로드 매트릭스 (파일 + 영향)

감시되는 파일:

• ~/.openclaw/openclaw.json (또는 OPENCLAW_CONFIG_PATH)

즉시 적용 (전체 게이트웨이 재시작 없음):

• hooks (webhook 인증/경로/매핑) + hooks.gmail (Gmail 감시자 재시작)
• browser (브라우저 제어 서버 재시작)
• cron (cron 서비스 재시작 + 동시성 업데이트)
• agents.defaults.heartbeat (하트비트 러너 재시작)
• web (WhatsApp 웹 채널 재시작)
• telegram, discord, signal, imessage (채널 재시작)
• agent, models, routing, messages, session, whatsapp, logging, skills, ui, talk, identity, wizard (동적 읽기)

전체 Gateway 재시작 필요:

• gateway (포트/바인드/인증/control UI/tailscale)
• bridge (레거시)
• discovery
• canvasHost
• plugins
• 알 수 없거나 지원되지 않는 설정 경로 (안전을 위해 기본적으로 재시작)

멀티 인스턴스 격리

한 호스트에서 여러 게이트웨이를 실행하려면 (중복성 또는 구조 봇을 위해) 인스턴스별 상태 + 설정을 격리하고 고유한 포트를 사용하세요:

• OPENCLAW_CONFIG_PATH (인스턴스별 설정)
• OPENCLAW_STATE_DIR (세션/자격 증명)
• agents.defaults.workspace (메모리)
• gateway.port (인스턴스별 고유)

편의 플래그 (CLI):

• openclaw --dev … → ~/.openclaw-dev를 사용하고 기본 19001에서 포트를 이동합니다
• openclaw --profile <name> … → ~/.openclaw-<name>을 사용합니다 (포트는 설정/env/플래그를 통해)

파생된 포트 매핑 (gateway/browser/canvas)은 Gateway 런북을 참조하세요. 브라우저/CDP 포트 격리 세부 정보는 여러 게이트웨이를 참조하세요.

예제:

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

hooks (Gateway webhook)

Gateway HTTP 서버에서 간단한 HTTP webhook 엔드포인트를 활성화합니다.

기본값:

• enabled: false
• path: /hooks
• maxBodyBytes: 262144 (256 KB)

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate:
          "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        model: "openai/gpt-5.2-mini",
      },
    ],
  }
}

요청에는 hook token이 포함되어야 합니다:

• Authorization: Bearer <token> 또는
• x-openclaw-token: <token> 또는
• ?token=<token>

엔드포인트:

• POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
• POST /hooks/agent → { message, name?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
• POST /hooks/<name> → hooks.mappings를 통해 확인

/hooks/agent는 항상 메인 세션에 요약을 게시합니다 (그리고 선택적으로 wakeMode: "now"를 통해 즉각적인 하트비트를 트리거할 수 있습니다).

매핑 참고사항:

• match.path는 /hooks 이후의 하위 경로와 일치합니다 (예: /hooks/gmail → gmail).
• match.source는 페이로드 필드와 일치합니다 (예: { source: "gmail" }) 따라서 일반 /hooks/ingest 경로를 사용할 수 있습니다.
• {{messages[0].subject}}와 같은 템플릿은 페이로드에서 읽습니다.
• transform은 hook 액션을 반환하는 JS/TS 모듈을 가리킬 수 있습니다.
• deliver: true는 최종 응답을 채널로 보냅니다; channel은 기본적으로 last입니다 (WhatsApp으로 폴백).
• 이전 배달 경로가 없으면 channel + to를 명시적으로 설정하세요 (Telegram/Discord/Google Chat/Slack/Signal/iMessage/MS Teams에 필요).
• model은 이 hook 실행에 대한 LLM을 재정의합니다 (provider/model 또는 별칭; agents.defaults.models가 설정된 경우 허용되어야 함).

Gmail 도우미 설정 (openclaw webhooks gmail setup / run에서 사용):

{
  hooks: {
    gmail: {
      account: "[email protected]",
      topic: "projects/<project-id>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "shared-push-token",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
      serve: { bind: "127.0.0.1", port: 8788, path: "/" },
      tailscale: { mode: "funnel", path: "/gmail-pubsub" },

      // 선택사항: Gmail hook 처리에 더 저렴한 모델 사용
      // 인증/속도 제한/시간 초과 시 agents.defaults.model.fallbacks, 그 다음 primary로 폴백
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      // 선택사항: Gmail hook의 기본 thinking 레벨
      thinking: "off",
    }
  }
}

Gmail hook에 대한 모델 재정의:

• hooks.gmail.model은 Gmail hook 처리에 사용할 모델을 지정합니다 (기본값은 세션 primary).
• provider/model 참조 또는 agents.defaults.models의 별칭을 허용합니다.
• 인증/속도 제한/시간 초과 시 agents.defaults.model.fallbacks, 그 다음 agents.defaults.model.primary로 폴백합니다.
• agents.defaults.models가 설정된 경우 hooks 모델을 허용 목록에 포함하세요.
• 시작 시 구성된 모델이 모델 카탈로그나 허용 목록에 없으면 경고합니다.
• hooks.gmail.thinking은 Gmail hook의 기본 thinking 레벨을 설정하며 hook별 thinking에 의해 재정의됩니다.

Gateway 자동 시작:

• hooks.enabled=true이고 hooks.gmail.account가 설정되면 Gateway는 부팅 시 gog gmail watch serve를 시작하고 watch를 자동으로 갱신합니다.
• 자동 시작을 비활성화하려면 OPENCLAW_SKIP_GMAIL_WATCHER=1을 설정하세요 (수동 실행용).
• Gateway와 함께 별도의 gog gmail watch serve를 실행하지 마세요; listen tcp 127.0.0.1:8788: bind: address already in use로 실패합니다.

참고: tailscale.mode가 켜져 있으면 OpenClaw는 기본적으로 serve.path를 /로 설정하여 Tailscale이 /gmail-pubsub을 올바르게 프록시할 수 있도록 합니다 (설정 경로 접두사를 제거합니다). 백엔드가 접두사가 붙은 경로를 받아야 하는 경우 hooks.gmail.tailscale.target을 전체 URL로 설정하세요 (그리고 serve.path를 정렬하세요).

canvasHost (LAN/tailnet Canvas 파일 서버 + 라이브 리로드)

Gateway는 HTML/CSS/JS 디렉토리를 HTTP를 통해 제공하므로 iOS/Android 노드가 단순히 canvas.navigate할 수 있습니다.

기본 루트: ~/.openclaw/workspace/canvas
기본 포트: 18793 (openclaw 브라우저 CDP 포트 18792를 피하기 위해 선택됨)
서버는 노드가 도달할 수 있도록 gateway bind 호스트 (LAN 또는 Tailnet)에서 수신 대기합니다.

서버:

• canvasHost.root 아래의 파일을 제공합니다
• 제공되는 HTML에 작은 라이브 리로드 클라이언트를 주입합니다
• 디렉토리를 감시하고 /__openclaw__/ws의 WebSocket 엔드포인트를 통해 리로드를 브로드캐스트합니다
• 디렉토리가 비어 있으면 시작 index.html을 자동 생성합니다 (즉시 무언가를 볼 수 있도록)
• /__openclaw__/a2ui/에서 A2UI도 제공하며 canvasHostUrl로 노드에 광고됩니다 (항상 Canvas/A2UI에 대해 노드에서 사용됨)

디렉토리가 크거나 EMFILE에 도달하면 라이브 리로드 (및 파일 감시)를 비활성화하세요:

• 설정: canvasHost: { liveReload: false }

{
  canvasHost: {
    root: "~/.openclaw/workspace/canvas",
    port: 18793,
    liveReload: true
  }
}

canvasHost.* 변경 시 게이트웨이 재시작이 필요합니다 (설정 리로드가 재시작합니다).

비활성화:

• 설정: canvasHost: { enabled: false }
• 환경: OPENCLAW_SKIP_CANVAS_HOST=1

bridge (레거시 TCP 브리지, 제거됨)

현재 빌드에는 더 이상 TCP 브리지 리스너가 포함되지 않습니다; bridge.* 설정 키는 무시됩니다. 노드는 Gateway WebSocket을 통해 연결합니다. 이 섹션은 역사적 참조를 위해 유지됩니다.

레거시 동작:

• Gateway는 노드 (iOS/Android)를 위한 간단한 TCP 브리지를 노출할 수 있었으며, 일반적으로 포트 18790에서 제공되었습니다.

기본값:

• enabled: true
• port: 18790
• bind: lan (0.0.0.0에 바인딩)

바인드 모드:

• lan: 0.0.0.0 (LAN/Wi‑Fi 및 Tailscale을 포함한 모든 인터페이스에서 도달 가능)
• tailnet: 머신의 Tailscale IP에만 바인딩 (Vienna ⇄ London에 권장)
• loopback: 127.0.0.1 (로컬 전용)
• auto: tailnet IP가 있으면 선호하고, 그렇지 않으면 lan

TLS:

• bridge.tls.enabled: 브리지 연결에 대해 TLS 활성화 (활성화되면 TLS 전용).
• bridge.tls.autoGenerate: 인증서/키가 없을 때 자체 서명 인증서 생성 (기본값: true).
• bridge.tls.certPath / bridge.tls.keyPath: 브리지 인증서 + 개인 키의 PEM 경로.
• bridge.tls.caPath: 선택적 PEM CA 번들 (사용자 정의 루트 또는 향후 mTLS).

TLS가 활성화되면 Gateway는 노드가 인증서를 고정할 수 있도록 검색 TXT 레코드에서 bridgeTls=1 및 bridgeTlsSha256을 광고합니다. 수동 연결은 아직 저장된 지문이 없으면 최초 신뢰를 사용합니다. 자동 생성된 인증서에는 PATH에 openssl이 필요합니다; 생성에 실패하면 브리지가 시작되지 않습니다.

{
  bridge: {
    enabled: true,
    port: 18790,
    bind: "tailnet",
    tls: {
      enabled: true,
      // 생략하면 ~/.openclaw/bridge/tls/bridge-{cert,key}.pem을 사용합니다.
      // certPath: "~/.openclaw/bridge/tls/bridge-cert.pem",
      // keyPath: "~/.openclaw/bridge/tls/bridge-key.pem"
    }
  }
}

discovery.mdns (Bonjour / mDNS 브로드캐스트 모드)

LAN mDNS 검색 브로드캐스트 (_openclaw-gw._tcp)를 제어합니다.

• minimal (기본값): TXT 레코드에서 cliPath + sshPort 생략
• full: TXT 레코드에 cliPath + sshPort 포함
• off: mDNS 브로드캐스트 완전히 비활성화
• 호스트명: 기본값은 openclaw (openclaw.local을 광고). OPENCLAW_MDNS_HOSTNAME으로 재정의.

{
  discovery: { mdns: { mode: "minimal" } }
}

discovery.wideArea (Wide-Area Bonjour / 유니캐스트 DNS‑SD)

활성화되면 Gateway는 구성된 검색 도메인 (예: openclaw.internal.)에서 _openclaw-gw._tcp에 대한 유니캐스트 DNS-SD 존을 ~/.openclaw/dns/에 작성합니다.

iOS/Android가 네트워크 간에 검색하도록 하려면 (Vienna ⇄ London) 다음과 페어링하세요:

• 선택한 도메인을 제공하는 게이트웨이 호스트의 DNS 서버 (CoreDNS 권장)
• 클라이언트가 게이트웨이 DNS 서버를 통해 해당 도메인을 확인하도록 Tailscale split DNS

일회성 설정 도우미 (게이트웨이 호스트):

openclaw dns setup --apply

{
  discovery: { wideArea: { enabled: true } }
}

템플릿 변수

템플릿 플레이스홀더는 tools.media.*.models[].args 및 tools.media.models[].args (및 향후 템플릿화된 인수 필드)에서 확장됩니다.

Cron (Gateway 스케줄러)

Cron은 깨우기 및 예약된 작업을 위한 Gateway 소유 스케줄러입니다. 기능 개요 및 CLI 예제는 Cron jobs를 참조하세요.

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2
  }
}

다음: Agent Runtime 🦞