Tham chiếu cấu hình

• openclaw config schema in JSON Schema trực tiếp dùng cho xác thực và Control UI, với metadata bundled/plugin/channel được hợp nhất khi có
• config.schema.lookup trả về một nút schema theo phạm vi đường dẫn cho công cụ drill-down
• pnpm config:docs:check / pnpm config:docs:gen xác thực hash baseline tài liệu cấu hình so với bề mặt schema hiện tại

• Tham chiếu cấu hình bộ nhớ cho agents.defaults.memorySearch.*, memory.qmd.*, memory.citations, và cấu hình dreaming dưới plugins.entries.memory-core.config.dreaming
• Lệnh slash cho catalog lệnh tích hợp + bundled hiện tại
• các trang kênh/plugin sở hữu cho bề mặt lệnh theo kênh

​

Kênh

​

Giá trị mặc định của agent, đa agent, phiên, và tin nhắn

• agents.defaults.* (workspace, model, thinking, heartbeat, memory, media, skills, sandbox)
• multiAgent.* (định tuyến và liên kết đa agent)
• session.* (vòng đời phiên, compaction, pruning)
• messages.* (phân phối tin nhắn, TTS, kết xuất markdown)
• talk.* (chế độ Talk)
  • talk.consultThinkingLevel: ghi đè mức thinking cho toàn bộ lần chạy agent OpenClaw phía sau các consult realtime của Control UI Talk
  • talk.consultFastMode: ghi đè fast-mode một lần cho các consult realtime của Control UI Talk
  • talk.speechLocale: id locale BCP 47 tùy chọn cho nhận dạng giọng nói Talk trên iOS/macOS
  • talk.silenceTimeoutMs: khi chưa đặt, Talk giữ cửa sổ tạm dừng mặc định của nền tảng trước khi gửi transcript (700 ms on macOS and Android, 900 ms on iOS)
  • talk.realtime.consultRouting: fallback chuyển tiếp Gateway cho transcript Talk realtime đã hoàn tất bỏ qua openclaw_agent_consult

​

Công cụ và provider tùy chỉnh

​

Model

{
  models: {
    // Optional. Default: true. Requires a Gateway restart when changed.
    pricing: { enabled: false },
  },
}

• models.mode: hành vi catalog provider (merge hoặc replace).
• models.providers: map provider tùy chỉnh được khóa theo id provider.
• models.providers.*.localService: trình quản lý tiến trình theo nhu cầu tùy chọn cho máy chủ model cục bộ. OpenClaw thăm dò endpoint health đã cấu hình, khởi động command tuyệt đối khi cần, chờ sẵn sàng, rồi gửi yêu cầu model. Xem Dịch vụ model cục bộ.
• models.pricing.enabled: kiểm soát bootstrap pricing chạy nền bắt đầu sau khi sidecar và kênh đạt đường dẫn Gateway ready. Khi là false, Gateway bỏ qua việc lấy catalog pricing của OpenRouter và LiteLLM; các giá trị models.providers.*.models[].cost đã cấu hình vẫn hoạt động cho ước tính chi phí cục bộ.

​

MCP

{
  mcp: {
    // Optional. Default: 600000 ms (10 minutes). Set 0 to disable idle eviction.
    sessionIdleTtlMs: 600000,
    servers: {
      docs: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-fetch"],
      },
      remote: {
        url: "https://example.com/mcp",
        transport: "streamable-http", // streamable-http | sse
        timeout: 20,
        connectTimeout: 5,
        supportsParallelToolCalls: true,
        headers: {
          Authorization: "Bearer ${MCP_REMOTE_TOKEN}",
        },
        auth: "oauth",
        oauth: {
          scope: "docs.read",
        },
        sslVerify: true,
        clientCert: "/path/to/client.crt",
        clientKey: "/path/to/client.key",
        toolFilter: {
          include: ["search_*"],
          exclude: ["admin_*"],
        },
        // Optional Codex app-server projection controls.
        codex: {
          agents: ["main"],
          defaultToolsApprovalMode: "approve", // auto | prompt | approve
        },
      },
    },
  },
}

• mcp.servers: định nghĩa máy chủ MCP stdio hoặc remote có tên cho các runtime phơi bày công cụ MCP đã cấu hình. Mục remote dùng transport: "streamable-http" hoặc transport: "sse"; type: "http" là alias gốc CLI mà openclaw mcp set và openclaw doctor --fix chuẩn hóa vào trường transport canonical.
• mcp.servers.<name>.enabled: đặt false để giữ định nghĩa máy chủ đã lưu trong khi loại trừ nó khỏi khám phá MCP OpenClaw nhúng và phép chiếu công cụ.
• mcp.servers.<name>.timeout / requestTimeoutMs: thời gian chờ yêu cầu MCP theo máy chủ, tính bằng giây hoặc mili giây.
• mcp.servers.<name>.connectTimeout / connectionTimeoutMs: thời gian chờ kết nối theo máy chủ, tính bằng giây hoặc mili giây.
• mcp.servers.<name>.supportsParallelToolCalls: gợi ý đồng thời tùy chọn cho adapter có thể chọn có phát lệnh gọi công cụ MCP song song hay không.
• mcp.servers.<name>.auth: đặt "oauth" cho máy chủ HTTP MCP yêu cầu OAuth. Chạy openclaw mcp login <name> để lưu token dưới trạng thái OpenClaw.
• mcp.servers.<name>.oauth: ghi đè tùy chọn cho scope OAuth, URL chuyển hướng, và URL metadata client.
• mcp.servers.<name>.sslVerify, clientCert, clientKey: điều khiển HTTP TLS cho endpoint riêng tư và TLS hai chiều.
• mcp.servers.<name>.toolFilter: lựa chọn công cụ theo máy chủ tùy chọn. include giới hạn các công cụ MCP được khám phá chỉ còn những tên khớp; exclude ẩn các tên khớp. Mục là tên công cụ MCP chính xác hoặc glob * đơn giản. Máy chủ có resources hoặc prompts cũng tạo tên công cụ tiện ích (resources_list, resources_read, prompts_list, prompts_get), và những tên đó dùng cùng bộ lọc.
• mcp.servers.<name>.codex: điều khiển phép chiếu app-server Codex tùy chọn. Khối này là metadata OpenClaw chỉ dành cho luồng app-server Codex; nó không ảnh hưởng đến phiên ACP, cấu hình harness Codex chung, hoặc adapter runtime khác. codex.agents không rỗng giới hạn máy chủ vào các id agent OpenClaw được liệt kê. Danh sách agent có phạm vi rỗng, trống, hoặc không hợp lệ bị xác thực cấu hình từ chối và bị đường dẫn phép chiếu runtime bỏ qua thay vì trở thành toàn cục. codex.defaultToolsApprovalMode phát default_tools_approval_mode gốc của Codex cho máy chủ đó. OpenClaw loại bỏ khối codex trước khi truyền cấu hình mcp_servers gốc cho Codex. Bỏ qua khối này để giữ máy chủ được chiếu cho mọi agent app-server Codex với hành vi phê duyệt MCP mặc định của Codex.
• mcp.sessionIdleTtlMs: TTL nhàn rỗi cho runtime MCP bundled theo phạm vi phiên. Các lần chạy nhúng one-shot yêu cầu dọn dẹp khi kết thúc chạy; TTL này là chốt dự phòng cho phiên sống lâu và caller tương lai.
• Thay đổi dưới mcp.* được áp dụng nóng bằng cách hủy runtime MCP phiên đã cache. Lần khám phá/dùng công cụ tiếp theo tạo lại chúng từ cấu hình mới, nên các mục mcp.servers đã xóa được thu dọn ngay thay vì chờ TTL nhàn rỗi.
• Khám phá runtime cũng tôn trọng thông báo thay đổi danh sách công cụ MCP bằng cách bỏ catalog đã cache cho phiên đó. Máy chủ quảng bá resources hoặc prompts nhận công cụ tiện ích để liệt kê/đọc resources và liệt kê/lấy prompts. Lỗi gọi công cụ lặp lại tạm dừng máy chủ bị ảnh hưởng trong thời gian ngắn trước khi thử một lệnh gọi khác.

