Hello Claw: คู่มือเริ่มต้น OpenClaw

#ภาคผนวก B: คำอธิบายโดยละเอียดของไฟล์การกำหนดค่า

ระบบการกำหนดค่าของ OpenClaw มีความยืดหยุ่นและทรงพลัง ภาคผนวกนี้จะวิเคราะห์แต่ละรายการการกำหนดค่าโดยละเอียดตามเอกสารอย่างเป็นทางการ

แหล่งอ้างอิง: OpenClaw Configuration

ตำแหน่งไฟล์การกำหนดค่า

OpenClaw อ่านไฟล์การกำหนดค่าเสริม JSON5:

~/.openclaw/openclaw.json          # 主配置文件
~/.openclaw/.env                   # 环境变量文件

หากไม่มีไฟล์การกำหนดค่า OpenClaw จะใช้ค่าเริ่มต้นที่ปลอดภัย

ภาพรวมโครงสร้างไฟล์การกำหนดค่า

json5

{
  agents: { ... },           // Agent 配置
  channels: { ... },         // 渠道配置
  gateway: { ... },          // 网关配置
  session: { ... },          // 会话配置
  messages: { ... },         // 消息配置
  tools: { ... },            // 工具配置
  skills: { ... },           // 技能配置
  cron: { ... },             // 定时任务配置
  hooks: { ... },            // Webhook 配置
  bindings: [...],           // 绑定规则
  env: { ... },              // 环境变量
}

1. การกำหนดค่าตัวแทน (ตัวแทน)

1.1 การกำหนดค่าเริ่มต้น (agents.defaults)

json5

{
  agents: {
    defaults: {
      // 工作空间路径
      workspace: "~/.openclaw/workspace",
      
      // 模型配置
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"]
      },
      
      // 模型目录（用于 /model 命令）
      models: {
        "anthropic/claude-sonnet-4-5": {
          alias: "Sonnet"
        },
        "openai/gpt-5.2": {
          alias: "GPT"
        }
      },
      
      // 图片最大尺寸（像素）
      imageMaxDimensionPx: 1200,
      
      // 心跳配置
      heartbeat: {
        every: "30m",        // 30分钟、2小时等
        target: "last",      // last | whatsapp | telegram | discord | none
        directPolicy: "allow" // allow | block
      },
      
      // 沙盒配置
      sandbox: {
        mode: "non-main",    // off | non-main | all
        scope: "agent"       // session | agent | shared
      },
      
      // 工具配置
      tools: {
        enabled: true,
        profile: "full"
      }
    }
  }
}

คำอธิบายรายการการกำหนดค่า:

รายการการกำหนดค่า	พิมพ์	ค่าเริ่มต้น	คำอธิบาย
`workspace`	สตริง	~/.openclaw/พื้นที่ทำงาน	ไดเร็กทอรีการทำงานของตัวแทน
`model.primary`	สตริง	-	โมเดลหลัก รูปแบบ: ผู้ให้บริการ/โมเดล
`model.fallbacks`	อาร์เรย์	[]	รายการโมเดลสำรอง
`imageMaxDimensionPx`	หมายเลข	1200	การถอดความรูปภาพ/เครื่องมือ ขนาดการซูมภาพ
`heartbeat.every`	สตริง	-	ช่วงเวลาการเต้นของหัวใจ (เช่น 30 นาที 2 ชั่วโมง)
`sandbox.mode`	สตริง	ปิด	โหมดแซนด์บ็อกซ์

1.2 การกำหนดค่าหลายตัวแทน (agents.list)

json5

{
  agents: {
    list: [
      {
        id: "home",
        default: true,
        workspace: "~/.openclaw/workspace-home",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"]
        }
      },
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work",
        model: {
          primary: "anthropic/claude-opus-4-6"
        }
      }
    ]
  }
}

2. การกำหนดค่าช่อง (ช่อง)

2.1 การกำหนดค่านโยบาย DM ทั่วไป

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

