Gateway
Ví dụ cấu hình
Các ví dụ bên dưới được căn chỉnh với schema cấu hình hiện tại. Để xem tài liệu tham chiếu đầy đủ và ghi chú theo từng trường, hãy xem Cấu hình.
Bắt đầu nhanh
Tối thiểu tuyệt đối
{ agents: { defaults: { workspace: "~/.openclaw/workspace" } }, channels: { whatsapp: { allowFrom: ["+15555550123"] } },}Lưu vào ~/.openclaw/openclaw.json và bạn có thể nhắn tin trực tiếp cho bot từ số đó.
Cấu hình khởi đầu được khuyến nghị
{ 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", // default; use "automatic" for legacy room replies }, },}Ví dụ mở rộng (các tùy chọn chính)
JSON5 cho phép bạn dùng chú thích và dấu phẩy ở cuối. JSON thông thường cũng hoạt động.
{ // Environment + shell env: { OPENROUTER_API_KEY: "sk-or-...", vars: { GROQ_API_KEY: "gsk-...", }, shellEnv: { enabled: true, timeoutMs: 15000, }, }, // Auth profile metadata (secrets live in 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-codex:personal": { provider: "openai-codex", mode: "oauth" }, }, order: { anthropic: ["anthropic:default", "anthropic:work"], openai: ["openai:default"], "openai-codex": ["openai-codex:personal"], }, }, // Identity is per agent — set it on agents.list[].identity below. // Logging logging: { level: "info", file: "/tmp/openclaw/openclaw.log", consoleLevel: "info", consoleStyle: "pretty", redactSensitive: "tools", }, // Message formatting messages: { messagePrefix: "[openclaw]", visibleReplies: "automatic", responsePrefix: ">", ackReaction: "👀", ackReactionScope: "group-mentions", groupChat: { historyLimit: 50, visibleReplies: "message_tool", // normal final replies stay private in groups/channels }, queue: { mode: "steer", debounceMs: 500, cap: 20, drop: "summarize", byChannel: { whatsapp: "steer", telegram: "steer", discord: "steer", slack: "steer", signal: "steer", imessage: "steer", webchat: "steer", }, }, }, // Tooling tools: { media: { audio: { enabled: true, maxBytes: 20971520, models: [ { provider: "openai", model: "gpt-4o-mini-transcribe" }, // Optional CLI fallback (Whisper binary): // { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] } ], timeoutSeconds: 120, }, video: { enabled: true, maxBytes: 52428800, models: [{ provider: "google", model: "gemini-3-flash-preview" }], }, }, }, // Session behavior session: { scope: "per-sender", dmScope: "per-channel-peer", // recommended for multi-user inboxes reset: { mode: "daily", atHour: 4, idleMinutes: 60, }, resetByChannel: { discord: { mode: "idle", idleMinutes: 10080 }, }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/default/sessions/sessions.json", maintenance: { mode: "warn", pruneAfter: "30d", maxEntries: 500, resetArchiveRetention: "30d", // duration or false maxDiskBytes: "500mb", // optional highWaterBytes: "400mb", // optional (defaults to 80% of maxDiskBytes) }, typingIntervalSeconds: 5, sendPolicy: { default: "allow", rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], }, }, // Channels 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: { allow: true }, help: { allow: true, requireMention: true }, }, }, }, }, slack: { enabled: true, botToken: "xoxb-REPLACE_ME", appToken: "xapp-REPLACE_ME", channels: { "#general": { allow: true, requireMention: true }, }, dm: { enabled: true, allowFrom: ["U123"] }, slashCommand: { enabled: true, name: "openclaw", sessionPrefix: "slack:slash", ephemeral: true, }, }, }, // Agent runtime 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"], // inherited by agents that omit 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", // allow (default) | block 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", // preferred over legacy 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: "🦥", }, // inherits defaults.skills -> github, weather groupChat: { mentionPatterns: ["@openclaw", "openclaw"], }, thinkingDefault: "high", // per-agent thinking override reasoningDefault: "on", // per-agent reasoning visibility fastModeDefault: false, // per-agent fast mode }, { id: "quick", skills: [], // no skills for this agent fastModeDefault: true, // this agent always runs fast 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: ["[email protected]"], webchat: ["session:demo"], }, }, }, // Custom model providers 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 jobs cron: { enabled: true, store: "~/.openclaw/cron/cron.json", maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution sessionRetention: "24h", runLog: { maxBytes: "2mb", keepLines: 2000, }, }, // Webhooks 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: "From: {{messages[0].from}}\nSubject: {{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: "[email protected]", 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 + networking 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.tailnet: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 }, }, },}Kho kỹ năng anh em được liên kết symlink
Dùng cấu hình này khi thư mục gốc kỹ năng tích hợp sẵn chứa một symlink trỏ vào kho anh em, ví dụ ~/.agents/skills/manager -> ~/Projects/manager/skills.
{ skills: { load: { extraDirs: ["~/Projects/manager/skills"], allowSymlinkTargets: ["~/Projects/manager/skills"], }, },}extraDirsquét kho anh em như một thư mục gốc kỹ năng tường minh.allowSymlinkTargetscho phép các thư mục kỹ năng được liên kết symlink phân giải vào thư mục gốc đích thực đáng tin cậy đó mà không cho phép thoát symlink tùy ý.
Mẫu phổ biến
Đường cơ sở kỹ năng dùng chung với một ghi đè
{ agents: { defaults: { workspace: "~/.openclaw/workspace", skills: ["github", "weather"], }, list: [ { id: "main", default: true }, { id: "docs", workspace: "~/.openclaw/workspace-docs", skills: ["docs-search"] }, ], },}agents.defaults.skillslà đường cơ sở dùng chung.agents.list[].skillsthay thế đường cơ sở đó cho một tác tử.- Dùng
skills: []khi một tác tử không nên thấy kỹ năng nào.
Thiết lập đa nền tảng
{ 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"] }, }, },}Tự động phê duyệt mạng Node đáng tin cậy
Giữ việc ghép đôi thiết bị ở chế độ thủ công trừ khi bạn kiểm soát đường dẫn mạng. Với một lab chuyên dụng hoặc subnet tailnet, bạn có thể chọn bật tự động phê duyệt thiết bị Node lần đầu bằng CIDR hoặc IP chính xác:
{ gateway: { nodes: { pairing: { autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"], }, }, },}Tùy chọn này vẫn tắt khi chưa được thiết lập. Nó chỉ áp dụng cho ghép đôi role: node mới
không có phạm vi được yêu cầu. Máy khách operator/browser và các nâng cấp vai trò, phạm vi,
metadata hoặc khóa công khai vẫn yêu cầu phê duyệt thủ công.
Chế độ DM an toàn (hộp thư đến dùng chung / DM nhiều người dùng)
Nếu nhiều hơn một người có thể DM bot của bạn (nhiều mục trong allowFrom, phê duyệt ghép đôi cho nhiều người, hoặc dmPolicy: "open"), hãy bật chế độ DM an toàn để DM từ các người gửi khác nhau mặc định không dùng chung một ngữ cảnh:
{ // Secure DM mode (recommended for multi-user or sensitive DM agents) session: { dmScope: "per-channel-peer" }, channels: { // Example: WhatsApp multi-user inbox whatsapp: { dmPolicy: "allowlist", allowFrom: ["+15555550123", "+15555550124"], }, // Example: Discord multi-user inbox discord: { enabled: true, token: "YOUR_DISCORD_BOT_TOKEN", dm: { enabled: true, allowFrom: ["123456789012345678", "987654321098765432"] }, }, },}Đối với Discord/Slack/Google Chat/Microsoft Teams/Mattermost/IRC, ủy quyền người gửi mặc định ưu tiên ID.
Chỉ bật khớp tên/email/nick có thể thay đổi trực tiếp bằng dangerouslyAllowNameMatching: true của từng kênh nếu bạn chấp nhận rõ ràng rủi ro đó.
Khóa API Anthropic + phương án dự phòng 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"], }, }, },}Bot công việc (quyền truy cập bị hạn chế)
{ agents: { defaults: { workspace: "~/work-openclaw", elevatedDefault: "off", }, list: [ { id: "main", identity: { name: "WorkBot", theme: "professional assistant", }, }, ], }, channels: { slack: { enabled: true, botToken: "xoxb-...", channels: { "#engineering": { allow: true, requireMention: true }, "#general": { allow: true, requireMention: true }, }, }, },}Chỉ dùng mô hình cục bộ
{ 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, }, ], }, }, },}Mẹo
- Nếu bạn đặt
dmPolicy: "open", danh sáchallowFromtương ứng phải bao gồm"*". - ID nhà cung cấp khác nhau (số điện thoại, ID người dùng, ID kênh). Hãy dùng tài liệu của nhà cung cấp để xác nhận định dạng.
- Các phần tùy chọn có thể thêm sau:
web,browser,ui,discovery,plugins,talk,signal,imessage. - Xem Nhà cung cấp và Khắc phục sự cố để biết ghi chú thiết lập chuyên sâu hơn.