​

Skills

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun
      allowUploadedArchives: false,
    },
    workshop: {
      allowSymlinkTargetWrites: false,
    },
    entries: {
      "image-lab": {
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

• allowBundled: allowlist tùy chọn chỉ cho skills bundled (skills được quản lý/workspace không bị ảnh hưởng).
• load.extraDirs: root skill chia sẻ bổ sung (độ ưu tiên thấp nhất).
• load.allowSymlinkTargets: root đích thực đáng tin cậy mà symlink skill có thể phân giải vào khi liên kết nằm ngoài root nguồn đã cấu hình.
• workshop.allowSymlinkTargetWrites: cho phép Skill Workshop apply ghi xuyên qua các đích symlink đã tin cậy (mặc định: false).
• install.preferBrew: khi là true, ưu tiên trình cài đặt Homebrew khi brew có sẵn trước khi fallback sang các loại trình cài đặt khác.
• install.nodeManager: tùy chọn trình cài đặt node cho spec metadata.openclaw.install (npm | pnpm | yarn | bun).
• install.allowUploadedArchives: cho phép client Gateway operator.admin đáng tin cậy cài đặt kho lưu trữ zip riêng tư được staged qua skills.upload.* (mặc định: false). Điều này chỉ bật đường dẫn uploaded-archive; cài đặt ClawHub bình thường không yêu cầu nó.
• entries.<skillKey>.enabled: false vô hiệu hóa một skill ngay cả khi đã bundled/installed.
• entries.<skillKey>.apiKey: tiện ích cho skills khai báo một biến môi trường chính (chuỗi plaintext hoặc đối tượng SecretRef).

​

Plugin

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: [],
    load: {
      paths: ["~/Projects/oss/voice-call-plugin"],
    },
    entries: {
      "voice-call": {
        enabled: true,
        hooks: {
          allowPromptInjection: false,
        },
        config: { provider: "twilio" },
      },
    },
  },
}

• Được tải từ các thư mục package hoặc bundle trong ~/.openclaw/extensions và <workspace>/.openclaw/extensions, cộng với các tệp hoặc thư mục được liệt kê trong plugins.load.paths.
• Đặt các tệp Plugin độc lập trong plugins.load.paths; các gốc tiện ích mở rộng được tự động phát hiện sẽ bỏ qua các tệp .js, .mjs, và .ts cấp cao nhất để các script hỗ trợ trong những gốc đó không chặn quá trình khởi động.
• Quá trình phát hiện chấp nhận các Plugin OpenClaw gốc cùng với các bundle Codex và bundle Claude tương thích, bao gồm cả các bundle bố cục mặc định của Claude không có manifest.
• Thay đổi cấu hình yêu cầu khởi động lại Gateway.
• allow: danh sách cho phép tùy chọn (chỉ các Plugin được liệt kê mới tải). deny được ưu tiên.
• plugins.entries.<id>.apiKey: trường tiện ích API key cấp Plugin (khi được Plugin hỗ trợ).
• plugins.entries.<id>.env: bản đồ biến môi trường theo phạm vi Plugin.
• plugins.entries.<id>.hooks.allowPromptInjection: khi là false, core chặn before_prompt_build và bỏ qua các trường làm thay đổi prompt từ before_agent_start cũ, trong khi vẫn giữ modelOverride và providerOverride cũ. Áp dụng cho hook Plugin gốc và các thư mục hook do bundle được hỗ trợ cung cấp.
• plugins.entries.<id>.hooks.allowConversationAccess: khi là true, các Plugin không đi kèm đáng tin cậy có thể đọc nội dung hội thoại thô từ các hook có kiểu như llm_input, llm_output, before_model_resolve, before_agent_reply, before_agent_run, before_agent_finalize, và agent_end.
• plugins.entries.<id>.subagent.allowModelOverride: tin cậy rõ ràng Plugin này để yêu cầu ghi đè provider và model theo từng lượt chạy cho các lượt chạy subagent nền.
• plugins.entries.<id>.subagent.allowedModels: danh sách cho phép tùy chọn gồm các mục tiêu provider/model chuẩn cho ghi đè subagent đáng tin cậy. Chỉ dùng "*" khi bạn chủ đích muốn cho phép bất kỳ mô hình nào.
• plugins.entries.<id>.llm.allowModelOverride: tin cậy rõ ràng Plugin này để yêu cầu ghi đè mô hình cho api.runtime.llm.complete.
• plugins.entries.<id>.llm.allowedModels: danh sách cho phép tùy chọn gồm các mục tiêu provider/model chuẩn cho ghi đè hoàn tất LLM của Plugin đáng tin cậy. Chỉ dùng "*" khi bạn chủ đích muốn cho phép bất kỳ mô hình nào.
• plugins.entries.<id>.llm.allowAgentIdOverride: tin cậy rõ ràng Plugin này để chạy api.runtime.llm.complete với id agent không phải mặc định.
• plugins.entries.<id>.config: đối tượng cấu hình do Plugin định nghĩa (được schema Plugin OpenClaw gốc xác thực khi có).
• Cài đặt tài khoản/runtime của Plugin kênh nằm dưới channels.<id> và nên được mô tả bằng metadata channelConfigs trong manifest của Plugin sở hữu, không phải bằng một registry tùy chọn OpenClaw trung tâm.

​

Cấu hình Plugin harness Codex

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          codexPlugins: {
            enabled: true,
            allow_destructive_actions: true,
            plugins: {
              "google-calendar": {
                enabled: true,
                marketplaceName: "openai-curated",
                pluginName: "google-calendar",
                allow_destructive_actions: false,
              },
            },
          },
        },
      },
    },
  },
}

• plugins.entries.codex.config.codexPlugins.enabled: bật hỗ trợ Plugin/ứng dụng Codex gốc cho harness Codex. Mặc định: false.
• plugins.entries.codex.config.codexPlugins.allow_destructive_actions: chính sách hành động phá hủy mặc định cho các lời gọi ứng dụng Plugin đã được di chuyển. Dùng true để chấp nhận các schema phê duyệt Codex an toàn mà không hỏi, false để từ chối chúng, "auto" để định tuyến các phê duyệt do Codex yêu cầu qua phê duyệt Plugin OpenClaw, hoặc "ask" để hỏi cho mọi hành động ghi/phá hủy của Plugin mà không có phê duyệt bền vững. Chế độ "ask" xóa các ghi đè phê duyệt Codex bền vững theo từng công cụ cho ứng dụng bị ảnh hưởng và chọn người đánh giá phê duyệt là con người cho ứng dụng đó trước khi luồng Codex bắt đầu. Mặc định: true.
• plugins.entries.codex.config.codexPlugins.plugins.<key>.enabled: bật một mục Plugin đã di chuyển khi codexPlugins.enabled toàn cục cũng là true. Mặc định: true cho các mục tường minh.
• plugins.entries.codex.config.codexPlugins.plugins.<key>.marketplaceName: danh tính marketplace ổn định. V1 chỉ hỗ trợ "openai-curated".
• plugins.entries.codex.config.codexPlugins.plugins.<key>.pluginName: danh tính Plugin Codex ổn định từ quá trình di chuyển, ví dụ "google-calendar".
• plugins.entries.codex.config.codexPlugins.plugins.<key>.allow_destructive_actions: ghi đè hành động phá hủy theo từng Plugin. Khi bị bỏ qua, giá trị allow_destructive_actions toàn cục được dùng. Giá trị theo từng Plugin chấp nhận cùng các chính sách true, false, "auto", hoặc "ask".