json5

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",      // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"],    // 仅用于 allowlist/open
    },
    
    whatsapp: {
      enabled: true,
      allowFrom: ["+15555550123"],
      groups: {
        "*": {
          requireMention: true
        }
      }
    },
    
    discord: {
      enabled: true,
      botToken: "${DISCORD_BOT_TOKEN}",
      dmPolicy: "pairing",
      allowFrom: ["discord:123"]
    },
    
    slack: {
      enabled: true,
      botToken: "${SLACK_BOT_TOKEN}",
      dmPolicy: "pairing"
    }
  }
}

ตัวเลือกนโยบาย DM:

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

2.2 แชทกลุ่มพูดถึงการควบคุมประตู

json5

{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"]
        }
      }
    ]
  },
  
  channels: {
    whatsapp: {
      groups: {
        "*": {
          requireMention: true
        }
      }
    }
  }
}

3. การกำหนดค่าเกตเวย์ (เกตเวย์)

json5

{
  gateway: {
    port: 18789,
    bind: "loopback",           // loopback | lan | tailnet | auto | custom
    auth: {
      mode: "token",            // token | password
      token: "${OPENCLAW_GATEWAY_TOKEN}",
      password: "${OPENCLAW_GATEWAY_PASSWORD}",
      allowTailscale: true
    },
    tailscale: {
      mode: "off",              // off | serve | funnel
      resetOnExit: false
    },
    reload: {
      mode: "hybrid",           // hybrid | hot | restart | off
      debounceMs: 300
    }
  }
}

ตัวเลือกที่อยู่ผูก:

ค่า	คำอธิบาย
`loopback`	การเข้าถึงในพื้นที่เท่านั้น (127.0.0.1)
`lan`	LAN เข้าถึงได้
`tailnet`	เครือข่าย Tailscale
`auto`	การตรวจจับอัตโนมัติ
`custom`	ที่อยู่ที่กำหนดเอง

โหมดรีโหลดด่วน:

รูปแบบ	พฤติกรรม
`hybrid`	ใช้การเปลี่ยนแปลงที่ปลอดภัย รีสตาร์ทการเปลี่ยนแปลงที่สำคัญโดยอัตโนมัติ (ค่าเริ่มต้น)
`hot`	เฉพาะการเปลี่ยนแปลงที่ปลอดภัยแบบ hot-ใช้ บันทึกคำเตือนหากจำเป็นต้องรีสตาร์ท
`restart`	รีสตาร์ทเกตเวย์สำหรับการเปลี่ยนแปลงการกำหนดค่า
`off`	ปิดการใช้งานการตรวจสอบไฟล์

4. การกำหนดค่าเซสชัน (เซสชัน)

json5

{
  session: {
    dmScope: "per-channel-peer",  // main | per-peer | per-channel-peer | per-account-channel-peer
    
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0
    },
    
    reset: {
      mode: "daily",            // daily | idle | manual
      atHour: 4,
      idleMinutes: 120
    }
  }
}

ตัวเลือกขอบเขต DM:

ค่า	คำอธิบาย
`main`	เซสชันที่แชร์
`per-peer`	เซสชันอิสระต่อเพียร์
`per-channel-peer`	ต่อช่อง - เซสชันอิสระถึงเพื่อน (แนะนำผู้ใช้หลายคน)
`per-account-channel-peer`	เซสชันอิสระต่อบัญชี-ช่องทาง-เพียร์

5. การกำหนดค่าข้อความ (ข้อความ)

json5

{
  messages: {
    groupChat: {
      mentionPatterns: ["@openclaw"]
    }
  }
}

6. การกำหนดค่าเครื่องมือ (เครื่องมือ)

json5

{
  tools: {
    profile: "full",              // messaging | default | coding | full | all
    enabled: true,
    web: {
      search: {
        apiKey: "${BRAVE_API_KEY}"
      }
    }
  }
}

ไฟล์การกำหนดค่าเครื่องมือ:

ข้อมูลส่วนตัว	คำอธิบาย
`messaging`	แชทเท่านั้น ไม่มีเครื่องมือ
`default`	ชุดเครื่องมือพื้นฐาน
`coding`	ชุดเครื่องมือการเขียนโปรแกรม
`full`	ชุดเครื่องมือครบชุด
`all`	เครื่องมือทั้งหมด

