การกำหนดค่า

แต่ละช่องทางมีส่วนการกำหนดค่าของตัวเองภายใต้ channels.<provider> ดูหน้าช่องทางเฉพาะสำหรับขั้นตอนการตั้งค่า:

• WhatsApp - channels.whatsapp
• Telegram - channels.telegram
• Discord - channels.discord
• Feishu - channels.feishu
• Google Chat - channels.googlechat
• Microsoft Teams - channels.msteams
• Slack - channels.slack
• Signal - channels.signal
• iMessage - channels.imessage
• Mattermost - channels.mattermost

ทุกช่องทางใช้รูปแบบนโยบาย DM เดียวกัน:

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // pairing | allowlist | open | disabled      allowFrom: ["tg:123"], // only for allowlist/open    },  },}

ตั้งค่าโมเดลหลักและ fallback แบบไม่บังคับ:

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

• agents.defaults.models กำหนดแคตตาล็อกโมเดลและทำหน้าที่เป็น allowlist สำหรับ /model; รายการ provider/* จะกรอง /model, /models และตัวเลือกโมเดลให้เหลือ provider ที่เลือกไว้ โดยยังคงใช้การค้นพบโมเดลแบบไดนามิก
• ใช้ openclaw config set agents.defaults.models '<json>' --strict-json --merge เพื่อเพิ่มรายการ allowlist โดยไม่ลบโมเดลที่มีอยู่ การแทนที่แบบธรรมดาที่จะลบรายการจะถูกปฏิเสธ เว้นแต่คุณส่ง --replace
• Model refs ใช้รูปแบบ provider/model (เช่น anthropic/claude-opus-4-6)
• agents.defaults.imageMaxDimensionPx ควบคุมการลดขนาดภาพใน transcript/tool (ค่าเริ่มต้น 1200); ค่าที่ต่ำกว่ามักลดการใช้ vision-token ในการรันที่มีภาพหน้าจอจำนวนมาก
• ดู Models CLI สำหรับการสลับโมเดลในแชต และ Model Failover สำหรับการหมุนเวียน auth และพฤติกรรม fallback
• สำหรับ provider แบบกำหนดเอง/โฮสต์เอง ดู provider แบบกำหนดเอง ในเอกสารอ้างอิง

การเข้าถึง DM ถูกควบคุมต่อช่องทางผ่าน dmPolicy:

• "pairing" (ค่าเริ่มต้น): ผู้ส่งที่ไม่รู้จักจะได้รับรหัส pairing แบบใช้ครั้งเดียวเพื่ออนุมัติ
• "allowlist": เฉพาะผู้ส่งใน allowFrom (หรือ paired allow store)
• "open": อนุญาต DM ขาเข้าทั้งหมด (ต้องมี allowFrom: ["*"])
• "disabled": เพิกเฉยต่อ DM ทั้งหมด

สำหรับกลุ่ม ให้ใช้ groupPolicy + groupAllowFrom หรือ allowlist เฉพาะช่องทาง

ดูเอกสารอ้างอิงฉบับเต็มสำหรับรายละเอียดรายช่องทาง

ข้อความกลุ่มมีค่าเริ่มต้นเป็น ต้องกล่าวถึง กำหนดค่ารูปแบบ trigger ต่อเอเจนต์ และให้การตอบกลับในห้องที่มองเห็นได้อยู่บนพาธเครื่องมือข้อความเริ่มต้น เว้นแต่คุณตั้งใจต้องการการตอบกลับสุดท้ายอัตโนมัติแบบเดิม:

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

• การกล่าวถึงด้วยเมทาดาทา: @-mentions แบบ native (WhatsApp tap-to-mention, Telegram @bot ฯลฯ)
• รูปแบบข้อความ: รูปแบบ regex ที่ปลอดภัยใน mentionPatterns
• การตอบกลับที่มองเห็นได้: messages.visibleReplies สามารถกำหนดให้ใช้การส่งด้วยเครื่องมือข้อความทั่วทั้งระบบ; messages.groupChat.visibleReplies จะแทนที่ค่านั้นสำหรับกลุ่ม/ช่องทาง
• ดูเอกสารอ้างอิงฉบับเต็มสำหรับโหมดการตอบกลับที่มองเห็นได้ การแทนที่รายช่องทาง และโหมด self-chat

ใช้ agents.defaults.skills สำหรับ baseline ที่ใช้ร่วมกัน จากนั้นแทนที่เอเจนต์ เฉพาะด้วย agents.list[].skills:

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // inherits github, weather      { id: "docs", skills: ["docs-search"] }, // replaces defaults      { id: "locked-down", skills: [] }, // no skills    ],  },}

• ละเว้น agents.defaults.skills เพื่อให้ Skills ไม่ถูกจำกัดตามค่าเริ่มต้น
• ละเว้น agents.list[].skills เพื่อสืบทอดค่าเริ่มต้น
• ตั้งค่า agents.list[].skills: [] เพื่อไม่ให้มี Skills
• ดู Skills, การกำหนดค่า Skills และ เอกสารอ้างอิงการกำหนดค่า

ควบคุมว่า Gateway จะรีสตาร์ตช่องทางที่ดูค้างอย่างเข้มงวดแค่ไหน:

{  gateway: {    channelHealthCheckMinutes: 5,    channelStaleEventThresholdMinutes: 30,    channelMaxRestartsPerHour: 10,  },  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• ตั้งค่า gateway.channelHealthCheckMinutes: 0 เพื่อปิดการรีสตาร์ตโดย health-monitor ทั่วทั้งระบบ
• channelStaleEventThresholdMinutes ควรมากกว่าหรือเท่ากับช่วงเวลาการตรวจสอบ
• ใช้ channels.<provider>.healthMonitor.enabled หรือ channels.<provider>.accounts.<id>.healthMonitor.enabled เพื่อปิดการรีสตาร์ตอัตโนมัติสำหรับช่องทางหรือบัญชีหนึ่งรายการโดยไม่ปิดตัวเฝ้าติดตามทั่วทั้งระบบ
• ดู Health Checks สำหรับการดีบักเชิงปฏิบัติการ และเอกสารอ้างอิงฉบับเต็มสำหรับทุกฟิลด์

ให้ไคลเอนต์ local มีเวลามากขึ้นในการทำ pre-auth WebSocket handshake บน โฮสต์ที่โหลดสูงหรือมีกำลังประมวลผลต่ำ:

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• ค่าเริ่มต้นคือ 15000 มิลลิวินาที
• OPENCLAW_HANDSHAKE_TIMEOUT_MS ยังคงมีลำดับความสำคัญสูงกว่าสำหรับการแทนที่ service หรือ shell แบบครั้งเดียว
• ควรแก้ปัญหา startup/event-loop stall ก่อน ปุ่มปรับนี้มีไว้สำหรับโฮสต์ที่สุขภาพดีแต่ช้าระหว่าง warmup

เซสชันควบคุมความต่อเนื่องและการแยกกันของบทสนทนา:

{  session: {    dmScope: "per-channel-peer",  // recommended for multi-user    threadBindings: {      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },    reset: {      mode: "daily",      atHour: 4,      idleMinutes: 120,    },  },}

• dmScope: main (ใช้ร่วมกัน) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings: ค่าเริ่มต้นส่วนกลางสำหรับการกำหนดเส้นทางเซสชันที่ผูกกับเธรด (Discord รองรับ /focus, /unfocus, /agents, /session idle และ /session max-age)
• ดู การจัดการเซสชัน สำหรับขอบเขต ลิงก์ตัวตน และนโยบายการส่ง
• ดู อ้างอิงฉบับเต็ม สำหรับฟิลด์ทั้งหมด

เรียกใช้เซสชันเอเจนต์ในรันไทม์ sandbox ที่แยกออกจากกัน:

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

สร้างอิมเมจก่อน - จาก checkout ซอร์สให้เรียกใช้ scripts/sandbox-setup.sh หรือจากการติดตั้ง npm ให้ดูคำสั่ง docker build แบบ inline ใน Sandboxing § อิมเมจและการตั้งค่า

ดู Sandboxing สำหรับคู่มือฉบับเต็ม และ อ้างอิงฉบับเต็ม สำหรับตัวเลือกทั้งหมด

push ที่มี relay รองรับถูกกำหนดค่าใน openclaw.json

ตั้งค่านี้ในการกำหนดค่า Gateway:

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // Optional. Default: 10000          timeoutMs: 10000,        },      },    },  },}

คำสั่ง CLI ที่เทียบเท่า:

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

สิ่งที่ค่านี้ทำ:

• อนุญาตให้ Gateway ส่ง push.test, การสะกิดให้ตื่น และการปลุกเพื่อเชื่อมต่อใหม่ผ่าน relay ภายนอก
• ใช้สิทธิ์อนุญาตส่งที่อยู่ในขอบเขตการลงทะเบียน ซึ่งส่งต่อโดยแอป iOS ที่จับคู่ไว้ Gateway ไม่จำเป็นต้องมีโทเค็น relay ระดับการปรับใช้ทั้งระบบ
• ผูกการลงทะเบียนแต่ละรายการที่มี relay รองรับกับตัวตน Gateway ที่แอป iOS จับคู่ด้วย เพื่อให้ Gateway อื่นไม่สามารถใช้การลงทะเบียนที่จัดเก็บไว้ซ้ำได้
• คงบิลด์ iOS แบบ local/manual ไว้บน APNs โดยตรง การส่งที่มี relay รองรับจะใช้เฉพาะกับบิลด์ที่แจกจ่ายอย่างเป็นทางการซึ่งลงทะเบียนผ่าน relay เท่านั้น
• ต้องตรงกับ URL ฐานของ relay ที่ฝังอยู่ในบิลด์ iOS อย่างเป็นทางการ/TestFlight เพื่อให้ทราฟฟิกการลงทะเบียนและการส่งไปถึงการปรับใช้ relay เดียวกัน

โฟลว์ตั้งแต่ต้นจนจบ:

1. ติดตั้งบิลด์ iOS อย่างเป็นทางการ/TestFlight ที่คอมไพล์ด้วย URL ฐานของ relay เดียวกัน
2. กำหนดค่า gateway.push.apns.relay.baseUrl บน Gateway
3. จับคู่แอป iOS กับ Gateway และให้ทั้งเซสชัน node และ operator เชื่อมต่อ
4. แอป iOS ดึงตัวตน Gateway, ลงทะเบียนกับ relay โดยใช้ App Attest พร้อมใบเสร็จของแอป แล้วเผยแพร่ payload push.apns.register ที่มี relay รองรับไปยัง Gateway ที่จับคู่ไว้
5. Gateway จัดเก็บ relay handle และสิทธิ์อนุญาตส่ง จากนั้นใช้สำหรับ push.test, การสะกิดให้ตื่น และการปลุกเพื่อเชื่อมต่อใหม่

หมายเหตุด้านการปฏิบัติงาน:

• หากคุณสลับแอป iOS ไปยัง Gateway อื่น ให้เชื่อมต่อแอปใหม่เพื่อให้แอปเผยแพร่การลงทะเบียน relay ใหม่ที่ผูกกับ Gateway นั้นได้
• หากคุณส่งบิลด์ iOS ใหม่ที่ชี้ไปยังการปรับใช้ relay อื่น แอปจะรีเฟรชการลงทะเบียน relay ที่แคชไว้แทนการใช้ต้นทาง relay เดิมซ้ำ

หมายเหตุด้านความเข้ากันได้:

• OPENCLAW_APNS_RELAY_BASE_URL และ OPENCLAW_APNS_RELAY_TIMEOUT_MS ยังใช้งานได้เป็นการ override ผ่าน env ชั่วคราว
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true ยังคงเป็นช่องทางหลบสำหรับการพัฒนาแบบ loopback เท่านั้น อย่าบันทึก URL relay แบบ HTTP ไว้ในการกำหนดค่า

ดู แอป iOS สำหรับโฟลว์ตั้งแต่ต้นจนจบ และ โฟลว์การยืนยันตัวตนและความไว้วางใจ สำหรับโมเดลความปลอดภัยของ relay

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

• every: สตริงระยะเวลา (30m, 2h) ตั้งค่าเป็น 0m เพื่อปิดใช้งาน
• target: last | none | <channel-id> (ตัวอย่างเช่น discord, matrix, telegram หรือ whatsapp)
• directPolicy: allow (ค่าเริ่มต้น) หรือ block สำหรับเป้าหมาย Heartbeat แบบ DM
• ดู Heartbeat สำหรับคู่มือฉบับเต็ม

{  cron: {    enabled: true,    maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution    sessionRetention: "24h",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },}

• sessionRetention: ล้างเซสชันการรันแบบแยกที่เสร็จแล้วออกจาก sessions.json (ค่าเริ่มต้น 24h; ตั้งค่าเป็น false เพื่อปิดใช้งาน)
• runLog: ล้าง cron/runs/<jobId>.jsonl ตามขนาดและจำนวนบรรทัดที่คงไว้
• ดู งาน Cron สำหรับภาพรวมฟีเจอร์และตัวอย่าง CLI

เปิดใช้งาน endpoint HTTP Webhook บน Gateway:

{  hooks: {    enabled: true,    token: "shared-secret",    path: "/hooks",    defaultSessionKey: "hook:ingress",    allowRequestSessionKey: false,    allowedSessionKeyPrefixes: ["hook:"],    mappings: [      {        match: { path: "gmail" },        action: "agent",        agentId: "main",        deliver: true,      },    ],  },}

หมายเหตุด้านความปลอดภัย:

• ถือว่าเนื้อหา payload ของ hook/webhook ทั้งหมดเป็นอินพุตที่ไม่น่าเชื่อถือ
• ใช้ hooks.token เฉพาะ อย่านำโทเค็น Gateway ที่ใช้ร่วมกันมาใช้ซ้ำ
• การยืนยันตัวตนของ hook ใช้เฉพาะ header (Authorization: Bearer ... หรือ x-openclaw-token); โทเค็นใน query string จะถูกปฏิเสธ
• hooks.path ไม่สามารถเป็น / ได้ ให้เก็บทางเข้า webhook ไว้ใน subpath เฉพาะ เช่น /hooks
• ปิดแฟล็กข้ามเนื้อหาที่ไม่ปลอดภัยไว้ (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) เว้นแต่จะดีบักในขอบเขตที่จำกัดอย่างเข้มงวด
• หากคุณเปิดใช้ hooks.allowRequestSessionKey ให้ตั้งค่า hooks.allowedSessionKeyPrefixes ด้วย เพื่อจำกัดคีย์เซสชันที่ผู้เรียกเลือกได้
• สำหรับเอเจนต์ที่ขับเคลื่อนด้วย hook ให้ใช้ tier โมเดลสมัยใหม่ที่แข็งแรงและนโยบายเครื่องมือที่เข้มงวดเป็นหลัก (เช่น อนุญาตเฉพาะการส่งข้อความ พร้อม sandboxing เมื่อเป็นไปได้)

ดู อ้างอิงฉบับเต็ม สำหรับตัวเลือก mapping ทั้งหมดและการเชื่อมต่อ Gmail

เรียกใช้เอเจนต์ที่แยกออกจากกันหลายตัว โดยมี workspace และเซสชันแยกกัน:

{  agents: {    list: [      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },      { id: "work", workspace: "~/.openclaw/workspace-work" },    ],  },  bindings: [    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },  ],}

ดู หลายเอเจนต์ และ อ้างอิงฉบับเต็ม สำหรับกฎการผูกและโปรไฟล์การเข้าถึงรายเอเจนต์

ใช้ $include เพื่อจัดระเบียบ config ขนาดใหญ่:

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

• ไฟล์เดียว: แทนที่ object ที่ครอบอยู่
• อาร์เรย์ของไฟล์: deep-merge ตามลำดับ (รายการหลังชนะ)
• คีย์ข้างเคียง: merge หลัง includes (override ค่าที่ include มา)
• include ซ้อนกัน: รองรับได้ลึกสูงสุด 10 ระดับ
• พาธสัมพัทธ์: resolve โดยอิงจากไฟล์ที่ include
• การเขียนที่ OpenClaw เป็นเจ้าของ: เมื่อการเขียนเปลี่ยนเฉพาะส่วน top-level หนึ่งส่วน ที่รองรับด้วย single-file include เช่น plugins: { $include: "./plugins.json5" }, OpenClaw จะอัปเดตไฟล์ที่ include นั้น และปล่อย openclaw.json ไว้เหมือนเดิม
• write-through ที่ไม่รองรับ: root includes, include arrays และ includes ที่มี sibling overrides จะ fail closed สำหรับการเขียนที่ OpenClaw เป็นเจ้าของ แทนที่จะ flatten config
• การจำกัดขอบเขต: พาธ $include ต้อง resolve อยู่ภายใต้ไดเรกทอรีที่มี openclaw.json หากต้องการแชร์ tree ระหว่างเครื่องหรือผู้ใช้ ให้ตั้งค่า OPENCLAW_INCLUDE_ROOTS เป็น path-list (: บน POSIX, ; บน Windows) ของ ไดเรกทอรีเพิ่มเติมที่ includes อาจอ้างอิงได้ Symlink จะถูก resolve และตรวจสอบซ้ำ ดังนั้นพาธที่ตามตัวอักษรอยู่ใน config dir แต่ target จริง หลุดออกจาก root ที่อนุญาตทั้งหมดจะยังคงถูกปฏิเสธ
• การจัดการข้อผิดพลาด: ข้อผิดพลาดที่ชัดเจนสำหรับไฟล์ที่หายไป ข้อผิดพลาดในการ parse และ circular includes