• plugins.entries.firecrawl.config.webFetch: cài đặt provider tìm nạp web Firecrawl.
  • apiKey: API key Firecrawl tùy chọn để có giới hạn cao hơn (chấp nhận SecretRef). Dự phòng về plugins.entries.firecrawl.config.webSearch.apiKey, tools.web.fetch.firecrawl.apiKey cũ, hoặc biến môi trường FIRECRAWL_API_KEY.
  • baseUrl: URL cơ sở API Firecrawl (mặc định: https://api.firecrawl.dev; các ghi đè tự lưu trữ phải nhắm đến endpoint riêng tư/nội bộ).
  • onlyMainContent: chỉ trích xuất nội dung chính từ trang (mặc định: true).
  • maxAgeMs: tuổi tối đa của bộ nhớ đệm tính bằng mili giây (mặc định: 172800000 / 2 ngày).
  • timeoutSeconds: thời gian chờ yêu cầu scrape tính bằng giây (mặc định: 60).
• plugins.entries.xai.config.xSearch: cài đặt xAI X Search (tìm kiếm web Grok).
  • enabled: bật provider X Search.
  • model: mô hình Grok dùng cho tìm kiếm (ví dụ "grok-4-1-fast").
• plugins.entries.memory-core.config.dreaming: cài đặt dreaming bộ nhớ. Xem Dreaming để biết các pha và ngưỡng.
  • enabled: công tắc dreaming chính (mặc định false).
  • frequency: nhịp cron cho mỗi lượt quét dreaming đầy đủ (mặc định là "0 3 * * *").
  • model: ghi đè mô hình subagent Dream Diary tùy chọn. Yêu cầu plugins.entries.memory-core.subagent.allowModelOverride: true; ghép với allowedModels để giới hạn mục tiêu. Lỗi không có mô hình sẽ thử lại một lần với mô hình mặc định của phiên; lỗi tin cậy hoặc danh sách cho phép sẽ không âm thầm dự phòng.
  • chính sách pha và ngưỡng là chi tiết triển khai (không phải khóa cấu hình hướng đến người dùng).
• Cấu hình bộ nhớ đầy đủ nằm trong tham chiếu cấu hình bộ nhớ:
  • agents.defaults.memorySearch.*
  • memory.backend
  • memory.citations
  • memory.qmd.*
  • plugins.entries.memory-core.config.dreaming
• Các Plugin bundle Claude đã bật cũng có thể đóng góp mặc định OpenClaw nhúng từ settings.json; OpenClaw áp dụng chúng như cài đặt agent đã được làm sạch, không phải như bản vá cấu hình OpenClaw thô.
• plugins.slots.memory: chọn id Plugin bộ nhớ đang hoạt động, hoặc "none" để tắt Plugin bộ nhớ.
• plugins.slots.contextEngine: chọn id Plugin công cụ ngữ cảnh đang hoạt động; mặc định là "legacy" trừ khi bạn cài đặt và chọn một công cụ khác.

​

Cam kết

• commitments.enabled: bật trích xuất LLM ẩn, lưu trữ và phân phối Heartbeat cho các cam kết theo dõi suy luận. Mặc định: false.
• commitments.maxPerDay: số cam kết theo dõi suy luận tối đa được phân phối cho mỗi phiên agent trong một ngày cuốn chiếu. Mặc định: 3.

​

Trình duyệt

{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    defaultProfile: "user",
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    tabCleanup: {
      enabled: true,
      idleMinutes: 120,
      maxTabsPerSession: 8,
      sweepMinutes: 5,
    },
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: {
        cdpPort: 18801,
        color: "#0066CC",
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      user: { driver: "existing-session", attachOnly: true, color: "#00AA00" },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
    color: "#FF4500",
    // headless: false,
    // noSandbox: false,
    // extraArgs: [],
    // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    // attachOnly: false,
  },
}

• evaluateEnabled: false vô hiệu hóa act:evaluate và wait --fn.
• tabCleanup thu hồi các tab tác nhân chính được theo dõi sau thời gian nhàn rỗi hoặc khi một phiên vượt quá giới hạn của nó. Đặt idleMinutes: 0 hoặc maxTabsPerSession: 0 để vô hiệu hóa từng chế độ dọn dẹp riêng lẻ đó.
• ssrfPolicy.dangerouslyAllowPrivateNetwork bị vô hiệu hóa khi chưa đặt, vì vậy điều hướng trình duyệt mặc định vẫn nghiêm ngặt.
• Chỉ đặt ssrfPolicy.dangerouslyAllowPrivateNetwork: true khi bạn chủ ý tin cậy điều hướng trình duyệt trong mạng riêng.
• Trong chế độ nghiêm ngặt, các endpoint hồ sơ CDP từ xa (profiles.*.cdpUrl) cũng chịu cùng cơ chế chặn mạng riêng trong các kiểm tra khả năng truy cập/phát hiện.
• ssrfPolicy.allowPrivateNetwork vẫn được hỗ trợ như một bí danh kế thừa.
• Trong chế độ nghiêm ngặt, hãy dùng ssrfPolicy.hostnameAllowlist và ssrfPolicy.allowedHostnames cho các ngoại lệ rõ ràng.
• Hồ sơ từ xa chỉ cho phép đính kèm (vô hiệu hóa start/stop/reset).
• profiles.*.cdpUrl chấp nhận http://, https://, ws://, và wss://. Dùng HTTP(S) khi bạn muốn OpenClaw phát hiện /json/version; dùng WS(S) khi nhà cung cấp của bạn cấp URL DevTools WebSocket trực tiếp.
• remoteCdpTimeoutMs và remoteCdpHandshakeTimeoutMs áp dụng cho khả năng truy cập CDP từ xa và attachOnly, cùng với các yêu cầu mở tab. Các hồ sơ local loopback được quản lý vẫn giữ mặc định CDP cục bộ.
• Nếu một dịch vụ CDP được quản lý bên ngoài có thể truy cập qua loopback, hãy đặt attachOnly: true cho hồ sơ đó; nếu không OpenClaw sẽ xem cổng loopback là một hồ sơ trình duyệt được quản lý cục bộ và có thể báo lỗi quyền sở hữu cổng cục bộ.
• Hồ sơ existing-session dùng Chrome MCP thay vì CDP và có thể đính kèm trên máy chủ đã chọn hoặc thông qua một nút trình duyệt đã kết nối.
• Hồ sơ existing-session có thể đặt userDataDir để nhắm tới một hồ sơ trình duyệt dựa trên Chromium cụ thể như Brave hoặc Edge.
• Hồ sơ existing-session có thể đặt cdpUrl khi Chrome đã chạy phía sau endpoint phát hiện HTTP(S) DevTools hoặc endpoint WS(S) trực tiếp. Trong chế độ đó, OpenClaw truyền endpoint cho Chrome MCP thay vì dùng auto-connect; userDataDir bị bỏ qua đối với đối số khởi chạy Chrome MCP.
• Hồ sơ existing-session giữ các giới hạn tuyến Chrome MCP hiện tại: hành động dựa trên snapshot/ref thay vì nhắm mục tiêu bằng CSS-selector, hook tải lên một tệp, không ghi đè timeout hộp thoại, không có wait --load networkidle, và không có responsebody, xuất PDF, chặn tải xuống, hoặc hành động hàng loạt.
• Hồ sơ openclaw được quản lý cục bộ tự động gán cdpPort và cdpUrl; chỉ đặt cdpUrl rõ ràng cho hồ sơ CDP từ xa hoặc đính kèm endpoint existing-session.
• Hồ sơ được quản lý cục bộ có thể đặt executablePath để ghi đè browser.executablePath toàn cục cho hồ sơ đó. Dùng tùy chọn này để chạy một hồ sơ trong Chrome và hồ sơ khác trong Brave.
• Hồ sơ được quản lý cục bộ dùng browser.localLaunchTimeoutMs cho quá trình phát hiện HTTP Chrome CDP sau khi tiến trình khởi động và browser.localCdpReadyTimeoutMs cho trạng thái sẵn sàng CDP websocket sau khởi chạy. Tăng các giá trị này trên máy chủ chậm hơn, nơi Chrome khởi động thành công nhưng các kiểm tra sẵn sàng chạy đua với quá trình khởi động. Cả hai giá trị phải là số nguyên dương tối đa 120000 ms; giá trị cấu hình không hợp lệ sẽ bị từ chối.
• Thứ tự tự động phát hiện: trình duyệt mặc định nếu dựa trên Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
• browser.executablePath và browser.profiles.<name>.executablePath đều chấp nhận ~ và ~/... cho thư mục home của hệ điều hành trước khi khởi chạy Chromium. userDataDir theo hồ sơ trên hồ sơ existing-session cũng được mở rộng dấu ngã.
• Dịch vụ điều khiển: chỉ loopback (cổng dẫn xuất từ gateway.port, mặc định 18791).
• extraArgs thêm các cờ khởi chạy bổ sung vào quá trình khởi động Chromium cục bộ (ví dụ --disable-gpu, định cỡ cửa sổ, hoặc cờ gỡ lỗi).

​

Giao diện người dùng

{
  ui: {
    seamColor: "#FF4500",
    assistant: {
      name: "OpenClaw",
      avatar: "CB", // emoji, short text, image URL, or data URI
    },
  },
}

• seamColor: màu nhấn cho chrome giao diện người dùng ứng dụng gốc (màu phủ bong bóng Talk Mode, v.v.).
• assistant: ghi đè danh tính Control UI. Dự phòng về danh tính tác nhân đang hoạt động.

​

Gateway

{
  gateway: {
    mode: "local", // local | remote
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token", // none | token | password | trusted-proxy
      token: "your-token",
      // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD
      // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth
      allowTailscale: true,
      rateLimit: {
        maxAttempts: 10,
        windowMs: 60000,
        lockoutMs: 300000,
        exemptLoopback: true,
      },
    },
    tailscale: {
      mode: "off", // off | serve | funnel
      resetOnExit: false,
    },
    controlUi: {
      enabled: true,
      basePath: "/openclaw",
      // root: "dist/control-ui",
      // embedSandbox: "scripts", // strict | scripts | trusted
      // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs
      // chatMessageMaxWidth: "min(1280px, 82%)", // optional grouped chat message max-width
      // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI
      // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode
      // allowInsecureAuth: false,
      // dangerouslyDisableDeviceAuth: false,
    },
    remote: {
      url: "ws://127.0.0.1:18789",
      transport: "ssh", // ssh | direct
      token: "your-token",
      // password: "your-password",
    },
    trustedProxies: ["10.0.0.1"],
    // Optional. Default false.
    allowRealIpFallback: false,
    nodes: {
      pairing: {
        // Optional. Default unset/disabled.
        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],
      },
      allowCommands: ["canvas.navigate"],
      denyCommands: ["system.run"],
    },
    tools: {
      // Additional /tools/invoke HTTP denies
      deny: ["browser"],
      // Remove tools from the default HTTP deny list for owner/admin callers
      allow: ["gateway"],
    },
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          timeoutMs: 10000,
        },
      },
    },
  },
}

