Gateway
구성 예제
아래 예시는 현재 구성 스키마에 맞춰져 있습니다. 전체 참조 문서와 필드별 참고 사항은 구성을 참조하세요.
빠른 시작
최소 구성
{ agents: { defaults: { workspace: "~/.openclaw/workspace" } }, channels: { whatsapp: { allowFrom: ["+15555550123"] } },}~/.openclaw/openclaw.json에 저장하면 해당 번호로 봇에게 DM을 보낼 수 있습니다.
권장 시작 구성
{ agents: { defaults: { workspace: "~/.openclaw/workspace", model: { primary: "anthropic/claude-sonnet-4-6" }, }, list: [ { id: "main", identity: { name: "Clawd", theme: "helpful assistant", emoji: "🦞", }, }, ], }, channels: { whatsapp: { allowFrom: ["+15555550123"], groups: { "*": { requireMention: true } }, }, }, messages: { visibleReplies: "automatic", groupChat: { visibleReplies: "message_tool", // 명시적으로 활성화해야 하며, 표시되는 출력을 생성하려면 message(action=send)가 필요합니다 unmentionedInbound: "room_event", }, },}확장 예시(주요 옵션)
JSON5에서는 주석과 후행 쉼표를 사용할 수 있습니다. 일반 JSON도 사용할 수 있습니다.
{ // 환경 + 셸 env: { OPENROUTER_API_KEY: "sk-or-...", vars: { GROQ_API_KEY: "gsk-...", }, shellEnv: { enabled: true, timeoutMs: 15000, }, }, // 인증 프로필 메타데이터(보안 비밀은 auth-profiles.json에 저장됨) auth: { profiles: { "anthropic:default": { provider: "anthropic", mode: "api_key" }, "anthropic:work": { provider: "anthropic", mode: "api_key" }, "openai:default": { provider: "openai", mode: "api_key" }, "openai:personal": { provider: "openai", mode: "oauth" }, }, order: { anthropic: ["anthropic:default", "anthropic:work"], openai: ["openai:personal", "openai:default"], }, }, // ID는 에이전트별로 설정됩니다. 아래 agents.list[].identity에서 설정하세요. // 로깅 logging: { level: "info", file: "/tmp/openclaw/openclaw.log", consoleLevel: "info", consoleStyle: "pretty", redactSensitive: "tools", }, // 메시지 형식 messages: { messagePrefix: "[openclaw]", visibleReplies: "automatic", responsePrefix: ">", ackReaction: "👀", ackReactionScope: "group-mentions", groupChat: { historyLimit: 50, visibleReplies: "message_tool", // 도구를 안정적으로 사용하는 모델이 있는 공유 대화방에서 명시적으로 사용 unmentionedInbound: "room_event", }, queue: { mode: "followup", debounceMs: 500, cap: 20, drop: "summarize", byChannel: { whatsapp: "followup", telegram: "followup", discord: "collect", slack: "collect", signal: "followup", imessage: "followup", webchat: "followup", }, }, }, // 도구 tools: { media: { audio: { enabled: true, maxBytes: 20971520, models: [ { provider: "openai", model: "gpt-4o-transcribe" }, // 선택적 CLI 대체 수단(Whisper 바이너리): // { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] } ], timeoutSeconds: 120, }, video: { enabled: true, maxBytes: 52428800, models: [{ provider: "google", model: "gemini-3-flash-preview" }], }, }, }, // 세션 동작 session: { scope: "per-sender", dmScope: "per-channel-peer", // 여러 사용자가 사용하는 받은 편지함에 권장 reset: { mode: "daily", atHour: 4, idleMinutes: 60, }, resetByChannel: { discord: { mode: "idle", idleMinutes: 10080 }, }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/main/sessions/sessions.json", maintenance: { mode: "warn", pruneAfter: "30d", maxEntries: 500, resetArchiveRetention: "30d", // 기간 또는 false maxDiskBytes: "500mb", // 선택 사항 highWaterBytes: "400mb", // 선택 사항(기본값은 maxDiskBytes의 80%) }, typingIntervalSeconds: 5, sendPolicy: { default: "allow", rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], }, }, // 채널 channels: { whatsapp: { dmPolicy: "pairing", allowFrom: ["+15555550123"], groupPolicy: "allowlist", groupAllowFrom: ["+15555550123"], groups: { "*": { requireMention: true } }, }, telegram: { enabled: true, botToken: "YOUR_TELEGRAM_BOT_TOKEN", allowFrom: ["123456789"], groupPolicy: "allowlist", groupAllowFrom: ["123456789"], groups: { "*": { requireMention: true } }, }, discord: { enabled: true, token: "YOUR_DISCORD_BOT_TOKEN", dm: { enabled: true, allowFrom: ["123456789012345678"] }, guilds: { "123456789012345678": { slug: "friends-of-openclaw", requireMention: false, channels: { general: { enabled: true }, help: { enabled: true, requireMention: true }, }, }, }, }, slack: { enabled: true, botToken: "xoxb-REPLACE_ME", appToken: "xapp-REPLACE_ME", channels: { "#general": { enabled: true, requireMention: true }, }, dm: { enabled: true, allowFrom: ["U123"] }, slashCommand: { enabled: true, name: "openclaw", sessionPrefix: "slack:slash", ephemeral: true, }, }, }, // 에이전트 런타임 agents: { defaults: { workspace: "~/.openclaw/workspace", userTimezone: "America/Chicago", model: { primary: "anthropic/claude-sonnet-4-6", fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.4"], }, imageModel: { primary: "openrouter/anthropic/claude-sonnet-4-6", }, models: { "anthropic/claude-opus-4-6": { alias: "opus" }, "anthropic/claude-sonnet-4-6": { alias: "sonnet" }, "openai/gpt-5.4": { alias: "gpt" }, }, skills: ["github", "weather"], // list[].skills를 생략한 에이전트가 상속함 thinkingDefault: "low", verboseDefault: "off", toolProgressDetail: "explain", reasoningDefault: "off", elevatedDefault: "on", blockStreamingDefault: "off", blockStreamingBreak: "text_end", blockStreamingChunk: { minChars: 800, maxChars: 1200, breakPreference: "paragraph", }, blockStreamingCoalesce: { idleMs: 1000, }, humanDelay: { mode: "natural", }, timeoutSeconds: 600, mediaMaxMb: 5, typingIntervalSeconds: 5, maxConcurrent: 3, heartbeat: { every: "30m", model: "anthropic/claude-sonnet-4-6", target: "last", directPolicy: "allow", // 허용(기본값) | 차단 to: "+15555550123", prompt: "HEARTBEAT", ackMaxChars: 300, }, memorySearch: { provider: "gemini", model: "gemini-embedding-001", remote: { apiKey: "${GEMINI_API_KEY}", }, extraPaths: ["../team-docs", "/srv/shared-notes"], }, sandbox: { mode: "non-main", scope: "session", // 기존 perSession: true보다 권장 workspaceRoot: "~/.openclaw/sandboxes", docker: { image: "openclaw-sandbox:bookworm-slim", workdir: "/workspace", readOnlyRoot: true, tmpfs: ["/tmp", "/var/tmp", "/run"], network: "none", user: "1000:1000", }, browser: { enabled: false, }, }, }, list: [ { id: "main", default: true, identity: { name: "Samantha", theme: "helpful sloth", emoji: "🦥", }, // defaults.skills를 상속함 -> github, weather groupChat: { mentionPatterns: ["@openclaw", "openclaw"], }, thinkingDefault: "high", // 에이전트별 사고 설정 재정의 reasoningDefault: "on", // 에이전트별 추론 표시 여부 fastModeDefault: false, // 에이전트별 빠른 모드 }, { id: "quick", skills: [], // 이 에이전트에는 Skills가 없음 fastModeDefault: true, // 이 에이전트는 항상 빠르게 실행됨 thinkingDefault: "off", }, ], }, tools: { allow: ["exec", "process", "read", "write", "edit", "apply_patch"], deny: ["browser", "canvas"], exec: { backgroundMs: 10000, timeoutSec: 1800, cleanupMs: 1800000, }, elevated: { enabled: true, allowFrom: { whatsapp: ["+15555550123"], telegram: ["123456789"], discord: ["123456789012345678"], slack: ["U123"], signal: ["+15555550123"], imessage: ["user@example.com"], webchat: ["session:demo"], }, }, }, // 사용자 지정 모델 제공자 models: { mode: "merge", providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", apiKey: "LITELLM_KEY", api: "openai-responses", authHeader: true, headers: { "X-Proxy-Region": "us-west" }, models: [ { id: "llama-3.1-8b", name: "Llama 3.1 8B", api: "openai-responses", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 128000, maxTokens: 32000, }, ], }, }, }, // Cron 작업 cron: { enabled: true, store: "~/.openclaw/cron/jobs.json", maxConcurrentRuns: 8, // 기본값; Cron 디스패치 + 격리된 Cron 에이전트 턴 실행 sessionRetention: "24h", runLog: { maxBytes: "2mb", keepLines: 2000, }, }, // Webhook hooks: { enabled: true, path: "/hooks", token: "shared-secret", presets: ["gmail"], transformsDir: "~/.openclaw/hooks/transforms", mappings: [ { id: "gmail-hook", match: { path: "gmail" }, action: "agent", wakeMode: "now", name: "Gmail", sessionKey: "hook:gmail:{{messages[0].id}}", messageTemplate: "보낸 사람: {{messages[0].from}}\n제목: {{messages[0].subject}}", textTemplate: "{{messages[0].snippet}}", deliver: true, channel: "last", to: "+15555550123", thinking: "low", timeoutSeconds: 300, transform: { module: "gmail.js", export: "transformGmail", }, }, ], gmail: { account: "openclaw@gmail.com", label: "INBOX", 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" }, }, }, // Gateway + 네트워킹 gateway: { mode: "local", port: 18789, bind: "loopback", controlUi: { enabled: true, basePath: "/openclaw" }, auth: { mode: "token", token: "gateway-token", allowTailscale: true, }, tailscale: { mode: "serve", resetOnExit: false }, remote: { url: "ws://gateway-host.ts.net:18789", token: "remote-token" }, reload: { mode: "hybrid", debounceMs: 300 }, }, skills: { allowBundled: ["gemini", "peekaboo"], load: { extraDirs: ["~/Projects/agent-scripts/skills"], allowSymlinkTargets: ["~/Projects/agent-scripts/skills"], }, install: { preferBrew: true, nodeManager: "npm", // npm | pnpm | yarn | bun allowUploadedArchives: false, }, entries: { "image-lab": { enabled: true, apiKey: "GEMINI_KEY_HERE", env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, }, },}심볼릭 링크로 연결된 형제 Skills 저장소
기본 제공 Skills 루트에 형제 저장소를 가리키는 심볼릭 링크가 포함된 경우 사용합니다. 예를 들면
~/.agents/skills/manager -> ~/Projects/manager/skills입니다.
{ skills: { load: { extraDirs: ["~/Projects/manager/skills"], allowSymlinkTargets: ["~/Projects/manager/skills"], }, },}extraDirs는 형제 저장소를 명시적인 Skills 루트로 스캔합니다.allowSymlinkTargets를 사용하면 임의의 심볼릭 링크 이탈을 허용하지 않으면서 심볼릭 링크로 연결된 Skills 폴더를 신뢰할 수 있는 실제 대상 루트로 해석할 수 있습니다.- Skill Workshop이 동일한 신뢰할 수 있는 심볼릭 링크 대상을 통해 쓰기를 수행하도록 하려면
skills.workshop.allowSymlinkTargetWrites: true를 설정하세요.
일반적인 패턴
하나의 재정의가 있는 공유 Skills 기준 구성
{ agents: { defaults: { workspace: "~/.openclaw/workspace", skills: ["github", "weather"], }, list: [ { id: "main", default: true }, { id: "docs", workspace: "~/.openclaw/workspace-docs", skills: ["docs-search"] }, ], },}agents.defaults.skills는 공유 기준선입니다.agents.list[].skills는 한 에이전트에 대해 해당 기준선을 대체합니다.- 에이전트에 어떤 Skills도 표시하지 않으려면
skills: []를 사용하세요.
다중 플랫폼 설정
{ agents: { defaults: { workspace: "~/.openclaw/workspace" } }, channels: { whatsapp: { allowFrom: ["+15555550123"] }, telegram: { enabled: true, botToken: "YOUR_TOKEN", allowFrom: ["123456789"], }, discord: { enabled: true, token: "YOUR_TOKEN", dm: { allowFrom: ["123456789012345678"] }, }, },}신뢰할 수 있는 Node 네트워크 자동 승인
네트워크 경로를 직접 제어하지 않는 한 기기 페어링은 수동으로 유지하세요. 전용 실험실 또는 tailnet 서브넷에서는 정확한 CIDR이나 IP를 지정하여 최초 Node 기기 자동 승인을 사용하도록 설정할 수 있습니다.
{ gateway: { nodes: { pairing: { autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"], }, }, },}설정하지 않으면 이 기능은 계속 꺼져 있습니다. 요청된 범위가 없는 새로운
role: node 페어링에만 적용됩니다. 운영자/브라우저 클라이언트와 역할, 범위,
메타데이터 또는 공개 키 업그레이드는 여전히 수동 승인이 필요합니다.
안전한 DM 모드(공유 수신함/다중 사용자 DM)
두 명 이상이 봇에 DM을 보낼 수 있는 경우(allowFrom에 여러 항목이 있거나, 여러 사람의 페어링이 승인되었거나, dmPolicy: "open"인 경우)에는 서로 다른 발신자의 DM이 기본적으로 하나의 컨텍스트를 공유하지 않도록 안전한 DM 모드를 활성화하세요.
{ // 안전한 DM 모드(다중 사용자 또는 민감한 DM 에이전트에 권장) session: { dmScope: "per-channel-peer" }, channels: { // 예: WhatsApp 다중 사용자 수신함 whatsapp: { dmPolicy: "allowlist", allowFrom: ["+15555550123", "+15555550124"], }, // 예: Discord 다중 사용자 수신함 discord: { enabled: true, token: "YOUR_DISCORD_BOT_TOKEN", dm: { enabled: true, allowFrom: ["123456789012345678", "987654321098765432"] }, }, },}Discord/Google Chat/IRC/Mattermost/Microsoft Teams/Slack에서는 기본적으로 발신자 권한 부여 시 ID를 우선합니다.
그 위험을 명시적으로 수용하는 경우에만 각 채널의 dangerouslyAllowNameMatching: true를 설정하여 직접 변경 가능한 이름/이메일/닉네임 일치를 활성화하세요.
Anthropic API 키 + MiniMax 대체 모델
{ auth: { profiles: { "anthropic:api": { provider: "anthropic", mode: "api_key", }, }, order: { anthropic: ["anthropic:api"], }, }, models: { providers: { minimax: { baseUrl: "https://api.minimax.io/anthropic", api: "anthropic-messages", apiKey: "${MINIMAX_API_KEY}", }, }, }, agents: { defaults: { workspace: "~/.openclaw/workspace", model: { primary: "anthropic/claude-opus-4-6", fallbacks: ["minimax/MiniMax-M2.7"], }, }, },}업무용 봇(접근 제한)
{ agents: { defaults: { workspace: "~/work-openclaw", elevatedDefault: "off", }, list: [ { id: "main", identity: { name: "WorkBot", theme: "professional assistant", }, }, ], }, channels: { slack: { enabled: true, botToken: "xoxb-...", channels: { "#engineering": { enabled: true, requireMention: true }, "#general": { enabled: true, requireMention: true }, }, }, },}로컬 모델만 사용
{ agents: { defaults: { workspace: "~/.openclaw/workspace", model: { primary: "lmstudio/my-local-model" }, }, }, models: { mode: "merge", providers: { lmstudio: { baseUrl: "http://127.0.0.1:1234/v1", apiKey: "lmstudio", api: "openai-responses", models: [ { id: "my-local-model", name: "Local Model", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 196608, maxTokens: 8192, }, ], }, }, },}팁
dmPolicy: "open"을 설정하면 해당allowFrom목록에"*"가 포함되어야 합니다.- 제공자 ID 형식은 서로 다릅니다(전화번호, 사용자 ID, 채널 ID). 제공자 문서에서 형식을 확인하세요.
- 나중에 추가할 수 있는 선택적 섹션:
web,browser,ui,discovery,plugins,talk,signal,imessage. - 자세한 설정 참고 사항은 제공자 및 문제 해결을 참조하세요.
관련 문서
Was this useful?