7. การกำหนดค่าทักษะ (ทักษะ)

json5

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/nano-banana-pro/apiKey"
        }
      }
    }
  }
}

8. การกำหนดค่างานที่กำหนดเวลาไว้ (cron)

json5

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000
    }
  }
}

9. การกำหนดค่า Webhook (hooks)

json5

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

10. การกำหนดค่าการผูก (การผูก)

json5

{
  bindings: [
    {
      agentId: "home",
      match: {
        channel: "whatsapp",
        accountId: "personal"
      }
    },
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "biz"
      }
    }
  ]
}

11. การกำหนดค่าตัวแปรสภาพแวดล้อม (env)

json5

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-..."
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000
    }
  }
}

แหล่งที่มาของตัวแปรสภาพแวดล้อม (ตามลำดับความสำคัญ):

ตัวแปรสภาพแวดล้อมกระบวนการหลัก
ไฟล์ .env ในไดเร็กทอรีการทำงานปัจจุบัน
ไฟล์ ~/.openclaw/.env (ทางเลือกทั่วโลก)

ไม่มีการเขียนทับตัวแปรสภาพแวดล้อมที่มีอยู่

12. การแยกการกำหนดค่า ($รวม)

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

json5

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

กติกา:

ไฟล์เดียว: แทนที่วัตถุที่มีอยู่
อาร์เรย์ไฟล์: ผสานลึกตามลำดับ (ล่าสุดก่อน)
คีย์พี่น้อง: ผสานหลังจากรวม (เขียนทับค่าที่รวมไว้)
ซ้อนรวม: รองรับความลึกได้ถึง 10 ระดับ
เส้นทางสัมพัทธ์: แก้ไขโดยสัมพันธ์กับไฟล์ที่มีอยู่

13. การแทนที่ตัวแปรสภาพแวดล้อม

อ้างอิงตัวแปรสภาพแวดล้อมในค่าสตริงการกำหนดค่า:

json5

{
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    }
  },
  models: {
    providers: {
      custom: {
        apiKey: "${CUSTOM_API_KEY}"
      }
    }
  }
}

กติกา:

จับคู่เฉพาะชื่อตัวพิมพ์ใหญ่เท่านั้น: [A-Z_][A-Z0-9_]*
ตัวแปรที่หายไป/ว่างเปล่าทำให้เกิดข้อผิดพลาดขณะโหลด
ใช้ $${VAR} เพื่อหลบหนีไปยังเอาต์พุตตามตัวอักษร
ใช้ได้กับไฟล์ $include ด้วย
การแทนที่แบบอินไลน์: "${BASE}/v1" → "https://api.example.com/v1"

14. ใบรับรอง SecretRef

ฟิลด์ที่รองรับของออบเจ็กต์ SecretRef:

json5

{
  models: {
    providers: {
      openai: {
        apiKey: {
          source: "env",
          provider: "default",
          id: "OPENAI_API_KEY"
        }
      }
    }
  },
  
  skills: {
    entries: {
      "nano-banana-pro": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/nano-banana-pro/apiKey"
        }
      }
    }
  },
  
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount"
      }
    }
  }
}

ประเภทแหล่งที่มา:

env: ตัวแปรสภาพแวดล้อม
file: เนื้อหาไฟล์
exec: เอาต์พุตการดำเนินการคำสั่ง

15. ตัวอย่างการกำหนดค่าที่สมบูรณ์

15.1 การกำหนดค่าขั้นต่ำ

json5

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace"
    }
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"]
    }
  }
}

15.2 การกำหนดค่าการพัฒนาท้องถิ่น

json5

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "ollama/llama3.2"
      }
    }
  },
  gateway: {
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token",
      token: "dev-token"
    }
  }
}

15.3 การกำหนดค่าการปรับใช้เซิร์ฟเวอร์

json5

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"]
      }
    }
  },
  
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing"
    }
  },
  
  gateway: {
    port: 18789,
    bind: "lan",
    auth: {
      mode: "password",
      password: "${GATEWAY_PASSWORD}"
    }
  },
  
  session: {
    dmScope: "per-channel-peer"
  }
}

