Hello Claw: Hướng dẫn nhập môn OpenClaw

#Phụ lục B: Giải thích chi tiết file cấu hình

Hệ thống cấu hình của OpenClaw rất linh hoạt và mạnh mẽ. Phụ lục này phân tích chi tiết từng mục cấu hình dựa trên các tài liệu chính thức.

Nguồn tham khảo: OpenClaw Configuration

Vị trí tệp cấu hình

OpenClaw đọc tệp cấu hình JSON5 tùy chọn:

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

Nếu tệp cấu hình không tồn tại, OpenClaw sẽ sử dụng các giá trị mặc định an toàn.

Tổng quan về cấu trúc file cấu hình

json5

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

1. Cấu hình tác nhân (agent)

1.1 Cấu hình mặc định (agent.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"
      }
    }
  }
}

Mô tả mục cấu hình:

Mục cấu hình	Loại	Giá trị mặc định	Mô tả
`workspace`	chuỗi	~/.openclaw/workspace	Thư mục làm việc của đại lý
`model.primary`	chuỗi	-	Mô hình chính, định dạng: nhà cung cấp/mô hình
`model.fallbacks`	mảng	[]	Danh sách mô hình dự phòng
`imageMaxDimensionPx`	số	1200	Phiên âm hình ảnh/Công cụ Kích thước thu phóng hình ảnh
`heartbeat.every`	chuỗi	-	Khoảng nhịp tim (chẳng hạn như 30m, 2h)
`sandbox.mode`	chuỗi	tắt	chế độ hộp cát

1.2 Cấu hình Multi-Agent (agent.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. Cấu hình kênh (channel)

2.1 Cấu hình chính sách DM chung

Tất cả các kênh đều có chung một mẫu chiến lược 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"
    }
  }
}

Tùy chọn chính sách DM:

Chiến lược	Mô tả
`pairing`	Người gửi không xác định đã nhận được mã ghép nối một lần và cần được phê duyệt
`allowlist`	Chỉ người gửi trong allowFrom
`open`	Cho phép tất cả DM gửi đến (yêu cầu allowFrom: ["*"])
`disabled`	Bỏ qua tất cả DM

2.2 Kiểm soát cổng đề cập trò chuyện nhóm

json5

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

3. Cấu hình cổng (gateway)

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

Tùy chọn địa chỉ liên kết:

giá trị	mô tả
`loopback`	Chỉ truy cập cục bộ (127.0.0.1)
`lan`	Có thể truy cập mạng LAN
`tailnet`	Mạng lưới đuôi xe
`auto`	Tự động phát hiện
`custom`	Địa chỉ tùy chỉnh

Chế độ tải lại nóng:

Mẫu	Hành vi
`hybrid`	Áp dụng nóng các thay đổi an toàn, tự động khởi động lại các thay đổi quan trọng (mặc định)
`hot`	Chỉ áp dụng các thay đổi an toàn nóng, cảnh báo nhật ký nếu cần khởi động lại
`restart`	Khởi động lại cổng khi có bất kỳ thay đổi cấu hình nào
`off`	Vô hiệu hóa giám sát tập tin

4. Cấu hình phiên (session)

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

Tùy chọn phạm vi DM:

giá trị	mô tả
`main`	Phiên chia sẻ
`per-peer`	Phiên độc lập trên mỗi ngang hàng
`per-channel-peer`	Mỗi kênh - phiên độc lập cho các đồng nghiệp (khuyến nghị nhiều người dùng)
`per-account-channel-peer`	Phiên độc lập trên mỗi tài khoản-kênh-ngang hàng

5. Cấu hình tin nhắn (tin nhắn)

json5

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

6. Cấu hình công cụ (tool)

json5

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

Tệp cấu hình công cụ:

Hồ sơ	Mô tả
`messaging`	Chỉ trò chuyện, không có công cụ
`default`	Bộ công cụ cơ bản
`coding`	Bộ công cụ lập trình
`full`	Bộ công cụ hoàn chỉnh
`all`	Tất cả công cụ

##7. Cấu hình kỹ năng (skills)

json5

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

8. Cấu hình tác vụ theo lịch trình (cron)

json5

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

9. Cấu hình Webhook (hook)

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. Cấu hình liên kết (bind)

json5

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

11. Cấu hình biến môi trường (env)

json5

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

Các nguồn biến đổi môi trường (theo mức độ ưu tiên):

Biến môi trường tiến trình cha
Tệp .env trong thư mục làm việc hiện tại
Tệp ~/.openclaw/.env (dự phòng toàn cầu)

Không ghi đè lên các biến môi trường hiện có.

12. Chia cấu hình ($bao gồm)

Sử dụng $include để sắp xếp các cấu hình lớn:

json5

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

Quy tắc:

Tệp đơn: thay thế các đối tượng chứa
Mảng file: gộp sâu theo thứ tự (mới nhất trước)
Khóa anh chị em: hợp nhất sau bao gồm (ghi đè các giá trị được bao gồm)
Nested bao gồm: hỗ trợ sâu tới 10 cấp độ
Đường dẫn tương đối: giải quyết tương ứng với file chứa

13. Thay thế biến môi trường

Các biến môi trường tham chiếu trong giá trị chuỗi cấu hình:

json5

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

Quy tắc:

Chỉ khớp với tên viết hoa: [A-Z_][A-Z0-9_]*
Biến bị thiếu/trống gây ra lỗi khi tải
Sử dụng $${VAR} để thoát sang đầu ra theo nghĩa đen
Cũng hợp lệ trong các tệp $include
Thay thế nội tuyến: "${BASE}/v1" → "https://api.example.com/v1"

14. Chứng chỉ SecretRef

