การกำหนดค่า

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

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

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

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // การจับคู่ | รายการอนุญาต | เปิด | ปิดใช้งาน      allowFrom: ["tg:123"], // สำหรับรายการอนุญาต/เปิดเท่านั้น    },  },}

ตั้งค่าโมเดลหลักและโมเดลสำรองที่เป็นทางเลือก:

{  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 เก็บนามแฝงและการตั้งค่าแต่ละโมเดล การเพิ่มรายการจะไม่จำกัดการแทนที่ /model หรือ --model
• agents.defaults.modelPolicy.allow คือรายการอนุญาตอย่างชัดเจนสำหรับการแทนที่และตัวเลือกโมเดล โดยรับการอ้างอิงแบบตรงทั้งหมดและ wildcard provider/* หากไม่ระบุหรือใช้ [] จะอนุญาตทุกโมเดล
• การอ้างอิงโมเดลใช้รูปแบบ provider/model (เช่น anthropic/claude-opus-4-6)
• agents.defaults.imageMaxDimensionPx ควบคุมการลดขนาดรูปภาพในบทถอดความ/เครื่องมือ (ค่าเริ่มต้น 1200) โดยทั่วไปค่าที่ต่ำกว่าจะลดการใช้โทเค็นภาพในการทำงานที่มีภาพหน้าจอจำนวนมาก
• ดู CLI สำหรับโมเดล สำหรับการสลับโมเดลในแชต และการสลับใช้โมเดลเมื่อขัดข้อง สำหรับการหมุนเวียนข้อมูลรับรองการยืนยันตัวตนและพฤติกรรมการสำรอง
• สำหรับผู้ให้บริการแบบกำหนดเอง/โฮสต์เอง ดูผู้ให้บริการแบบกำหนดเอง ในเอกสารอ้างอิง

การเข้าถึง DM ถูกควบคุมแยกตามช่องทางผ่าน dmPolicy (ค่าเริ่มต้น "pairing"):

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

สำหรับกลุ่ม ให้ใช้ groupPolicy ("allowlist" | "open" | "disabled") ร่วมกับ groupAllowFrom หรือรายการอนุญาตเฉพาะช่องทาง

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

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

{  messages: {    visibleReplies: "automatic", // ตั้งเป็น "message_tool" เพื่อบังคับให้ส่งผ่านเครื่องมือส่งข้อความทุกที่    groupChat: {      visibleReplies: "message_tool", // เลือกใช้; เอาต์พุตที่มองเห็นได้ต้องใช้ message(action=send)      unmentionedInbound: "room_event", // บทสนทนากลุ่มที่เปิดตลอดและไม่กล่าวถึงจะเป็นบริบทแบบเงียบ    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

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

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

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // สืบทอด github, weather      { id: "docs", skills: ["docs-search"] }, // แทนที่ค่าเริ่มต้น      { id: "locked-down", skills: [] }, // ไม่มี Skills    ],  },}

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

ปิดหรือเปิดการรีสตาร์ตสถานะอัตโนมัติสำหรับช่องทางหรือบัญชี:

{  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

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

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

{  session: {    dmScope: "per-channel-peer",  // แนะนำสำหรับผู้ใช้หลายคน    threadBindings: {      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },    reset: {      mode: "daily",      atHour: 4,      idleMinutes: 120,    },  },}

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

เรียกใช้เซสชันของเอเจนต์ในรันไทม์แซนด์บ็อกซ์ที่แยกออกจากกัน:

{  agents: {    defaults: {      sandbox: {        mode: "non-main",  // ปิด | ไม่ใช่เซสชันหลัก | ทั้งหมด        scope: "agent",    // เซสชัน | เอเจนต์ | ใช้ร่วมกัน      },    },  },}

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

ดูคู่มือฉบับเต็มได้ที่ แซนด์บ็อกซ์ และดูตัวเลือกทั้งหมดได้ที่ ข้อมูลอ้างอิงฉบับเต็ม

พุชที่มีรีเลย์รองรับสำหรับบิลด์ App Store สาธารณะใช้รีเลย์ OpenClaw ที่โฮสต์ไว้: https://ios-push-relay.openclaw.ai

การติดตั้งใช้งานรีเลย์แบบกำหนดเองต้องมีเส้นทางการบิลด์/ติดตั้งใช้งาน iOS ที่จงใจแยกออกมาต่างหาก โดย URL ของรีเลย์ต้องตรงกับ URL รีเลย์ของ Gateway หากใช้บิลด์รีเลย์แบบกำหนดเอง ให้ตั้งค่านี้ในการกำหนดค่า Gateway:

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // ไม่บังคับ ค่าเริ่มต้น: 10000          timeoutMs: 10000,        },      },    },  },}

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

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

การทำงานของการตั้งค่านี้:

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

ขั้นตอนการทำงานตั้งแต่ต้นจนจบ:

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

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

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

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

• OPENCLAW_APNS_RELAY_BASE_URL และ OPENCLAW_APNS_RELAY_TIMEOUT_MS ยังคงใช้เป็นการแทนที่ชั่วคราวผ่านตัวแปรสภาพแวดล้อมได้
• URL รีเลย์แบบกำหนดเองของ Gateway ต้องตรงกับ URL ฐานของรีเลย์ที่ฝังอยู่ในบิลด์ iOS โดยช่องทางเผยแพร่ App Store สาธารณะจะปฏิเสธการแทนที่ URL รีเลย์ iOS แบบกำหนดเอง
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true ยังคงเป็นช่องทางหลีกเลี่ยงสำหรับการพัฒนาที่ใช้ได้เฉพาะลูปแบ็กเท่านั้น ห้ามบันทึก URL รีเลย์แบบ HTTP ไว้ในการกำหนดค่า

ดูขั้นตอนการทำงานตั้งแต่ต้นจนจบได้ที่ แอป iOS และดูโมเดลความปลอดภัยของรีเลย์ได้ที่ ขั้นตอนการยืนยันตัวตนและความเชื่อถือ

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

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

{  cron: {    enabled: true,    sessionRetention: "24h",  },}

• sessionRetention: ล้างเซสชันการเรียกใช้แบบแยกที่เสร็จสมบูรณ์แล้วออกจากแถวเซสชัน SQLite (ค่าเริ่มต้น 24h; ตั้งค่า false เพื่อปิดใช้)
• ประวัติการเรียกใช้จะเก็บแถวเทอร์มินัลใหม่ล่าสุด 2000 แถวต่องานโดยอัตโนมัติ ส่วนแถวที่สูญหายยังคงมีกรอบเวลาล้างข้อมูล 24 ชั่วโมง
• ดูภาพรวมฟีเจอร์และตัวอย่าง CLI ได้ที่ งาน Cron

เปิดใช้ปลายทาง Webhook แบบ HTTP บน 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,      },    ],  },}

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

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

ดูตัวเลือกการแมปทั้งหมดและการผสานรวม Gmail ได้ที่ ข้อมูลอ้างอิงฉบับเต็ม

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

{  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 เพื่อจัดระเบียบการกำหนดค่าขนาดใหญ่:

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

• ไฟล์เดียว: แทนที่ออบเจ็กต์ที่ครอบอยู่
• อาร์เรย์ของไฟล์: ผสานแบบลึกตามลำดับ (รายการหลังมีผลเหนือกว่า) ซ้อนได้ลึกสูงสุด 10 ระดับ
• คีย์ระดับเดียวกัน: ผสานหลังการรวมไฟล์ (แทนที่ค่าจากไฟล์ที่รวม)
• พาธสัมพัทธ์: แก้พาธโดยอ้างอิงจากไฟล์ที่ทำการรวม
• รูปแบบพาธ: พาธที่รวมต้องไม่มีไบต์ null และต้องสั้นกว่า 4096 อักขระอย่างเคร่งครัด ทั้งก่อนและหลังการแก้พาธ
• การเขียนที่ OpenClaw เป็นเจ้าของ: เมื่อการเขียนเปลี่ยนแปลงเฉพาะส่วนระดับบนสุดเพียงส่วนเดียว ซึ่งมีไฟล์ที่รวมแบบไฟล์เดียวรองรับ เช่น plugins: { $include: "./plugins.json5" } OpenClaw จะอัปเดตไฟล์ที่รวมดังกล่าวและคง openclaw.json ไว้ดังเดิม
• ไม่รองรับการเขียนส่งผ่าน: การรวมที่ระดับราก อาร์เรย์ของไฟล์ที่รวม และการรวม ที่มีการแทนที่ด้วยคีย์ระดับเดียวกัน จะปฏิเสธการเขียนที่ OpenClaw เป็นเจ้าของอย่างปลอดภัย แทนการแผ่การกำหนดค่าให้อยู่ในไฟล์เดียว
• การจำกัดขอบเขต: พาธ $include ต้องแก้ไปยังตำแหน่งภายใต้ไดเรกทอรีที่เก็บ openclaw.json หากต้องการใช้โครงสร้างไดเรกทอรีร่วมกันระหว่างเครื่องหรือผู้ใช้ ให้ตั้งค่า OPENCLAW_INCLUDE_ROOTS เป็นรายการพาธ (: บน POSIX, ; บน Windows) ของ ไดเรกทอรีเพิ่มเติมที่ไฟล์รวมสามารถอ้างอิงได้ ระบบจะแก้ symlink และตรวจสอบอีกครั้ง ดังนั้นพาธที่ในเชิงข้อความอยู่ภายในไดเรกทอรีการกำหนดค่า แต่มี เป้าหมายจริงอยู่นอกรากที่อนุญาตทั้งหมดจะยังคงถูกปฏิเสธ
• การจัดการข้อผิดพลาด: แสดงข้อผิดพลาดอย่างชัดเจนเมื่อไฟล์หาย การแยกวิเคราะห์ผิดพลาด การรวมเป็นวงกลม รูปแบบพาธไม่ถูกต้อง และความยาวเกินกำหนด