15.4 การกำหนดค่าหลายตัวแทน

json5

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5"
      }
    },
    list: [
      {
        id: "home",
        default: true,
        workspace: "~/.openclaw/workspace-home"
      },
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work",
        model: {
          primary: "anthropic/claude-opus-4-6"
        }
      }
    ]
  },
  
  bindings: [
    {
      agentId: "home",
      match: {
        channel: "whatsapp",
        accountId: "personal"
      }
    },
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "biz"
      }
    }
  ]
}

16. วิธีการแก้ไขการกำหนดค่า

ตัวช่วยสร้างแบบโต้ตอบ

bash

openclaw onboard          # 完整设置向导
openclaw configure        # 配置向导

คำสั่ง CLI

bash

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset tools.web.search.apiKey
openclaw config file      # 查看配置文件路径
openclaw config validate  # 验证配置

เว็บคอนโซล

เปิด http://127.0.0.1:18789 และใช้แท็บ Config

แก้ไขโดยตรง

แก้ไข ~/.openclaw/openclaw.json โดยตรง และเกตเวย์จะใช้การเปลี่ยนแปลงโดยอัตโนมัติ

17. การตรวจสอบอย่างเข้มงวด

OpenClaw ยอมรับเฉพาะการกำหนดค่าที่ตรงกับสคีมาทุกประการ คีย์ที่ไม่รู้จัก ประเภทที่มีรูปแบบไม่ถูกต้อง หรือค่าที่ไม่ถูกต้องอาจทำให้เกตเวย์ปฏิเสธที่จะเริ่มทำงาน

เมื่อการยืนยันล้มเหลว:

เกตเวย์จะไม่เริ่มทำงาน
มีเพียงคำสั่งการวินิจฉัยเท่านั้น (openclaw doctor, openclaw logs, openclaw health, openclaw status)
เรียกใช้ openclaw doctor เพื่อดูปัญหาเฉพาะ
เรียกใช้ openclaw doctor --fix เพื่อใช้การแก้ไข

18. คำแนะนำในการโหลดซ้ำแบบร้อนแรง

รองรับการกำหนดค่าแอปพลิเคชันร้อนแรง

หมวดหมู่	สนาม	ต้องรีสตาร์ทไหม?
ช่อง	`channels.*`	ไม่
ตัวแทนและโมเดล	`agent`, `agents`, `models`, `routing`	ไม่
ระบบอัตโนมัติ	`hooks`, `cron`, `agent.heartbeat`	ไม่
การสนทนาและข้อความ	`session`, `messages`	ไม่
เครื่องมือและสื่อ	`tools`, `browser`, `skills`, `audio`, `talk`	ไม่
UI และอื่นๆ	`ui`, `logging`, `identity`, `bindings`	ไม่

การกำหนดค่าที่ต้องรีสตาร์ท

หมวดหมู่	สนาม
เซิร์ฟเวอร์เกตเวย์	`gateway.*` (พอร์ต, การเชื่อมโยง, การรับรองความถูกต้อง, Tailscale, TLS, HTTP)
โครงสร้างพื้นฐาน	`discovery`, `canvasHost`, `plugins`

ข้อยกเว้น: การเปลี่ยนแปลง gateway.reload และ gateway.remote ไม่ทำให้เกิดการรีสตาร์ท

เคล็ดลับ: คำอธิบายการกำหนดค่าโดยละเอียดนี้อ้างอิงจากเอกสาร OpenClaw อย่างเป็นทางการ สำหรับการอ้างอิงที่สมบูรณ์ โปรดไปที่ docs.openclaw.ai/gateway/configuration

ตำแหน่งไฟล์การกำหนดค่า ​

ภาพรวมโครงสร้างไฟล์การกำหนดค่า ​

1. การกำหนดค่าตัวแทน (ตัวแทน) ​

1.1 การกำหนดค่าเริ่มต้น (agents.defaults) ​

1.2 การกำหนดค่าหลายตัวแทน (agents.list) ​