​

Endpoint tương thích OpenAI

• HTTP RPC quản trị: tắt theo mặc định dưới dạng Plugin admin-http-rpc. Bật Plugin để đăng ký POST /api/v1/admin/rpc. Xem HTTP RPC quản trị.
• Chat Completions: tắt theo mặc định. Bật bằng gateway.http.endpoints.chatCompletions.enabled: true.
• Responses API: gateway.http.endpoints.responses.enabled.
• Gia cố đầu vào URL của Responses:
  • gateway.http.endpoints.responses.maxUrlParts
  • gateway.http.endpoints.responses.files.urlAllowlist
  • gateway.http.endpoints.responses.images.urlAllowlist Allowlist rỗng được xem như chưa đặt; dùng gateway.http.endpoints.responses.files.allowUrl=false và/hoặc gateway.http.endpoints.responses.images.allowUrl=false để tắt việc fetch URL.
• Header gia cố phản hồi tùy chọn:
  • gateway.http.securityHeaders.strictTransportSecurity (chỉ đặt cho các nguồn HTTPS bạn kiểm soát; xem Xác thực Trusted Proxy)

​

Cô lập nhiều instance

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

​

gateway.tls

{
  gateway: {
    tls: {
      enabled: false,
      autoGenerate: false,
      certPath: "/etc/openclaw/tls/server.crt",
      keyPath: "/etc/openclaw/tls/server.key",
      caPath: "/etc/openclaw/tls/ca-bundle.crt",
    },
  },
}

• enabled: bật kết thúc TLS tại listener Gateway (HTTPS/WSS) (mặc định: false).
• autoGenerate: tự động tạo cặp cert/key tự ký cục bộ khi các file rõ ràng chưa được cấu hình; chỉ dùng cho cục bộ/dev.
• certPath: đường dẫn hệ thống file tới file chứng chỉ TLS.
• keyPath: đường dẫn hệ thống file tới file khóa riêng TLS; giữ quyền truy cập bị hạn chế.
• caPath: đường dẫn gói CA tùy chọn cho xác minh client hoặc chuỗi tin cậy tùy chỉnh.

​

gateway.reload

{
  gateway: {
    reload: {
      mode: "hybrid", // off | restart | hot | hybrid
      debounceMs: 500,
      deferralTimeoutMs: 300000,
    },
  },
}

• mode: kiểm soát cách áp dụng các chỉnh sửa cấu hình trong thời gian chạy.
  • "off": bỏ qua các chỉnh sửa trực tiếp; thay đổi yêu cầu khởi động lại rõ ràng.
  • "restart": luôn khởi động lại tiến trình gateway khi cấu hình thay đổi.
  • "hot": áp dụng thay đổi trong tiến trình mà không khởi động lại.
  • "hybrid" (mặc định): thử tải lại nóng trước; quay về khởi động lại nếu cần.
• debounceMs: khoảng debounce tính bằng ms trước khi áp dụng thay đổi cấu hình (số nguyên không âm).
• deferralTimeoutMs: thời gian tối đa tùy chọn tính bằng ms để chờ các thao tác đang chạy trước khi buộc khởi động lại hoặc tải lại nóng kênh. Bỏ qua để dùng thời gian chờ có giới hạn mặc định (300000); đặt 0 để chờ vô thời hạn và ghi nhật ký cảnh báo định kỳ rằng vẫn còn tác vụ đang chờ.

​

Hook

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    maxBodyBytes: 262144,
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: true,
    allowedSessionKeyPrefixes: ["hook:", "hook:gmail:"],
    allowedAgentIds: ["hooks", "main"],
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks/transforms",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "hooks",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        model: "openai/gpt-5.4-mini",
      },
    ],
  },
}

