การกำหนดค่า

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

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

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

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

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

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

{  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: @-mentions แบบ native (WhatsApp tap-to-mention, Telegram @bot ฯลฯ)
• Text patterns: รูปแบบ regex ที่ปลอดภัยใน mentionPatterns
• Visible replies: messages.visibleReplies สามารถบังคับให้ส่งด้วย message-tool ทั่วทั้งระบบ; messages.groupChat.visibleReplies แทนที่ค่านั้นสำหรับกลุ่ม/ช่องทาง
• ดู ข้อมูลอ้างอิงฉบับเต็ม สำหรับโหมด visible reply การแทนที่ต่อช่องทาง และโหมด 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 เพื่อปิดการรีสตาร์ตอัตโนมัติสำหรับหนึ่งช่องทางหรือบัญชี โดยไม่ปิด monitor ส่วนกลาง
• ดู Health Checks สำหรับการดีบักเชิงปฏิบัติการ และ ข้อมูลอ้างอิงฉบับเต็ม สำหรับทุกฟิลด์

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

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• ค่าเริ่มต้นคือ 15000 มิลลิวินาที
• OPENCLAW_HANDSHAKE_TIMEOUT_MS ยังคงมีลำดับความสำคัญสูงกว่าสำหรับการ override บริการหรือ shell แบบครั้งเดียว
• ควรแก้การค้างของ startup/event-loop ก่อน 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 แบบอินไลน์ใน แซนด์บ็อกซ์ § อิมเมจและการตั้งค่า

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

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

การปรับใช้รีเลย์แบบกำหนดเองต้องใช้เส้นทางบิลด์/ปรับใช้ iOS ที่แยกอย่างตั้งใจ ซึ่ง URL รีเลย์ตรงกับ URL รีเลย์ของ Gateway หากคุณใช้บิลด์รีเลย์แบบกำหนดเอง ให้ตั้งค่านี้ในการกำหนดค่า 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, การสะกิดปลุก และการปลุกเพื่อเชื่อมต่อใหม่ผ่านรีเลย์ภายนอกได้
• ใช้สิทธิ์ส่งที่จำกัดตามการลงทะเบียนซึ่งส่งต่อโดยแอป iOS ที่จับคู่ไว้ Gateway ไม่จำเป็นต้องมีโทเค็นรีเลย์ระดับการปรับใช้ทั้งหมด
• ผูกการลงทะเบียนที่มีรีเลย์รองรับแต่ละรายการกับตัวตนของ Gateway ที่แอป iOS จับคู่ไว้ เพื่อไม่ให้ Gateway อื่นใช้การลงทะเบียนที่จัดเก็บไว้ซ้ำได้
• คงบิลด์ iOS แบบ local/แมนนวลไว้บน 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 ยังใช้งานได้เป็นการแทนที่ผ่าน env ชั่วคราว
• URL รีเลย์ Gateway แบบกำหนดเองต้องตรงกับ URL ฐานของรีเลย์ที่ฝังไว้ในบิลด์ iOS ช่องทางเผยแพร่ App Store สาธารณะจะปฏิเสธการแทนที่ URL รีเลย์ iOS แบบกำหนดเอง
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true ยังคงเป็นช่องทางเลี่ยงสำหรับการพัฒนาแบบ loopback เท่านั้น อย่าคง URL รีเลย์ HTTP ไว้ในการกำหนดค่า

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

{  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); โทเค็นใน query string จะถูกปฏิเสธ
• hooks.path เป็น / ไม่ได้ ให้คงทางเข้า Webhook ไว้บนพาธย่อยเฉพาะ เช่น /hooks
• ปิดแฟล็กข้ามเนื้อหาที่ไม่ปลอดภัยไว้ (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) เว้นแต่กำลังดีบักในขอบเขตที่จำกัดมาก
• หากคุณเปิดใช้ hooks.allowRequestSessionKey ให้ตั้งค่า hooks.allowedSessionKeyPrefixes ด้วย เพื่อจำกัดคีย์เซสชันที่ผู้เรียกเลือกได้
• สำหรับตัวแทนที่ขับเคลื่อนด้วย hook ให้เลือกเทียร์โมเดลสมัยใหม่ที่แข็งแกร่งและนโยบายเครื่องมือที่เข้มงวด (เช่น เฉพาะการส่งข้อความบวกกับแซนด์บ็อกซ์เมื่อทำได้)

ดู เอกสารอ้างอิงฉบับเต็ม สำหรับตัวเลือกการแมปทั้งหมดและการผสานรวม 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 เป็นเจ้าของ แทนที่จะ flatten การกำหนดค่า
• การจำกัดขอบเขต: พาธ $include ต้องแก้พาธไปอยู่ใต้ไดเรกทอรีที่เก็บ openclaw.json หากต้องการแชร์ทรีข้ามเครื่องหรือผู้ใช้ ให้ตั้งค่า OPENCLAW_INCLUDE_ROOTS เป็นรายการพาธ (: บน POSIX, ; บน Windows) ของ ไดเรกทอรีเพิ่มเติมที่ include อ้างอิงได้ Symlink จะถูกแก้พาธ และตรวจสอบซ้ำ ดังนั้นพาธที่ตามตัวอักษรอยู่ในไดเรกทอรี config แต่เป้าหมายจริง หลุดออกจาก root ที่อนุญาตทุกตัวก็ยังถูกปฏิเสธ
• การจัดการข้อผิดพลาด: ข้อผิดพลาดที่ชัดเจนสำหรับไฟล์ที่หายไป ข้อผิดพลาดการพาร์ส include แบบวงกลม รูปแบบพาธไม่ถูกต้อง และความยาวเกินกำหนด