2. การกำหนดค่าช่อง (ช่อง) ​

2.1 การกำหนดค่านโยบาย DM ทั่วไป ​

2.2 แชทกลุ่มพูดถึงการควบคุมประตู ​

3. การกำหนดค่าเกตเวย์ (เกตเวย์) ​

4. การกำหนดค่าเซสชัน (เซสชัน) ​

5. การกำหนดค่าข้อความ (ข้อความ) ​

6. การกำหนดค่าเครื่องมือ (เครื่องมือ) ​

7. การกำหนดค่าทักษะ (ทักษะ) ​

8. การกำหนดค่างานที่กำหนดเวลาไว้ (cron) ​

9. การกำหนดค่า Webhook (hooks) ​

10. การกำหนดค่าการผูก (การผูก) ​

11. การกำหนดค่าตัวแปรสภาพแวดล้อม (env) ​

12. การแยกการกำหนดค่า ($รวม) ​

13. การแทนที่ตัวแปรสภาพแวดล้อม ​

14. ใบรับรอง SecretRef ​

15. ตัวอย่างการกำหนดค่าที่สมบูรณ์ ​

15.1 การกำหนดค่าขั้นต่ำ ​

15.2 การกำหนดค่าการพัฒนาท้องถิ่น ​

15.3 การกำหนดค่าการปรับใช้เซิร์ฟเวอร์ ​

15.4 การกำหนดค่าหลายตัวแทน ​

16. วิธีการแก้ไขการกำหนดค่า ​

ตัวช่วยสร้างแบบโต้ตอบ ​

คำสั่ง CLI ​

เว็บคอนโซล ​

แก้ไขโดยตรง ​

17. การตรวจสอบอย่างเข้มงวด ​

18. คำแนะนำในการโหลดซ้ำแบบร้อนแรง ​

รองรับการกำหนดค่าแอปพลิเคชันร้อนแรง ​

การกำหนดค่าที่ต้องรีสตาร์ท ​

ตำแหน่งไฟล์การกำหนดค่า

ภาพรวมโครงสร้างไฟล์การกำหนดค่า

1. การกำหนดค่าตัวแทน (ตัวแทน)

1.1 การกำหนดค่าเริ่มต้น (agents.defaults)

1.2 การกำหนดค่าหลายตัวแทน (agents.list)

2. การกำหนดค่าช่อง (ช่อง)

2.1 การกำหนดค่านโยบาย DM ทั่วไป

2.2 แชทกลุ่มพูดถึงการควบคุมประตู

3. การกำหนดค่าเกตเวย์ (เกตเวย์)

4. การกำหนดค่าเซสชัน (เซสชัน)

5. การกำหนดค่าข้อความ (ข้อความ)

6. การกำหนดค่าเครื่องมือ (เครื่องมือ)

7. การกำหนดค่าทักษะ (ทักษะ)

8. การกำหนดค่างานที่กำหนดเวลาไว้ (cron)

9. การกำหนดค่า Webhook (hooks)

10. การกำหนดค่าการผูก (การผูก)

11. การกำหนดค่าตัวแปรสภาพแวดล้อม (env)

12. การแยกการกำหนดค่า ($รวม)

13. การแทนที่ตัวแปรสภาพแวดล้อม

14. ใบรับรอง SecretRef

15. ตัวอย่างการกำหนดค่าที่สมบูรณ์

15.1 การกำหนดค่าขั้นต่ำ

15.2 การกำหนดค่าการพัฒนาท้องถิ่น

15.3 การกำหนดค่าการปรับใช้เซิร์ฟเวอร์

15.4 การกำหนดค่าหลายตัวแทน

16. วิธีการแก้ไขการกำหนดค่า

ตัวช่วยสร้างแบบโต้ตอบ

คำสั่ง CLI

เว็บคอนโซล

แก้ไขโดยตรง

17. การตรวจสอบอย่างเข้มงวด

18. คำแนะนำในการโหลดซ้ำแบบร้อนแรง

รองรับการกำหนดค่าแอปพลิเคชันร้อนแรง

การกำหนดค่าที่ต้องรีสตาร์ท