Cấu hình — tác nhân

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Mặc định của tác tử

​

agents.defaults.workspace

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

​

agents.defaults.repoRoot

{
  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },
}

​

agents.defaults.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
    ],
  },
}

• Bỏ qua agents.defaults.skills để mặc định không giới hạn Skills.
• Bỏ qua agents.list[].skills để kế thừa các giá trị mặc định.
• Đặt agents.list[].skills: [] để không có Skills.
• Danh sách agents.list[].skills không rỗng là tập cuối cùng cho tác tử đó; nó không hợp nhất với các giá trị mặc định.

​

agents.defaults.skipBootstrap

{
  agents: { defaults: { skipBootstrap: true } },
}

​

agents.defaults.contextInjection

• "continuation-skip": các lượt tiếp tục an toàn (sau một phản hồi trợ lý đã hoàn tất) bỏ qua việc chèn lại bootstrap workspace, giúp giảm kích thước lời nhắc. Các lần chạy Heartbeat và lần thử lại sau Compaction vẫn dựng lại ngữ cảnh.
• "never": tắt bootstrap workspace và chèn tệp ngữ cảnh ở mọi lượt. Chỉ dùng tùy chọn này cho các tác tử tự quản lý toàn bộ vòng đời lời nhắc của chúng (công cụ ngữ cảnh tùy chỉnh, runtime gốc tự xây dựng ngữ cảnh, hoặc quy trình chuyên biệt không dùng bootstrap). Các lượt Heartbeat và phục hồi sau Compaction cũng bỏ qua việc chèn.

{
  agents: { defaults: { contextInjection: "continuation-skip" } },
}

​

agents.defaults.bootstrapMaxChars

{
  agents: { defaults: { bootstrapMaxChars: 12000 } },
}

​

agents.defaults.bootstrapTotalMaxChars

{
  agents: { defaults: { bootstrapTotalMaxChars: 60000 } },
}

​

agents.defaults.bootstrapPromptTruncationWarning

• "off": không bao giờ chèn văn bản cảnh báo vào lời nhắc hệ thống.
• "once": chèn cảnh báo một lần cho mỗi chữ ký cắt ngắn duy nhất (khuyến nghị).
• "always": chèn cảnh báo ở mọi lần chạy khi có cắt ngắn.

{
  agents: { defaults: { bootstrapPromptTruncationWarning: "once" } }, // off | once | always
}

​