Các trường được hỗ trợ của đối tượng 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"
      }
    }
  }
}

loại nguồn:

env: biến môi trường
file: Nội dung file
exec: Đầu ra thực thi lệnh

15. Ví dụ cấu hình hoàn chỉnh

15.1 Cấu hình tối thiểu

json5

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

15.2 Cấu hình phát triển cục bộ

json5

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

15.3 Cấu hình triển khai máy chủ

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 Cấu hình đa tác nhân

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. Phương pháp chỉnh sửa cấu hình

Thuật sĩ tương tác

bash

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

Lệnh 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  # 验证配置

Bảng điều khiển web

Mở http://127.0.0.1:18789 và sử dụng tab Cấu hình.

Chỉnh sửa trực tiếp

Chỉnh sửa trực tiếp ~/.openclaw/openclaw.json và cổng sẽ tự động áp dụng các thay đổi.

##17. Xác minh nghiêm ngặt

OpenClaw chỉ chấp nhận các cấu hình khớp chính xác với lược đồ. Khóa không xác định, loại không đúng định dạng hoặc giá trị không hợp lệ có thể khiến cổng từ chối khởi động.

Khi xác minh không thành công:

Cổng sẽ không khởi động
Chỉ có các lệnh chẩn đoán (openclaw doctor, openclaw logs, openclaw health, openclaw status)
Chạy openclaw doctor để xem các vấn đề cụ thể
Chạy openclaw doctor --fix để áp dụng bản sửa lỗi

##18. Hướng dẫn nạp đạn nóng

###Hỗ trợ cấu hình ứng dụng hot

Danh mục	Lĩnh vực	Cần khởi động lại?
Kênh	`channels.*`	Không
Đại lý & Người mẫu	`agent`, `agents`, `models`, `routing`	Không
Tự động hóa	`hooks`, `cron`, `agent.heartbeat`	Không
Cuộc trò chuyện & Tin nhắn	`session`, `messages`	Không
Công cụ & Phương tiện	`tools`, `browser`, `skills`, `audio`, `talk`	Không
Giao diện người dùng & Khác	`ui`, `logging`, `identity`, `bindings`	Không

Cấu hình yêu cầu khởi động lại

Danh mục	Lĩnh vực
Máy chủ cổng	`gateway.*` (Cổng, Ràng buộc, Xác thực, Tailscale, TLS, HTTP)
Cơ sở hạ tầng	`discovery`, `canvasHost`, `plugins`

Ngoại lệ: gateway.reload và gateway.remote các thay đổi không kích hoạt khởi động lại.

Mẹo: Giải thích cấu hình chi tiết này dựa trên tài liệu OpenClaw chính thức. Để tham khảo đầy đủ, vui lòng truy cập docs.openclaw.ai/gateway/configuration.

Vị trí tệp cấu hình ​

Tổng quan về cấu trúc file cấu hình ​

1. Cấu hình tác nhân (agent) ​

1.1 Cấu hình mặc định (agent.defaults) ​

1.2 Cấu hình Multi-Agent (agent.list) ​

2. Cấu hình kênh (channel) ​

2.1 Cấu hình chính sách DM chung ​

2.2 Kiểm soát cổng đề cập trò chuyện nhóm ​

3. Cấu hình cổng (gateway) ​

4. Cấu hình phiên (session) ​

5. Cấu hình tin nhắn (tin nhắn) ​

6. Cấu hình công cụ (tool) ​

8. Cấu hình tác vụ theo lịch trình (cron) ​

9. Cấu hình Webhook (hook) ​

10. Cấu hình liên kết (bind) ​

11. Cấu hình biến môi trường (env) ​

12. Chia cấu hình ($bao gồm) ​

13. Thay thế biến môi trường ​

14. Chứng chỉ SecretRef ​

15. Ví dụ cấu hình hoàn chỉnh ​

15.1 Cấu hình tối thiểu ​

15.2 Cấu hình phát triển cục bộ ​

15.3 Cấu hình triển khai máy chủ ​

15.4 Cấu hình đa tác nhân ​

16. Phương pháp chỉnh sửa cấu hình ​

Thuật sĩ tương tác ​

Lệnh CLI ​

Bảng điều khiển web ​

Chỉnh sửa trực tiếp ​

Cấu hình yêu cầu khởi động lại ​

Vị trí tệp cấu hình

Tổng quan về cấu trúc file cấu hình

1. Cấu hình tác nhân (agent)

1.1 Cấu hình mặc định (agent.defaults)

1.2 Cấu hình Multi-Agent (agent.list)

2. Cấu hình kênh (channel)

2.1 Cấu hình chính sách DM chung

2.2 Kiểm soát cổng đề cập trò chuyện nhóm

3. Cấu hình cổng (gateway)

4. Cấu hình phiên (session)

5. Cấu hình tin nhắn (tin nhắn)

6. Cấu hình công cụ (tool)

8. Cấu hình tác vụ theo lịch trình (cron)

9. Cấu hình Webhook (hook)

10. Cấu hình liên kết (bind)

11. Cấu hình biến môi trường (env)

12. Chia cấu hình ($bao gồm)

13. Thay thế biến môi trường

14. Chứng chỉ SecretRef

15. Ví dụ cấu hình hoàn chỉnh

15.1 Cấu hình tối thiểu

15.2 Cấu hình phát triển cục bộ

15.3 Cấu hình triển khai máy chủ

15.4 Cấu hình đa tác nhân

16. Phương pháp chỉnh sửa cấu hình

Thuật sĩ tương tác

Lệnh CLI

Bảng điều khiển web

Chỉnh sửa trực tiếp

Cấu hình yêu cầu khởi động lại