การกำหนดค่า

แต่ละช่องทางมีส่วนคอนฟิกของตัวเองภายใต้ 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
• ใช้ 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 สำหรับการหมุนเวียนการยืนยันตัวตนและพฤติกรรม fallback
• สำหรับผู้ให้บริการแบบกำหนดเอง/โฮสต์เอง ดู ผู้ให้บริการแบบกำหนดเอง ในเอกสารอ้างอิง

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

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

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

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

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

{
  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 } },
    },
  },
}

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

ใช้ agents.defaults.skills เป็น baseline ร่วม แล้วแทนที่ 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 จะรีสตาร์ตช่องทางที่ดูเหมือนค้างอย่างเข้มงวดแค่ไหน:

{
  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 เพื่อปิด auto-restarts สำหรับช่องทางหรือบัญชีหนึ่งรายการโดยไม่ปิดตัวตรวจสอบส่วนกลาง
• ดู Health Checks สำหรับการดีบักงานปฏิบัติการ และ เอกสารอ้างอิงฉบับเต็ม สำหรับทุกฟิลด์

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

{
  gateway: {
    handshakeTimeoutMs: 30000,
  },
}

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

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

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

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

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

การพุชที่ใช้ 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 และสิทธิ์การส่ง จากนั้นใช้สำหรับ 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-only เท่านั้น อย่าบันทึก 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 ตามขนาดและจำนวนบรรทัดที่เก็บไว้
• ดูภาพรวมฟีเจอร์และตัวอย่าง CLI ที่ งาน Cron

เปิดใช้ endpoint 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,
      },
    ],
  },
}

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

• ถือว่าเนื้อหา 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 ด้วย เพื่อจำกัดคีย์เซสชันที่ผู้เรียกเลือกได้
• สำหรับ agent ที่ขับเคลื่อนด้วย hook ควรใช้ระดับโมเดลสมัยใหม่ที่แข็งแกร่งและนโยบายเครื่องมือที่เข้มงวด (เช่น เฉพาะการส่งข้อความ พร้อม sandboxing เมื่อทำได้)

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

เรียกใช้ agent ที่แยกอยู่ต่างหากหลายตัวพร้อม 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" } },
  ],
}

ดูกฎการ binding และโปรไฟล์การเข้าถึงราย agent ที่ Multi-Agent และ ข้อมูลอ้างอิงฉบับเต็ม

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

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

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