• hooks.enabled=true yêu cầu hooks.token không rỗng.
• hooks.token nên khác với xác thực shared-secret Gateway đang hoạt động (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN hoặc gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD); khi phát hiện tái sử dụng, quá trình khởi động sẽ ghi nhật ký cảnh báo bảo mật không gây lỗi.
• openclaw security audit đánh dấu việc tái sử dụng xác thực hook/Gateway là phát hiện nghiêm trọng, bao gồm cả xác thực mật khẩu Gateway chỉ được cung cấp tại thời điểm kiểm tra (--auth password --password <password>). Chạy openclaw doctor --fix để xoay vòng hooks.token đã lưu bị tái sử dụng, rồi cập nhật các trình gửi hook bên ngoài để dùng token hook mới.
• hooks.path không thể là /; dùng một đường dẫn con chuyên dụng như /hooks.
• Nếu hooks.allowRequestSessionKey=true, hãy giới hạn hooks.allowedSessionKeyPrefixes (ví dụ ["hook:"]).
• Nếu một ánh xạ hoặc preset dùng sessionKey dạng mẫu, hãy đặt hooks.allowedSessionKeyPrefixes và hooks.allowRequestSessionKey=true. Các khóa ánh xạ tĩnh không yêu cầu bật tùy chọn đó.

• POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
• POST /hooks/agent → { message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
  • sessionKey từ payload yêu cầu chỉ được chấp nhận khi hooks.allowRequestSessionKey=true (mặc định: false).
• POST /hooks/<name> → được phân giải qua hooks.mappings
  • Các giá trị ánh xạ sessionKey được render từ mẫu được xem là do bên ngoài cung cấp và cũng yêu cầu hooks.allowRequestSessionKey=true.

​

Tích hợp Gmail

• Preset Gmail tích hợp sẵn dùng sessionKey: "hook:gmail:{{messages[0].id}}".
• Nếu bạn giữ định tuyến theo từng thư đó, hãy đặt hooks.allowRequestSessionKey: true và giới hạn hooks.allowedSessionKeyPrefixes để khớp với namespace Gmail, ví dụ ["hook:", "hook:gmail:"].
• Nếu bạn cần hooks.allowRequestSessionKey: false, hãy ghi đè preset bằng một sessionKey tĩnh thay vì mặc định dạng mẫu.

{
  hooks: {
    gmail: {
      account: "openclaw@gmail.com",
      topic: "projects/<project-id>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "shared-push-token",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
      serve: { bind: "127.0.0.1", port: 8788, path: "/" },
      tailscale: { mode: "funnel", path: "/gmail-pubsub" },
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

• Gateway tự động khởi động gog gmail watch serve khi boot nếu được cấu hình. Đặt OPENCLAW_SKIP_GMAIL_WATCHER=1 để tắt.
• Không chạy một gog gmail watch serve riêng bên cạnh Gateway.

​

Máy chủ Plugin Canvas

{
  plugins: {
    entries: {
      canvas: {
        config: {
          host: {
            root: "~/.openclaw/workspace/canvas",
            liveReload: true,
            // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1
          },
        },
      },
    },
  },
}

• Phục vụ HTML/CSS/JS và A2UI mà agent có thể chỉnh sửa qua HTTP dưới cổng Gateway:
  • http://<gateway-host>:<gateway.port>/__openclaw__/canvas/
  • http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/
• Chỉ cục bộ: giữ gateway.bind: "loopback" (mặc định).
• Bind không phải loopback: các route canvas yêu cầu xác thực Gateway (token/password/trusted-proxy), giống như các bề mặt HTTP Gateway khác.
• Node WebViews thường không gửi header xác thực; sau khi một node được ghép nối và kết nối, Gateway quảng bá các URL capability theo phạm vi node để truy cập canvas/A2UI.
• URL capability được ràng buộc với phiên WS node đang hoạt động và hết hạn nhanh. Không dùng fallback dựa trên IP.
• Chèn client tải lại trực tiếp vào HTML được phục vụ.
• Tự động tạo index.html khởi đầu khi trống.
• Cũng phục vụ A2UI tại /__openclaw__/a2ui/.
• Thay đổi yêu cầu khởi động lại gateway.
• Tắt tải lại trực tiếp cho thư mục lớn hoặc lỗi EMFILE.

​

Khám phá

​

mDNS (Bonjour)

{
  discovery: {
    mdns: {
      mode: "minimal", // minimal | full | off
    },
  },
}

• minimal (mặc định khi Plugin bonjour đi kèm được bật): bỏ qua cliPath + sshPort khỏi bản ghi TXT.
• full: bao gồm cliPath + sshPort; quảng bá multicast LAN vẫn yêu cầu bật Plugin bonjour đi kèm.
• off: chặn quảng bá multicast LAN mà không thay đổi trạng thái bật Plugin.
• Plugin bonjour đi kèm tự động khởi động trên máy chủ macOS và là tùy chọn bật trên Linux, Windows, và các triển khai Gateway trong container.
• Tên máy chủ mặc định là hostname hệ thống khi đó là nhãn DNS hợp lệ, nếu không sẽ dùng openclaw. Ghi đè bằng OPENCLAW_MDNS_HOSTNAME.

​

Diện rộng (DNS-SD)

{
  discovery: {
    wideArea: { enabled: true },
  },
}

​

Môi trường

​

env (biến môi trường inline)

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

• Biến môi trường inline chỉ được áp dụng nếu môi trường tiến trình thiếu khóa đó.
• Tệp .env: CWD .env + ~/.openclaw/.env (không tệp nào ghi đè biến hiện có).
• shellEnv: nhập các khóa dự kiến còn thiếu từ hồ sơ shell đăng nhập của bạn.
• Xem Môi trường để biết đầy đủ thứ tự ưu tiên.

​

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

{
  gateway: {
    auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" },
  },
}

• Chỉ khớp tên viết hoa: [A-Z_][A-Z0-9_]*.
• Biến thiếu/rỗng sẽ gây lỗi khi tải cấu hình.
• Thoát bằng $${VAR} để có literal ${VAR}.
• Hoạt động với $include.

​

Bí mật

​

SecretRef

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

• Mẫu provider: ^[a-z][a-z0-9_-]{0,63}$
• Mẫu id source: "env": ^[A-Z][A-Z0-9_]{0,127}$
• id source: "file": con trỏ JSON tuyệt đối (ví dụ "/providers/openai/apiKey")
• Mẫu id source: "exec": ^[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}$ (hỗ trợ selector kiểu AWS secret#json_key)
• id source: "exec" không được chứa các đoạn đường dẫn phân tách bằng dấu gạch chéo là . hoặc .. (ví dụ a/../b bị từ chối)

​

Bề mặt thông tin xác thực được hỗ trợ

• Ma trận chuẩn: Bề mặt thông tin xác thực SecretRef
• secrets apply nhắm đến các đường dẫn thông tin xác thực openclaw.json được hỗ trợ.
• Tham chiếu auth-profiles.json được bao gồm trong phân giải thời gian chạy và phạm vi kiểm tra.

​

Cấu hình nhà cung cấp bí mật

{
  secrets: {
    providers: {
      default: { source: "env" }, // optional explicit env provider
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json",
        timeoutMs: 5000,
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        passEnv: ["PATH", "VAULT_ADDR"],
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
  },
}

• Nhà cung cấp file hỗ trợ mode: "json" và mode: "singleValue" (id phải là "value" trong chế độ singleValue).
• Đường dẫn nhà cung cấp file và exec fail closed khi không thể xác minh Windows ACL. Chỉ đặt allowInsecurePath: true cho các đường dẫn đáng tin cậy không thể xác minh.
• Nhà cung cấp exec yêu cầu đường dẫn command tuyệt đối và dùng payload giao thức trên stdin/stdout.
• Theo mặc định, đường dẫn lệnh symlink bị từ chối. Đặt allowSymlinkCommand: true để cho phép đường dẫn symlink trong khi xác thực đường dẫn đích đã phân giải.
• Nếu cấu hình trustedDirs, kiểm tra thư mục đáng tin cậy áp dụng cho đường dẫn đích đã phân giải.
• Môi trường tiến trình con exec mặc định là tối thiểu; truyền rõ ràng các biến cần thiết bằng passEnv.
• Tham chiếu bí mật được phân giải tại thời điểm kích hoạt vào một snapshot trong bộ nhớ, sau đó các đường dẫn yêu cầu chỉ đọc snapshot đó.
• Lọc bề mặt hoạt động được áp dụng trong quá trình kích hoạt: tham chiếu chưa phân giải trên các bề mặt đã bật làm lỗi khởi động/tải lại, trong khi bề mặt không hoạt động được bỏ qua kèm chẩn đoán.

​

Lưu trữ xác thực

{
  auth: {
    profiles: {
      "anthropic:default": { provider: "anthropic", mode: "api_key" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
      "openai:personal": { provider: "openai", mode: "oauth" },
    },
    order: {
      anthropic: ["anthropic:default", "anthropic:work"],
      openai: ["openai:personal"],
    },
  },
}

• Hồ sơ theo từng tác nhân được lưu tại <agentDir>/auth-profiles.json.
• auth-profiles.json hỗ trợ tham chiếu ở cấp giá trị (keyRef cho api_key, tokenRef cho token) cho các chế độ thông tin xác thực tĩnh.
• Các ánh xạ auth-profiles.json phẳng cũ như { "provider": { "apiKey": "..." } } không phải là định dạng runtime; openclaw doctor --fix ghi lại chúng thành hồ sơ API-key provider:default chuẩn với bản sao lưu .legacy-flat.*.bak.
• Hồ sơ chế độ OAuth (auth.profiles.<id>.mode = "oauth") không hỗ trợ thông tin xác thực hồ sơ xác thực dựa trên SecretRef.
• Thông tin xác thực runtime tĩnh đến từ các snapshot đã phân giải trong bộ nhớ; các mục auth.json tĩnh cũ sẽ được xóa sạch khi được phát hiện.
• Các bản nhập OAuth cũ từ ~/.openclaw/credentials/oauth.json.
• Xem OAuth.
• Hành vi runtime của bí mật và công cụ audit/configure/apply: Quản lý bí mật.

​

auth.cooldowns

{
  auth: {
    cooldowns: {
      billingBackoffHours: 5,
      billingBackoffHoursByProvider: { anthropic: 3, openai: 8 },
      billingMaxHours: 24,
      authPermanentBackoffMinutes: 10,
      authPermanentMaxMinutes: 60,
      failureWindowHours: 24,
      overloadedProfileRotations: 1,
      overloadedBackoffMs: 0,
      rateLimitedProfileRotations: 1,
    },
  },
}

• billingBackoffHours: thời gian backoff cơ sở tính bằng giờ khi hồ sơ thất bại do lỗi thanh toán/không đủ tín dụng thực sự (mặc định: 5). Văn bản thanh toán rõ ràng vẫn có thể rơi vào đây ngay cả trên phản hồi 401/403, nhưng các bộ khớp văn bản riêng theo nhà cung cấp vẫn chỉ giới hạn trong nhà cung cấp sở hữu chúng (ví dụ OpenRouter Key limit exceeded). HTTP 402 có thể thử lại cho cửa sổ sử dụng hoặc thông báo giới hạn chi tiêu của tổ chức/workspace vẫn nằm trong đường dẫn rate_limit thay vào đó.
• billingBackoffHoursByProvider: các ghi đè tùy chọn theo từng nhà cung cấp cho số giờ backoff thanh toán.
• billingMaxHours: giới hạn tính bằng giờ cho tăng trưởng lũy thừa của backoff thanh toán (mặc định: 24).
• authPermanentBackoffMinutes: thời gian backoff cơ sở tính bằng phút cho các lỗi auth_permanent có độ tin cậy cao (mặc định: 10).
• authPermanentMaxMinutes: giới hạn tính bằng phút cho tăng trưởng backoff auth_permanent (mặc định: 60).
• failureWindowHours: cửa sổ trượt tính bằng giờ dùng cho bộ đếm backoff (mặc định: 24).
• overloadedProfileRotations: số lần xoay vòng hồ sơ xác thực cùng nhà cung cấp tối đa cho lỗi quá tải trước khi chuyển sang phương án dự phòng mô hình (mặc định: 1). Các dạng nhà cung cấp bận như ModelNotReadyException rơi vào đây.
• overloadedBackoffMs: độ trễ cố định trước khi thử lại một vòng xoay nhà cung cấp/hồ sơ quá tải (mặc định: 0).
• rateLimitedProfileRotations: số lần xoay vòng hồ sơ xác thực cùng nhà cung cấp tối đa cho lỗi giới hạn tốc độ trước khi chuyển sang phương án dự phòng mô hình (mặc định: 1). Nhóm giới hạn tốc độ đó bao gồm văn bản dạng nhà cung cấp như Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, và resource exhausted.

​

Ghi nhật ký

{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty", // pretty | compact | json
    redactSensitive: "tools", // off | tools
    redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],
  },
}

• Tệp nhật ký mặc định: /tmp/openclaw/openclaw-YYYY-MM-DD.log.
• Đặt logging.file cho một đường dẫn ổn định.
• consoleLevel tăng lên debug khi dùng --verbose.
• maxFileBytes: kích thước tệp nhật ký đang hoạt động tối đa tính bằng byte trước khi xoay vòng (số nguyên dương; mặc định: 104857600 = 100 MB). OpenClaw giữ tối đa năm bản lưu trữ được đánh số bên cạnh tệp đang hoạt động.
• redactSensitive / redactPatterns: che dữ liệu theo nỗ lực tốt nhất cho đầu ra console, nhật ký tệp, bản ghi nhật ký OTLP, và văn bản transcript phiên được lưu bền vững. redactSensitive: "off" chỉ tắt chính sách nhật ký/transcript chung này; các bề mặt an toàn UI/công cụ/chẩn đoán vẫn che bí mật trước khi phát ra.

​

Chẩn đoán

{
  diagnostics: {
    enabled: true,
    flags: ["telegram.*"],
    stuckSessionWarnMs: 30000,
    stuckSessionAbortMs: 300000,
    memoryPressureSnapshot: false,

    otel: {
      enabled: false,
      endpoint: "https://otel-collector.example.com:4318",
      tracesEndpoint: "https://traces.example.com/v1/traces",
      metricsEndpoint: "https://metrics.example.com/v1/metrics",
      logsEndpoint: "https://logs.example.com/v1/logs",
      protocol: "http/protobuf", // http/protobuf | grpc
      headers: { "x-tenant-id": "my-org" },
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: false,
      logsExporter: "otlp",
      sampleRate: 1.0,
      flushIntervalMs: 5000,
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: false,
        toolDefinitions: false,
      },
    },

    cacheTrace: {
      enabled: false,
      filePath: "~/.openclaw/logs/cache-trace.jsonl",
      includeMessages: true,
      includePrompt: true,
      includeSystem: true,
    },
  },
}

• enabled: công tắc chính cho đầu ra instrumentation (mặc định: true).
• flags: mảng các chuỗi cờ bật đầu ra nhật ký có mục tiêu (hỗ trợ ký tự đại diện như "telegram.*" hoặc "*").
• stuckSessionWarnMs: ngưỡng tuổi không tiến triển tính bằng ms để phân loại các phiên xử lý chạy lâu là session.long_running, session.stalled, hoặc session.stuck. Phản hồi, công cụ, trạng thái, khối, và tiến trình ACP đặt lại bộ đếm giờ; chẩn đoán session.stuck lặp lại sẽ back off khi không thay đổi.
• stuckSessionAbortMs: ngưỡng tuổi không tiến triển tính bằng ms trước khi công việc đang hoạt động bị kẹt đủ điều kiện có thể được abort-drain để phục hồi. Khi chưa đặt, OpenClaw dùng cửa sổ chạy nhúng mở rộng an toàn hơn, ít nhất 5 phút và gấp 3 lần stuckSessionWarnMs.
• memoryPressureSnapshot: ghi lại snapshot ổn định đã được che dữ liệu trước OOM khi áp lực bộ nhớ đạt critical (mặc định: false). Đặt thành true để thêm thao tác quét/ghi tệp gói ổn định trong khi vẫn giữ các sự kiện áp lực bộ nhớ bình thường.
• otel.enabled: bật pipeline xuất OpenTelemetry (mặc định: false). Để xem cấu hình đầy đủ, catalog tín hiệu, và mô hình quyền riêng tư, xem xuất OpenTelemetry.
• otel.endpoint: URL collector cho xuất OTel.
• otel.tracesEndpoint / otel.metricsEndpoint / otel.logsEndpoint: các endpoint OTLP tùy chọn riêng theo tín hiệu. Khi được đặt, chúng ghi đè otel.endpoint chỉ cho tín hiệu đó.
• otel.protocol: "http/protobuf" (mặc định) hoặc "grpc".
• otel.headers: các header metadata HTTP/gRPC bổ sung được gửi cùng yêu cầu xuất OTel.
• otel.serviceName: tên dịch vụ cho thuộc tính tài nguyên.
• otel.traces / otel.metrics / otel.logs: bật xuất trace, metric, hoặc nhật ký.
• otel.logsExporter: đích xuất nhật ký: "otlp" (mặc định), "stdout" cho một đối tượng JSON trên mỗi dòng stdout, hoặc "both".
• otel.sampleRate: tỷ lệ lấy mẫu trace 0-1.
• otel.flushIntervalMs: khoảng thời gian flush telemetry định kỳ tính bằng ms.
• otel.captureContent: tùy chọn bật ghi lại nội dung thô cho thuộc tính span OTEL. Mặc định là tắt. Boolean true ghi lại nội dung tin nhắn/công cụ không thuộc hệ thống; dạng đối tượng cho phép bạn bật rõ ràng inputMessages, outputMessages, toolInputs, toolOutputs, systemPrompt, và toolDefinitions.
• OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental: công tắc môi trường cho dạng span suy luận GenAI thử nghiệm mới nhất, bao gồm tên span {gen_ai.operation.name} {gen_ai.request.model}, loại span CLIENT, và gen_ai.provider.name thay cho gen_ai.system cũ. Theo mặc định, các span giữ openclaw.model.call và gen_ai.system để tương thích; metric GenAI dùng các thuộc tính ngữ nghĩa có giới hạn.
• OPENCLAW_OTEL_PRELOADED=1: công tắc môi trường cho host đã đăng ký một SDK OpenTelemetry toàn cục. Khi đó OpenClaw bỏ qua khởi động/tắt SDK do Plugin sở hữu trong khi vẫn giữ các listener chẩn đoán hoạt động.
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, và OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: các biến môi trường endpoint riêng theo tín hiệu được dùng khi khóa cấu hình tương ứng chưa được đặt.
• cacheTrace.enabled: ghi nhật ký snapshot trace cache cho các lượt chạy nhúng (mặc định: false).
• cacheTrace.filePath: đường dẫn đầu ra cho cache trace JSONL (mặc định: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl).
• cacheTrace.includeMessages / includePrompt / includeSystem: kiểm soát nội dung được đưa vào đầu ra cache trace (tất cả mặc định: true).

​

Cập nhật

{
  update: {
    channel: "stable", // stable | beta | dev
    checkOnStart: true,

    auto: {
      enabled: false,
      stableDelayHours: 6,
      stableJitterHours: 12,
      betaCheckIntervalHours: 1,
    },
  },
}

• channel: kênh phát hành cho bản cài npm/git - "stable", "beta", hoặc "dev".
• checkOnStart: kiểm tra bản cập nhật npm khi Gateway khởi động (mặc định: true).
• auto.enabled: bật tự động cập nhật nền cho các bản cài gói (mặc định: false).
• auto.stableDelayHours: độ trễ tối thiểu tính bằng giờ trước khi tự động áp dụng kênh stable (mặc định: 6; tối đa: 168).
• auto.stableJitterHours: cửa sổ phân tán triển khai bổ sung cho kênh stable tính bằng giờ (mặc định: 12; tối đa: 168).
• auto.betaCheckIntervalHours: tần suất chạy kiểm tra kênh beta tính bằng giờ (mặc định: 1; tối đa: 24).

​

ACP

{
  acp: {
    enabled: true,
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "main",
    allowedAgents: ["main", "ops"],
    maxConcurrentSessions: 10,

    stream: {
      coalesceIdleMs: 50,
      maxChunkChars: 1000,
      repeatSuppression: true,
      deliveryMode: "live", // live | final_only
      hiddenBoundarySeparator: "paragraph", // none | space | newline | paragraph
      maxOutputChars: 50000,
      maxSessionUpdateChars: 500,
    },

    runtime: {
      ttlMinutes: 30,
    },
  },
}

• enabled: cổng tính năng ACP toàn cục (mặc định: true; đặt false để ẩn dispatch ACP và các affordance spawn).
• dispatch.enabled: cổng độc lập cho dispatch lượt phiên ACP (mặc định: true). Đặt false để giữ lệnh ACP khả dụng trong khi chặn thực thi.
• backend: id backend runtime ACP mặc định (phải khớp với một Plugin runtime ACP đã đăng ký). Cài đặt Plugin backend trước, và nếu plugins.allow được đặt, hãy bao gồm id Plugin backend (ví dụ acpx) nếu không backend ACP sẽ không tải.
• defaultAgent: id tác nhân mục tiêu ACP dự phòng khi các lần spawn không chỉ định mục tiêu rõ ràng.
• allowedAgents: danh sách cho phép các id tác nhân được phép dùng cho phiên runtime ACP; rỗng nghĩa là không có hạn chế bổ sung.
• maxConcurrentSessions: số phiên ACP đang hoạt động đồng thời tối đa.
• stream.coalesceIdleMs: cửa sổ flush khi rảnh tính bằng ms cho văn bản được stream.
• stream.maxChunkChars: kích thước chunk tối đa trước khi tách phép chiếu khối được stream.
• stream.repeatSuppression: chặn các dòng trạng thái/công cụ lặp lại theo từng lượt (mặc định: true).
• stream.deliveryMode: "live" stream tăng dần; "final_only" đệm cho đến các sự kiện kết thúc lượt.
• stream.hiddenBoundarySeparator: dấu phân tách trước văn bản hiển thị sau các sự kiện công cụ ẩn (mặc định: "paragraph").
• stream.maxOutputChars: số ký tự đầu ra trợ lý tối đa được chiếu mỗi lượt ACP.
• stream.maxSessionUpdateChars: số ký tự tối đa cho các dòng trạng thái/cập nhật ACP được chiếu.
• stream.tagVisibility: bản ghi tên tag tới các ghi đè khả năng hiển thị boolean cho sự kiện được stream.
• runtime.ttlMinutes: TTL khi rảnh tính bằng phút cho worker phiên ACP trước khi đủ điều kiện dọn dẹp.
• runtime.installCommand: lệnh cài đặt tùy chọn để chạy khi bootstrap môi trường runtime ACP.

​

CLI

{
  cli: {
    banner: {
      taglineMode: "off", // random | default | off
    },
  },
}

• cli.banner.taglineMode kiểm soát kiểu khẩu hiệu của banner:
  • "random" (mặc định): xoay vòng các khẩu hiệu hài hước/theo mùa.
  • "default": khẩu hiệu trung tính cố định (All your chats, one OpenClaw.).
  • "off": không có văn bản khẩu hiệu (tiêu đề/phiên bản banner vẫn hiển thị).
• Để ẩn toàn bộ banner (không chỉ khẩu hiệu), đặt env OPENCLAW_HIDE_BANNER=1.

​

Trình hướng dẫn

{
  wizard: {
    lastRunAt: "2026-01-01T00:00:00.000Z",
    lastRunVersion: "2026.1.4",
    lastRunCommit: "abc1234",
    lastRunCommand: "configure",
    lastRunMode: "local",
    securityAcknowledgedAt: "2026-01-01T00:00:00.000Z",
  },
}

​

Danh tính

​

Cầu nối (cũ, đã gỡ bỏ)

{
  "bridge": {
    "enabled": true,
    "port": 18790,
    "bind": "tailnet",
    "tls": {
      "enabled": true,
      "autoGenerate": true
    }
  }
}

​

Cron

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 8, // default; cron dispatch + isolated cron agent-turn execution
    webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs
    webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth
    sessionRetention: "24h", // duration string or false
    runLog: {
      maxBytes: "2mb", // default 2_000_000 bytes
      keepLines: 2000, // default 2000
    },
  },
}

• sessionRetention: thời lượng giữ lại các phiên chạy cron cô lập đã hoàn tất trước khi dọn khỏi sessions.json. Cũng kiểm soát việc dọn dẹp các bản ghi cron đã xóa được lưu trữ. Mặc định: 24h; đặt false để tắt.
• runLog.maxBytes: được chấp nhận để tương thích với nhật ký chạy cron cũ dựa trên tệp. Mặc định: 2_000_000 byte.
• runLog.keepLines: các hàng lịch sử chạy SQLite mới nhất được giữ lại cho mỗi job. Mặc định: 2000.
• webhookToken: bearer token dùng để gửi POST Webhook Cron (delivery.mode = "webhook"), nếu bỏ qua thì không gửi header xác thực.
• webhook: URL Webhook dự phòng cũ đã ngừng dùng (http/https), được openclaw doctor --fix dùng để di chuyển các job đã lưu vẫn có notify: true; khi chạy, việc gửi dùng delivery.mode="webhook" theo từng job cùng với delivery.to, hoặc delivery.completionDestination khi giữ lại gửi thông báo.

​

cron.retry

{
  cron: {
    retry: {
      maxAttempts: 3,
      backoffMs: [30000, 60000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"],
    },
  },
}

• maxAttempts: số lần thử lại tối đa cho job Cron khi gặp lỗi tạm thời (mặc định: 3; phạm vi: 0-10).
• backoffMs: mảng độ trễ backoff tính bằng ms cho mỗi lần thử lại (mặc định: [30000, 60000, 300000]; 1-10 mục).
• retryOn: các loại lỗi kích hoạt thử lại - "rate_limit", "overloaded", "network", "timeout", "server_error". Bỏ qua để thử lại tất cả các loại tạm thời.

​

cron.failureAlert

{
  cron: {
    failureAlert: {
      enabled: false,
      after: 3,
      cooldownMs: 3600000,
      includeSkipped: false,
      mode: "announce",
      accountId: "main",
    },
  },
}

• enabled: bật cảnh báo lỗi cho job Cron (mặc định: false).
• after: số lỗi liên tiếp trước khi phát cảnh báo (số nguyên dương, tối thiểu: 1).
• cooldownMs: số mili giây tối thiểu giữa các cảnh báo lặp lại cho cùng một job (số nguyên không âm).
• includeSkipped: tính các lần chạy bị bỏ qua liên tiếp vào ngưỡng cảnh báo (mặc định: false). Các lần chạy bị bỏ qua được theo dõi riêng và không ảnh hưởng đến backoff lỗi thực thi.
• mode: chế độ gửi - "announce" gửi qua tin nhắn kênh; "webhook" đăng tới Webhook đã cấu hình.
• accountId: id tài khoản hoặc kênh tùy chọn để giới hạn phạm vi gửi cảnh báo.

​

cron.failureDestination

{
  cron: {
    failureDestination: {
      mode: "announce",
      channel: "last",
      to: "channel:C1234567890",
      accountId: "main",
    },
  },
}

• Đích mặc định cho thông báo lỗi Cron trên tất cả job.
• mode: "announce" hoặc "webhook"; mặc định là "announce" khi có đủ dữ liệu đích.
• channel: ghi đè kênh cho gửi thông báo. "last" dùng lại kênh gửi đã biết gần nhất.
• to: đích thông báo rõ ràng hoặc URL Webhook. Bắt buộc cho chế độ Webhook.
• accountId: ghi đè tài khoản tùy chọn cho việc gửi.
• delivery.failureDestination theo từng job ghi đè mặc định toàn cục này.
• Khi cả đích lỗi toàn cục lẫn theo từng job đều không được đặt, các job đã gửi qua announce sẽ quay về đích thông báo chính đó khi lỗi.
• delivery.failureDestination chỉ được hỗ trợ cho job sessionTarget="isolated" trừ khi delivery.mode chính của job là "webhook".

​

Biến mẫu mô hình media

​

Include cấu hình ($include)

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

• Một tệp: thay thế đối tượng chứa nó.
• Mảng tệp: được deep-merge theo thứ tự (tệp sau ghi đè tệp trước).
• Khóa cùng cấp: được hợp nhất sau include (ghi đè các giá trị được include).
• Include lồng nhau: sâu tối đa 10 cấp.
• Đường dẫn: được phân giải tương đối với tệp include, nhưng phải nằm trong thư mục cấu hình cấp cao nhất (dirname của openclaw.json). Dạng tuyệt đối/../ chỉ được phép khi vẫn phân giải nằm trong ranh giới đó. Đường dẫn không được chứa byte null và phải ngắn hơn nghiêm ngặt 4096 ký tự trước và sau khi phân giải.
• Các thao tác ghi do OpenClaw sở hữu chỉ thay đổi một mục cấp cao nhất được hỗ trợ bởi include một tệp sẽ ghi xuyên qua vào tệp được include đó. Ví dụ, plugins install cập nhật plugins: { $include: "./plugins.json5" } trong plugins.json5 và giữ nguyên openclaw.json.
• Include gốc, mảng include và include có ghi đè cùng cấp là chỉ đọc đối với các thao tác ghi do OpenClaw sở hữu; các thao tác ghi đó fail closed thay vì làm phẳng cấu hình.
• Lỗi: thông báo rõ ràng cho tệp bị thiếu, lỗi phân tích cú pháp, include vòng, định dạng đường dẫn không hợp lệ và độ dài quá mức.

​

Liên quan

• Cấu hình
• Ví dụ cấu hình