การกำหนดค่า

แต่ละช่องทางมีส่วนการกำหนดค่าของตัวเองภายใต้ 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
• refs ของโมเดลใช้รูปแบบ provider/model (เช่น anthropic/claude-opus-4-6)
• agents.defaults.imageMaxDimensionPx ควบคุมการย่อขนาดรูปภาพใน transcript/tool (ค่าเริ่มต้น 1200); ค่าที่ต่ำกว่ามักลดการใช้ vision-token ในการรันที่มี screenshot จำนวนมาก
• ดู Models CLI สำหรับการสลับโมเดลในแชต และ Model Failover สำหรับการหมุนเวียน auth และพฤติกรรม fallback
• สำหรับ provider แบบกำหนดเอง/โฮสต์เอง ดู Custom providers ในเอกสารอ้างอิง

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

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

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

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

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

{  messages: {    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere    groupChat: {      visibleReplies: "message_tool", // opt-in; visible output requires message(action=send)      unmentionedInbound: "room_event", // unmentioned always-on group chatter is quiet context    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Metadata mentions: native @-mentions (WhatsApp แตะเพื่อ mention, Telegram @bot ฯลฯ)
• Text patterns: รูปแบบ regex ที่ปลอดภัยใน mentionPatterns
• Visible replies: messages.visibleReplies สามารถบังคับให้ส่งผ่าน message-tool ทั่วทั้งระบบ; messages.groupChat.visibleReplies override ค่านั้นสำหรับกลุ่ม/ช่องทาง
• ดู เอกสารอ้างอิงฉบับเต็ม สำหรับโหมด visible reply, override รายช่องทาง และโหมดแชตกับตัวเอง

ใช้ agents.defaults.skills สำหรับ baseline ร่วม แล้ว override agent เฉพาะ ด้วย 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 จะ restart ช่องทางที่ดูเหมือนค้างอย่างเข้มงวดเพียงใด:

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

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

ให้เวลา client ในเครื่องมากขึ้นในการทำ pre-auth WebSocket handshake ให้เสร็จบน โฮสต์ที่มีภาระสูงหรือพลังต่ำ:

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• ค่าเริ่มต้นคือ 15000 มิลลิวินาที
• OPENCLAW_HANDSHAKE_TIMEOUT_MS ยังคงมีลำดับความสำคัญสูงกว่าสำหรับการ override แบบเฉพาะครั้งของ service หรือ shell
• ควรแก้ startup/event-loop stall ก่อน; knob นี้มีไว้สำหรับโฮสต์ที่สุขภาพดีแต่ช้าในช่วง 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)
• ดู การจัดการเซสชัน สำหรับขอบเขต ลิงก์ข้อมูลประจำตัว และนโยบายการส่ง
• ดู ข้อมูลอ้างอิงฉบับเต็ม สำหรับฟิลด์ทั้งหมด

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

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

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

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

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

การปรับใช้ relay แบบกำหนดเองต้องใช้เส้นทางบิลด์/การปรับใช้ iOS ที่แยกออกโดยตั้งใจ ซึ่ง URL ของ relay ตรงกับ URL ของ gateway relay หากคุณใช้บิลด์ relay แบบกำหนดเอง ให้ตั้งค่านี้ในการกำหนดค่า 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 แบบโลคัล/แมนนวลอยู่บน APNs โดยตรง การส่งที่รองรับด้วย relay ใช้เฉพาะกับบิลด์ที่เผยแพร่อย่างเป็นทางการซึ่งลงทะเบียนผ่าน relay
• ต้องตรงกับ URL ฐานของ relay ที่ฝังอยู่ในบิลด์ iOS เพื่อให้ทราฟฟิกการลงทะเบียนและการส่งไปถึงการปรับใช้ relay เดียวกัน

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

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

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

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

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

• OPENCLAW_APNS_RELAY_BASE_URL และ OPENCLAW_APNS_RELAY_TIMEOUT_MS ยังคงใช้งานได้ในฐานะการเขียนทับ env ชั่วคราว
• URL relay ของ Gateway แบบกำหนดเองต้องตรงกับ URL ฐานของ relay ที่ฝังอยู่ในบิลด์ iOS ช่องทางเผยแพร่ App Store สาธารณะจะปฏิเสธการเขียนทับ URL relay ของ iOS แบบกำหนดเอง
• 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: 8, // default; cron dispatch + isolated cron agent-turn execution    sessionRetention: "24h",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },}

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

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

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

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

ดู ข้อมูลอ้างอิงฉบับเต็ม สำหรับตัวเลือกการแมปทั้งหมดและการผสานรวม 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"],  },}

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