Bản đồ sở hữu ngân sách ngữ cảnh

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: chèn bootstrap workspace thông thường.
• agents.defaults.startupContext.*: phần mở đầu chạy mô hình một lần khi đặt lại/khởi động, bao gồm các tệp memory/*.md hằng ngày gần đây. Các lệnh chat trần /new và /reset được xác nhận mà không gọi mô hình.
• skills.limits.*: danh sách Skills thu gọn được chèn vào lời nhắc hệ thống.
• agents.defaults.contextLimits.*: các trích đoạn runtime có giới hạn và các khối do runtime sở hữu được chèn.
• memory.qmd.limits.*: định cỡ đoạn trích tìm kiếm bộ nhớ được lập chỉ mục và phần chèn.

• agents.list[].skillsLimits.maxSkillsPromptChars
• agents.list[].contextLimits.*

​

agents.defaults.startupContext

{
  agents: {
    defaults: {
      startupContext: {
        enabled: true,
        applyOn: ["new", "reset"],
        dailyMemoryDays: 2,
        maxFileBytes: 16384,
        maxFileChars: 1200,
        maxTotalChars: 2800,
      },
    },
  },
}

​

agents.defaults.contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        memoryGetDefaultLines: 120,
        toolResultMaxChars: 16000,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

• memoryGetMaxChars: giới hạn trích đoạn memory_get mặc định trước khi thêm siêu dữ liệu cắt ngắn và thông báo tiếp tục.
• memoryGetDefaultLines: cửa sổ dòng memory_get mặc định khi bỏ qua lines.
• toolResultMaxChars: giới hạn kết quả công cụ trực tiếp dùng cho kết quả được lưu bền vững và phục hồi khi tràn.
• postCompactionMaxChars: giới hạn trích đoạn AGENTS.md dùng trong quá trình chèn làm mới sau Compaction.

​

agents.list[].contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        toolResultMaxChars: 16000,
      },
    },
    list: [
      {
        id: "tiny-local",
        contextLimits: {
          memoryGetMaxChars: 6000,
          toolResultMaxChars: 8000,
        },
      },
    ],
  },
}

​

skills.limits.maxSkillsPromptChars

{
  skills: {
    limits: {
      maxSkillsPromptChars: 18000,
    },
  },
}

​

agents.list[].skillsLimits.maxSkillsPromptChars

{
  agents: {
    list: [
      {
        id: "tiny-local",
        skillsLimits: {
          maxSkillsPromptChars: 6000,
        },
      },
    ],
  },
}

​

agents.defaults.imageMaxDimensionPx

{
  agents: { defaults: { imageMaxDimensionPx: 1200 } },
}

​

agents.defaults.userTimezone

{
  agents: { defaults: { userTimezone: "America/Chicago" } },
}

​

agents.defaults.timeFormat

{
  agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24
}

​

agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        fallbacks: ["google/gemini-3.1-flash-image-preview"],
      },
      videoGenerationModel: {
        primary: "qwen/wan2.6-t2v",
        fallbacks: ["qwen/wan2.6-i2v"],
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
      params: { cacheRetention: "long" }, // global default provider params
      agentRuntime: {
        id: "pi", // pi | auto | registered harness id, e.g. codex
        fallback: "pi", // pi | none
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      reasoningDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: chấp nhận chuỗi ("provider/model") hoặc đối tượng ({ primary, fallbacks }).
  • Dạng chuỗi chỉ đặt mô hình chính.
  • Dạng đối tượng đặt mô hình chính cùng các mô hình chuyển đổi dự phòng có thứ tự.
• imageModel: chấp nhận chuỗi ("provider/model") hoặc đối tượng ({ primary, fallbacks }).
  • Được đường dẫn công cụ image dùng làm cấu hình mô hình thị giác.
  • Cũng được dùng làm định tuyến dự phòng khi mô hình đã chọn/mặc định không thể nhận đầu vào hình ảnh.
  • Ưu tiên tham chiếu provider/model rõ ràng. ID trần được chấp nhận để tương thích; nếu một ID trần khớp duy nhất với một mục đã cấu hình có khả năng xử lý hình ảnh trong models.providers.*.models, OpenClaw chuẩn hóa nó về nhà cung cấp đó. Các kết quả khớp đã cấu hình nhưng không rõ ràng cần tiền tố nhà cung cấp rõ ràng.
• imageGenerationModel: chấp nhận chuỗi ("provider/model") hoặc đối tượng ({ primary, fallbacks }).
  • Được dùng bởi năng lực tạo hình ảnh dùng chung và mọi bề mặt công cụ/plugin trong tương lai tạo ra hình ảnh.
  • Giá trị điển hình: google/gemini-3.1-flash-image-preview cho tạo hình ảnh Gemini gốc, fal/fal-ai/flux/dev cho fal, openai/gpt-image-2 cho OpenAI Images, hoặc openai/gpt-image-1.5 cho đầu ra OpenAI PNG/WebP nền trong suốt.
  • Nếu bạn chọn trực tiếp nhà cung cấp/mô hình, cũng hãy cấu hình xác thực nhà cung cấp tương ứng (ví dụ GEMINI_API_KEY hoặc GOOGLE_API_KEY cho google/*, OPENAI_API_KEY hoặc OpenAI Codex OAuth cho openai/gpt-image-2 / openai/gpt-image-1.5, FAL_KEY cho fal/*).
  • Nếu bỏ qua, image_generate vẫn có thể suy luận mặc định nhà cung cấp được hỗ trợ bởi xác thực. Nó thử nhà cung cấp mặc định hiện tại trước, rồi các nhà cung cấp tạo hình ảnh đã đăng ký còn lại theo thứ tự ID nhà cung cấp.
• musicGenerationModel: chấp nhận chuỗi ("provider/model") hoặc đối tượng ({ primary, fallbacks }).
  • Được dùng bởi năng lực tạo nhạc dùng chung và công cụ tích hợp sẵn music_generate.
  • Giá trị điển hình: google/lyria-3-clip-preview, google/lyria-3-pro-preview, hoặc minimax/music-2.6.
  • Nếu bỏ qua, music_generate vẫn có thể suy luận mặc định nhà cung cấp được hỗ trợ bởi xác thực. Nó thử nhà cung cấp mặc định hiện tại trước, rồi các nhà cung cấp tạo nhạc đã đăng ký còn lại theo thứ tự ID nhà cung cấp.
  • Nếu bạn chọn trực tiếp nhà cung cấp/mô hình, cũng hãy cấu hình xác thực/khóa API nhà cung cấp tương ứng.
• videoGenerationModel: chấp nhận chuỗi ("provider/model") hoặc đối tượng ({ primary, fallbacks }).
  • Được dùng bởi năng lực tạo video dùng chung và công cụ tích hợp sẵn video_generate.
  • Giá trị điển hình: qwen/wan2.6-t2v, qwen/wan2.6-i2v, qwen/wan2.6-r2v, qwen/wan2.6-r2v-flash, hoặc qwen/wan2.7-r2v.
  • Nếu bỏ qua, video_generate vẫn có thể suy luận mặc định nhà cung cấp được hỗ trợ bởi xác thực. Nó thử nhà cung cấp mặc định hiện tại trước, rồi các nhà cung cấp tạo video đã đăng ký còn lại theo thứ tự ID nhà cung cấp.
  • Nếu bạn chọn trực tiếp nhà cung cấp/mô hình, cũng hãy cấu hình xác thực/khóa API nhà cung cấp tương ứng.
  • Nhà cung cấp tạo video Qwen đi kèm hỗ trợ tối đa 1 video đầu ra, 1 hình ảnh đầu vào, 4 video đầu vào, thời lượng 10 giây, và các tùy chọn cấp nhà cung cấp size, aspectRatio, resolution, audio, và watermark.
• pdfModel: chấp nhận chuỗi ("provider/model") hoặc đối tượng ({ primary, fallbacks }).
  • Được công cụ pdf dùng để định tuyến mô hình.
  • Nếu bỏ qua, công cụ PDF dự phòng về imageModel, rồi đến mô hình phiên/mặc định đã phân giải.
• pdfMaxBytesMb: giới hạn kích thước PDF mặc định cho công cụ pdf khi maxBytesMb không được truyền lúc gọi.
• pdfMaxPages: số trang tối đa mặc định được xét bởi chế độ dự phòng trích xuất trong công cụ pdf.
• verboseDefault: mức chi tiết mặc định cho tác tử. Giá trị: "off", "on", "full". Mặc định: "off".
• reasoningDefault: khả năng hiển thị suy luận mặc định cho tác tử. Giá trị: "off", "on", "stream". agents.list[].reasoningDefault theo từng tác tử ghi đè mặc định này. Các mặc định suy luận đã cấu hình chỉ được áp dụng cho chủ sở hữu, người gửi được ủy quyền, hoặc ngữ cảnh gateway quản trị viên vận hành khi không đặt ghi đè suy luận theo tin nhắn hoặc theo phiên.
• elevatedDefault: mức đầu ra nâng cao mặc định cho tác tử. Giá trị: "off", "on", "ask", "full". Mặc định: "on".
• model.primary: định dạng provider/model (ví dụ openai/gpt-5.5 cho truy cập bằng khóa API hoặc openai-codex/gpt-5.5 cho Codex OAuth). Nếu bạn bỏ qua nhà cung cấp, OpenClaw thử bí danh trước, rồi một kết quả khớp nhà cung cấp đã cấu hình duy nhất cho đúng ID mô hình đó, và chỉ sau đó mới dự phòng về nhà cung cấp mặc định đã cấu hình (hành vi tương thích đã lỗi thời, nên hãy ưu tiên provider/model rõ ràng). Nếu nhà cung cấp đó không còn cung cấp mô hình mặc định đã cấu hình, OpenClaw dự phòng về nhà cung cấp/mô hình đã cấu hình đầu tiên thay vì hiển thị một mặc định nhà cung cấp đã bị xóa và lỗi thời.
• models: danh mục mô hình đã cấu hình và danh sách cho phép cho /model. Mỗi mục có thể bao gồm alias (lối tắt) và params (đặc thù theo nhà cung cấp, ví dụ temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold, chat_template_kwargs, extra_body/extraBody).
  • Chỉnh sửa an toàn: dùng openclaw config set agents.defaults.models '<json>' --strict-json --merge để thêm mục. config set từ chối các thay thế sẽ xóa mục danh sách cho phép hiện có, trừ khi bạn truyền --replace.
  • Các luồng cấu hình/onboarding theo phạm vi nhà cung cấp hợp nhất các mô hình nhà cung cấp đã chọn vào bản đồ này và giữ nguyên các nhà cung cấp không liên quan đã được cấu hình.
  • Với các mô hình OpenAI Responses trực tiếp, compaction phía máy chủ được bật tự động. Dùng params.responsesServerCompaction: false để dừng chèn context_management, hoặc params.responsesCompactThreshold để ghi đè ngưỡng. Xem compaction phía máy chủ của OpenAI.
• params: tham số nhà cung cấp mặc định toàn cục được áp dụng cho tất cả mô hình. Đặt tại agents.defaults.params (ví dụ { cacheRetention: "long" }).
• Thứ tự ưu tiên hợp nhất params (cấu hình): agents.defaults.params (cơ sở toàn cục) bị agents.defaults.models["provider/model"].params (theo mô hình) ghi đè, rồi agents.list[].params (khớp ID tác tử) ghi đè theo khóa. Xem Lưu bộ nhớ đệm prompt để biết chi tiết.
• params.extra_body/params.extraBody: JSON truyền xuyên nâng cao được hợp nhất vào thân yêu cầu api: "openai-completions" cho proxy tương thích OpenAI. Nếu nó trùng với các khóa yêu cầu được tạo, phần thân bổ sung thắng; các tuyến completions không gốc vẫn loại bỏ store chỉ dành cho OpenAI sau đó.
• params.chat_template_kwargs: đối số mẫu trò chuyện tương thích vLLM/OpenAI được hợp nhất vào thân yêu cầu api: "openai-completions" cấp cao nhất. Với vllm/nemotron-3-* khi tắt thinking, plugin vLLM đi kèm tự động gửi enable_thinking: false và force_nonempty_content: true; chat_template_kwargs rõ ràng ghi đè mặc định được tạo, và extra_body.chat_template_kwargs vẫn có quyền ưu tiên cuối cùng. Với điều khiển thinking Qwen của vLLM, đặt params.qwenThinkingFormat thành "chat-template" hoặc "top-level" trên mục mô hình đó.
• compat.supportedReasoningEfforts: danh sách mức nỗ lực suy luận tương thích OpenAI theo từng mô hình. Bao gồm "xhigh" cho các endpoint tùy chỉnh thực sự chấp nhận nó; sau đó OpenClaw hiển thị /think xhigh trong menu lệnh, hàng phiên Gateway, xác thực bản vá phiên, xác thực CLI tác tử, và xác thực llm-task cho nhà cung cấp/mô hình đã cấu hình đó. Dùng compat.reasoningEffortMap khi backend cần một giá trị đặc thù nhà cung cấp cho một mức chuẩn.
• params.preserveThinking: tùy chọn chỉ dành cho Z.AI để bật giữ nguyên thinking. Khi bật và thinking đang bật, OpenClaw gửi thinking.clear_thinking: false và phát lại reasoning_content trước đó; xem thinking và thinking được giữ nguyên của Z.AI.
• agentRuntime: chính sách runtime tác tử cấp thấp mặc định. ID bị bỏ qua mặc định là OpenClaw Pi. Dùng id: "pi" để buộc dùng harness PI tích hợp sẵn, id: "auto" để cho các harness plugin đã đăng ký nhận các mô hình được hỗ trợ, một ID harness đã đăng ký như id: "codex", hoặc một bí danh backend CLI được hỗ trợ như id: "claude-cli". Đặt fallback: "none" để tắt dự phòng PI tự động. Các runtime plugin rõ ràng như codex mặc định đóng khi lỗi, trừ khi bạn đặt fallback: "pi" trong cùng phạm vi ghi đè. Giữ tham chiếu mô hình chuẩn hóa là provider/model; chọn Codex, Claude CLI, Gemini CLI, và các backend thực thi khác thông qua cấu hình runtime thay vì các tiền tố nhà cung cấp runtime cũ. Xem Runtime tác tử để biết điều này khác với lựa chọn nhà cung cấp/mô hình như thế nào.
• Các trình ghi cấu hình sửa đổi các trường này (ví dụ /models set, /models set-image, và các lệnh thêm/xóa dự phòng) lưu dạng đối tượng chuẩn hóa và giữ nguyên danh sách dự phòng hiện có khi có thể.
• maxConcurrent: số lần chạy tác tử song song tối đa giữa các phiên (mỗi phiên vẫn được tuần tự hóa). Mặc định: 4.

​

agents.defaults.agentRuntime

{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
        fallback: "none",
      },
    },
  },
}

• id: "auto", "pi", ID harness plugin đã đăng ký, hoặc bí danh backend CLI được hỗ trợ. Plugin Codex đi kèm đăng ký codex; plugin Anthropic đi kèm cung cấp backend CLI claude-cli.
• fallback: "pi" hoặc "none". Trong id: "auto", fallback bị bỏ qua mặc định là "pi" để cấu hình cũ vẫn có thể dùng PI khi không có harness plugin nào nhận một lần chạy. Trong chế độ runtime plugin rõ ràng, chẳng hạn id: "codex", fallback bị bỏ qua mặc định là "none" để harness bị thiếu sẽ thất bại thay vì âm thầm dùng PI. Ghi đè runtime không kế thừa fallback từ phạm vi rộng hơn; đặt fallback: "pi" cùng với runtime rõ ràng khi bạn cố ý muốn dự phòng tương thích đó. Lỗi harness plugin đã chọn luôn được hiển thị trực tiếp.
• Ghi đè môi trường: OPENCLAW_AGENT_RUNTIME=<id|auto|pi> ghi đè id; OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none ghi đè fallback cho tiến trình đó.
• Với các triển khai chỉ dùng Codex, đặt model: "openai/gpt-5.5" và agentRuntime.id: "codex". Bạn cũng có thể đặt rõ agentRuntime.fallback: "none" để dễ đọc; đó là mặc định cho runtime plugin rõ ràng.
• Với các triển khai Claude CLI, ưu tiên model: "anthropic/claude-opus-4-7" cùng với agentRuntime.id: "claude-cli". Tham chiếu mô hình cũ claude-cli/claude-opus-4-7 vẫn hoạt động để tương thích, nhưng cấu hình mới nên giữ lựa chọn nhà cung cấp/mô hình ở dạng chuẩn và đặt backend thực thi trong agentRuntime.id.
• Các khóa chính sách runtime cũ được openclaw doctor --fix viết lại thành agentRuntime.
• Lựa chọn harness được ghim theo ID phiên sau lần chạy nhúng đầu tiên. Thay đổi cấu hình/môi trường ảnh hưởng đến phiên mới hoặc phiên đặt lại, không ảnh hưởng đến bản ghi hiện có. Các phiên cũ có lịch sử bản ghi nhưng không có ghim đã ghi lại được xem là đã ghim PI. /status báo cáo runtime hiệu lực, ví dụ Runtime: OpenClaw Pi Default hoặc Runtime: OpenAI Codex.
• Điều này chỉ kiểm soát thực thi lượt tác tử văn bản. Tạo media, thị giác, PDF, nhạc, video, và TTS vẫn dùng cài đặt nhà cung cấp/mô hình của chúng.

​

agents.defaults.cliBackends

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          modelArg: "--model",
          sessionArg: "--session",
          sessionMode: "existing",
          systemPromptArg: "--system",
          // Or use systemPromptFileArg when the CLI accepts a prompt file flag.
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• Backend CLI ưu tiên văn bản; công cụ luôn bị tắt.
• Hỗ trợ phiên khi sessionArg được đặt.
• Hỗ trợ chuyển tiếp hình ảnh khi imageArg chấp nhận đường dẫn tệp.

​

agents.defaults.systemPromptOverride

{
  agents: {
    defaults: {
      systemPromptOverride: "You are a helpful assistant.",
    },
  },
}

​

agents.defaults.promptOverlays

{
  agents: {
    defaults: {
      promptOverlays: {
        gpt5: {
          personality: "friendly", // friendly | on | off
        },
      },
    },
  },
}

• "friendly" (mặc định) và "on" bật lớp phong cách tương tác thân thiện.
• "off" chỉ tắt lớp thân thiện; hợp đồng hành vi GPT-5 được gắn thẻ vẫn được bật.
• plugins.entries.openai.config.personality cũ vẫn được đọc khi thiết lập dùng chung này chưa được đặt.

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m disables
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt
        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
        skipWhenBusy: false, // default: false; true also waits for subagent/nested lanes
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | options: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        timeoutSeconds: 45,
      },
    },
  },
}

• every: chuỗi thời lượng (ms/s/m/h). Mặc định: 30m (xác thực bằng khóa API) hoặc 1h (xác thực OAuth). Đặt thành 0m để tắt.
• includeSystemPromptSection: khi là false, bỏ qua phần Heartbeat khỏi system prompt và bỏ qua việc chèn HEARTBEAT.md vào ngữ cảnh bootstrap. Mặc định: true.
• suppressToolErrorWarnings: khi là true, ẩn các payload cảnh báo lỗi công cụ trong các lượt chạy Heartbeat.
• timeoutSeconds: thời gian tối đa tính bằng giây được phép cho một lượt tác tử Heartbeat trước khi bị hủy. Để trống để dùng agents.defaults.timeoutSeconds.
• directPolicy: chính sách gửi trực tiếp/DM. allow (mặc định) cho phép gửi tới đích trực tiếp. block chặn gửi tới đích trực tiếp và phát ra reason=dm-blocked.
• lightContext: khi là true, các lượt chạy Heartbeat dùng ngữ cảnh bootstrap nhẹ và chỉ giữ HEARTBEAT.md từ các tệp bootstrap của không gian làm việc.
• isolatedSession: khi là true, mỗi Heartbeat chạy trong một phiên mới không có lịch sử hội thoại trước đó. Cùng mẫu cô lập như Cron sessionTarget: "isolated". Giảm chi phí token cho mỗi Heartbeat từ ~100K xuống ~2-5K token.
• skipWhenBusy: khi là true, các lượt chạy Heartbeat hoãn lại khi có thêm các lane bận: công việc subagent hoặc lệnh lồng nhau. Các lane Cron luôn hoãn Heartbeat, ngay cả khi không có cờ này.
• Theo tác tử: đặt agents.list[].heartbeat. Khi bất kỳ tác tử nào định nghĩa heartbeat, chỉ những tác tử đó chạy Heartbeat.
• Heartbeat chạy đầy đủ lượt tác tử — khoảng thời gian ngắn hơn sẽ tiêu tốn nhiều token hơn.

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // id of a registered compaction provider plugin (optional)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        keepRecentTokens: 50000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
        qualityGuard: { enabled: true, maxRetries: 1 },
        postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection
        model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
        truncateAfterCompaction: true, // rotate to a smaller successor JSONL after compaction
        maxActiveTranscriptBytes: "20mb", // optional preflight local compaction trigger
        notifyUser: true, // send brief notices when compaction starts and completes (default: false)
        memoryFlush: {
          enabled: true,
          model: "ollama/qwen3:8b", // optional memory-flush-only model override
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

• mode: default hoặc safeguard (tóm tắt theo đoạn cho lịch sử dài). Xem Compaction.
• provider: ID của Plugin nhà cung cấp Compaction đã đăng ký. Khi được đặt, summarize() của nhà cung cấp được gọi thay cho tóm tắt LLM tích hợp. Quay về cơ chế tích hợp khi lỗi. Việc đặt nhà cung cấp buộc mode: "safeguard". Xem Compaction.
• timeoutSeconds: số giây tối đa được phép cho một thao tác Compaction trước khi OpenClaw hủy thao tác đó. Mặc định: 900.
• keepRecentTokens: ngân sách điểm cắt của Pi để giữ nguyên văn phần đuôi bản ghi gần đây nhất. /compact thủ công tôn trọng giá trị này khi được đặt rõ ràng; nếu không, Compaction thủ công là một điểm checkpoint cứng.
• identifierPolicy: strict (mặc định), off, hoặc custom. strict thêm hướng dẫn tích hợp về giữ lại định danh mờ đục vào đầu quá trình tóm tắt Compaction.
• identifierInstructions: văn bản tùy chỉnh tùy chọn về việc bảo toàn định danh, dùng khi identifierPolicy=custom.
• qualityGuard: kiểm tra thử lại khi đầu ra sai định dạng cho tóm tắt safeguard. Được bật theo mặc định trong chế độ safeguard; đặt enabled: false để bỏ qua kiểm tra.
• postCompactionSections: tên phần H2/H3 tùy chọn trong AGENTS.md để chèn lại sau Compaction. Mặc định là ["Session Startup", "Red Lines"]; đặt [] để tắt chèn lại. Khi chưa đặt hoặc được đặt rõ ràng thành cặp mặc định đó, các tiêu đề cũ Every Session/Safety cũng được chấp nhận làm phương án dự phòng kế thừa.
• model: ghi đè provider/model-id tùy chọn chỉ cho tóm tắt Compaction. Dùng tùy chọn này khi phiên chính nên giữ một mô hình nhưng tóm tắt Compaction nên chạy trên mô hình khác; khi chưa đặt, Compaction dùng mô hình chính của phiên.
• maxActiveTranscriptBytes: ngưỡng byte tùy chọn (number hoặc chuỗi như "20mb") kích hoạt Compaction cục bộ bình thường trước một lượt chạy khi JSONL đang hoạt động vượt quá ngưỡng. Yêu cầu truncateAfterCompaction để Compaction thành công có thể xoay sang bản ghi kế nhiệm nhỏ hơn. Bị tắt khi chưa đặt hoặc bằng 0.
• notifyUser: khi là true, gửi thông báo ngắn cho người dùng khi Compaction bắt đầu và khi hoàn tất (ví dụ: “Compacting context…” và “Compaction complete”). Bị tắt theo mặc định để Compaction diễn ra im lặng.
• memoryFlush: lượt tác tử im lặng trước Compaction tự động để lưu trữ các ký ức bền vững. Đặt model thành một nhà cung cấp/mô hình chính xác như ollama/qwen3:8b khi lượt dọn dẹp này nên ở trên mô hình cục bộ; ghi đè này không kế thừa chuỗi dự phòng của phiên đang hoạt động. Bỏ qua khi không gian làm việc ở chế độ chỉ đọc.

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // duration (ms/s/m/h), default unit: minutes
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" },
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

​

Truyền trực tuyến theo khối

{
  agents: {
    defaults: {
      blockStreamingDefault: "off", // on | off
      blockStreamingBreak: "text_end", // text_end | message_end
      blockStreamingChunk: { minChars: 800, maxChars: 1200 },
      blockStreamingCoalesce: { idleMs: 1000 },
      humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs)
    },
  },
}

• Các kênh không phải Telegram yêu cầu *.blockStreaming: true rõ ràng để bật phản hồi theo khối.
• Ghi đè theo kênh: channels.<channel>.blockStreamingCoalesce (và các biến thể theo tài khoản). Signal/Slack/Discord/Google Chat mặc định minChars: 1500.
• humanDelay: khoảng dừng ngẫu nhiên giữa các phản hồi theo khối. natural = 800–2500ms. Ghi đè theo tác tử: agents.list[].humanDelay.

​

Chỉ báo đang nhập

{
  agents: {
    defaults: {
      typingMode: "instant", // never | instant | thinking | message
      typingIntervalSeconds: 6,
    },
  },
}

• Mặc định: instant cho trò chuyện trực tiếp/lượt nhắc đến, message cho trò chuyện nhóm không được nhắc đến.
• Ghi đè theo phiên: session.typingMode, session.typingIntervalSeconds.

​

agents.defaults.sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        backend: "docker", // docker | ssh | openshell
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/home/user/source:/source:rw"],
        },
        ssh: {
          target: "user@gateway-host:22",
          command: "ssh",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // SecretRefs / inline contents also supported:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          network: "openclaw-sandbox-browser",
          cdpPort: 9222,
          cdpSourceRange: "172.21.0.1/32",
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "apply_patch",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

{
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          mode: "mirror", // mirror | remote
          from: "openclaw",
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
          gateway: "lab", // optional
          gatewayEndpoint: "https://lab.example", // optional
          policy: "strict", // optional OpenShell policy id
          providers: ["openai"], // optional
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

scripts/sandbox-setup.sh           # main sandbox image
scripts/sandbox-browser-setup.sh   # optional browser image

​

agents.list (ghi đè theo tác nhân)

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // or { primary, fallbacks }
        thinkingDefault: "high", // per-agent thinking level override
        reasoningDefault: "on", // per-agent reasoning visibility override
        fastModeDefault: false, // per-agent fast mode override
        agentRuntime: { id: "auto", fallback: "pi" },
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        tts: {
          providers: {
            elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
        skills: ["docs-search"], // replaces agents.defaults.skills when set
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

• id: mã định danh tác nhân ổn định (bắt buộc).
• default: khi đặt nhiều mục, mục đầu tiên thắng (ghi cảnh báo). Nếu không đặt mục nào, mục đầu tiên trong danh sách là mặc định.
• model: dạng chuỗi đặt một primary nghiêm ngặt theo từng tác nhân, không có fallback model; dạng đối tượng { primary } cũng nghiêm ngặt trừ khi bạn thêm fallbacks. Dùng { primary, fallbacks: [...] } để cho tác nhân đó tham gia fallback, hoặc { primary, fallbacks: [] } để làm rõ hành vi nghiêm ngặt. Các Cron job chỉ ghi đè primary vẫn kế thừa fallback mặc định trừ khi bạn đặt fallbacks: [].
• params: tham số luồng theo từng tác nhân, được hợp nhất đè lên mục model đã chọn trong agents.defaults.models. Dùng mục này cho các ghi đè riêng của tác nhân như cacheRetention, temperature, hoặc maxTokens mà không phải sao chép toàn bộ danh mục model.
• tts: ghi đè chuyển văn bản thành giọng nói tùy chọn theo từng tác nhân. Khối này deep-merge đè lên messages.tts, vì vậy hãy giữ thông tin xác thực nhà cung cấp dùng chung và chính sách fallback trong messages.tts, rồi chỉ đặt các giá trị riêng theo persona như nhà cung cấp, giọng, model, kiểu, hoặc chế độ tự động tại đây.
• skills: danh sách cho phép skill tùy chọn theo từng tác nhân. Nếu bỏ qua, tác nhân kế thừa agents.defaults.skills khi đã đặt; một danh sách tường minh sẽ thay thế mặc định thay vì hợp nhất, và [] nghĩa là không có skill nào.
• thinkingDefault: mức suy nghĩ mặc định tùy chọn theo từng tác nhân (off | minimal | low | medium | high | xhigh | adaptive | max). Ghi đè agents.defaults.thinkingDefault cho tác nhân này khi không đặt ghi đè theo tin nhắn hoặc phiên. Hồ sơ nhà cung cấp/model đã chọn kiểm soát các giá trị hợp lệ; với Google Gemini, adaptive giữ suy nghĩ động do nhà cung cấp quản lý (thinkingLevel bị bỏ qua trên Gemini 3/3.1, thinkingBudget: -1 trên Gemini 2.5).
• reasoningDefault: chế độ hiển thị reasoning mặc định tùy chọn theo từng tác nhân (on | off | stream). Ghi đè agents.defaults.reasoningDefault cho tác nhân này khi không đặt ghi đè reasoning theo tin nhắn hoặc phiên.
• fastModeDefault: mặc định tùy chọn theo từng tác nhân cho chế độ nhanh (true | false). Áp dụng khi không đặt ghi đè chế độ nhanh theo tin nhắn hoặc phiên.
• agentRuntime: ghi đè chính sách runtime cấp thấp tùy chọn theo từng tác nhân. Dùng { id: "codex" } để khiến một tác nhân chỉ dùng Codex, trong khi các tác nhân khác vẫn giữ fallback PI mặc định ở chế độ auto.
• runtime: mô tả runtime tùy chọn theo từng tác nhân. Dùng type: "acp" với các mặc định runtime.acp (agent, backend, mode, cwd) khi tác nhân nên mặc định dùng các phiên harness ACP.
• identity.avatar: đường dẫn tương đối với workspace, URL http(s), hoặc URI data:.
• identity suy ra các mặc định: ackReaction từ emoji, mentionPatterns từ name/emoji.
• subagents.allowAgents: danh sách cho phép các mã định danh tác nhân cho mục tiêu sessions_spawn.agentId tường minh (["*"] = bất kỳ; mặc định: chỉ cùng tác nhân). Bao gồm mã định danh của bên yêu cầu khi muốn cho phép các lệnh gọi agentId tự nhắm tới chính nó.
• Bộ bảo vệ kế thừa sandbox: nếu phiên yêu cầu đang bị sandbox, sessions_spawn sẽ từ chối các mục tiêu sẽ chạy không sandbox.
• subagents.requireAgentId: khi là true, chặn các lệnh gọi sessions_spawn bỏ qua agentId (buộc chọn hồ sơ tường minh; mặc định: false).

​

Định tuyến đa tác nhân

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

​

Trường khớp binding

• type (tùy chọn): route cho định tuyến bình thường (thiếu type mặc định là route), acp cho các binding cuộc hội thoại ACP bền vững.
• match.channel (bắt buộc)
• match.accountId (tùy chọn; * = bất kỳ tài khoản nào; bỏ qua = tài khoản mặc định)
• match.peer (tùy chọn; { kind: direct|group|channel, id })
• match.guildId / match.teamId (tùy chọn; riêng theo kênh)
• acp (tùy chọn; chỉ cho type: "acp"): { mode, label, cwd, backend }

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (chính xác, không có peer/guild/team)
5. match.accountId: "*" (toàn kênh)
6. Tác nhân mặc định

​

Hồ sơ truy cập theo từng tác nhân

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },
        tools: {
          allow: [
            "read",
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
          ],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
        },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "public",
        workspace: "~/.openclaw/workspace-public",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },
        tools: {
          allow: [
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
            "whatsapp",
            "telegram",
            "slack",
            "discord",
            "gateway",
          ],
          deny: [
            "read",
            "write",
            "edit",
            "apply_patch",
            "exec",
            "process",
            "browser",
            "canvas",
            "nodes",
            "cron",
            "gateway",
            "image",
          ],
        },
      },
    ],
  },
}

​

Phiên

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      resetArchiveRetention: "30d", // duration or false
      maxDiskBytes: "500mb", // optional hard budget
      highWaterBytes: "400mb", // optional cleanup target
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
      maxAgeHours: 0, // default hard max age in hours (`0` disables)
    },
    mainKey: "main", // legacy (runtime always uses "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

​

Tin nhắn

{
  messages: {
    responsePrefix: "🦞", // or "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "steer", // steer | followup | collect | steer-backlog | steer+backlog | queue | interrupt
      debounceMs: 500,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "steer",
        telegram: "steer",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

Tiền tố phản hồi

​

Phản ứng xác nhận

• Mặc định là identity.emoji của agent đang hoạt động, nếu không thì dùng "👀". Đặt "" để tắt.
• Ghi đè theo kênh: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Thứ tự phân giải: tài khoản → kênh → messages.ackReaction → dự phòng từ định danh.
• Phạm vi: group-mentions (mặc định), group-all, direct, all.
• removeAckAfterReply: xóa xác nhận sau khi trả lời trên các kênh hỗ trợ phản ứng như Slack, Discord, Telegram, WhatsApp và BlueBubbles.
• messages.statusReactions.enabled: bật phản ứng trạng thái vòng đời trên Slack, Discord và Telegram. Trên Slack và Discord, nếu không đặt thì phản ứng trạng thái vẫn được bật khi phản ứng xác nhận đang hoạt động. Trên Telegram, hãy đặt rõ thành true để bật phản ứng trạng thái vòng đời.

​

Chống dội đầu vào

​

TTS (văn bản thành giọng nói)

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      providers: {
        elevenlabs: {
          apiKey: "elevenlabs_api_key",
          baseUrl: "https://api.elevenlabs.io",
          voiceId: "voice_id",
          modelId: "eleven_multilingual_v2",
          seed: 42,
          applyTextNormalization: "auto",
          languageCode: "en",
          voiceSettings: {
            stability: 0.5,
            similarityBoost: 0.75,
            style: 0.0,
            useSpeakerBoost: true,
            speed: 1.0,
          },
        },
        microsoft: {
          voice: "en-US-AvaMultilingualNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
        },
        openai: {
          apiKey: "openai_api_key",
          baseUrl: "https://api.openai.com/v1",
          model: "gpt-4o-mini-tts",
          voice: "alloy",
        },
      },
    },
  },
}

• auto điều khiển chế độ auto-TTS mặc định: off, always, inbound, hoặc tagged. /tts on|off có thể ghi đè tùy chọn cục bộ, và /tts status hiển thị trạng thái có hiệu lực.
• summaryModel ghi đè agents.defaults.model.primary cho tóm tắt tự động.
• modelOverrides được bật theo mặc định; modelOverrides.allowProvider mặc định là false (chọn tham gia).
• Khóa API dự phòng về ELEVENLABS_API_KEY/XI_API_KEY và OPENAI_API_KEY.
• Các nhà cung cấp giọng nói đi kèm thuộc sở hữu Plugin. Nếu plugins.allow được đặt, hãy bao gồm từng Plugin nhà cung cấp TTS mà bạn muốn dùng, ví dụ microsoft cho Edge TTS. Mã định danh nhà cung cấp cũ edge được chấp nhận làm bí danh cho microsoft.
• providers.openai.baseUrl ghi đè điểm cuối OpenAI TTS. Thứ tự phân giải là cấu hình, rồi OPENAI_TTS_BASE_URL, rồi https://api.openai.com/v1.
• Khi providers.openai.baseUrl trỏ đến một điểm cuối không phải OpenAI, OpenClaw coi đó là máy chủ TTS tương thích OpenAI và nới lỏng xác thực model/giọng nói.

​

Talk

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        voiceId: "elevenlabs_voice_id",
        voiceAliases: {
          Clawd: "EXAVITQu4vr4xnSDxMaL",
          Roger: "CwhRBWXzGAHq8TQ4Fs17",
        },
        modelId: "eleven_v3",
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
      mlx: {
        modelId: "mlx-community/Soprano-80M-bf16",
      },
      system: {},
    },
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
  },
}

• talk.provider phải khớp với một khóa trong talk.providers khi cấu hình nhiều nhà cung cấp Talk.
• Các khóa Talk dạng phẳng cũ (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) chỉ dành cho tương thích và được tự động di chuyển vào talk.providers.<provider>.
• Mã định danh giọng nói dự phòng về ELEVENLABS_VOICE_ID hoặc SAG_VOICE_ID.
• providers.*.apiKey chấp nhận chuỗi văn bản thuần hoặc đối tượng SecretRef.
• Dự phòng ELEVENLABS_API_KEY chỉ áp dụng khi không có khóa API Talk nào được cấu hình.
• providers.*.voiceAliases cho phép chỉ thị Talk dùng tên thân thiện.
• providers.mlx.modelId chọn kho Hugging Face được trình trợ giúp MLX cục bộ của macOS dùng. Nếu bỏ qua, macOS dùng mlx-community/Soprano-80M-bf16.
• Phát lại MLX trên macOS chạy qua trình trợ giúp openclaw-mlx-tts đi kèm khi có, hoặc một tệp thực thi trên PATH; OPENCLAW_MLX_TTS_BIN ghi đè đường dẫn trình trợ giúp cho phát triển.
• speechLocale đặt mã ngôn ngữ BCP 47 được nhận dạng giọng nói Talk trên iOS/macOS dùng. Để trống để dùng mặc định của thiết bị.
• silenceTimeoutMs điều khiển khoảng thời gian chế độ Talk chờ sau khi người dùng im lặng trước khi gửi bản chép lời. Nếu không đặt, cửa sổ tạm dừng mặc định của nền tảng được giữ nguyên (700 ms on macOS and Android, 900 ms on iOS).

​

Liên quan

• Tham chiếu cấu hình — tất cả khóa cấu hình khác
• Cấu hình — tác vụ phổ biến và thiết lập nhanh
• Ví dụ cấu hình