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.
tools.* khóa cấu hình và thiết lập nhà cung cấp tùy chỉnh / URL cơ sở. Đối với tác nhân, kênh và các khóa cấu hình cấp cao nhất khác, xem Tham chiếu cấu hình.
Công cụ
Hồ sơ công cụ
tools.profile đặt một danh sách cho phép cơ sở trước tools.allow/tools.deny:
Quy trình thiết lập cục bộ mặc định các cấu hình cục bộ mới thành
tools.profile: "coding" khi chưa đặt (các hồ sơ rõ ràng hiện có được giữ nguyên).| Hồ sơ | Bao gồm |
|---|---|
minimal | Chỉ session_status |
coding | group:fs, group:runtime, group:web, group:sessions, group:memory, cron, image, image_generate, video_generate |
messaging | group:messaging, sessions_list, sessions_history, sessions_send, session_status |
full | Không hạn chế (giống như chưa đặt) |
Nhóm công cụ
| Nhóm | Công cụ |
|---|---|
group:runtime | exec, process, code_execution (bash được chấp nhận làm bí danh cho exec) |
group:fs | read, write, edit, apply_patch |
group:sessions | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status |
group:memory | memory_search, memory_get |
group:web | web_search, x_search, web_fetch |
group:ui | browser, canvas |
group:automation | cron, gateway |
group:messaging | message |
group:nodes | nodes |
group:agents | agents_list |
group:media | image, image_generate, video_generate, tts |
group:openclaw | Tất cả công cụ tích hợp sẵn (không bao gồm Plugin của nhà cung cấp) |
tools.allow / tools.deny
Chính sách cho phép/từ chối công cụ toàn cục (từ chối thắng). Không phân biệt chữ hoa chữ thường, hỗ trợ ký tự đại diện *. Được áp dụng ngay cả khi Docker sandbox tắt.
tools.byProvider
Hạn chế thêm công cụ cho các nhà cung cấp hoặc mô hình cụ thể. Thứ tự: hồ sơ cơ sở → hồ sơ nhà cung cấp → cho phép/từ chối.
tools.elevated
Kiểm soát quyền truy cập exec nâng cao bên ngoài sandbox:
- Ghi đè theo từng tác nhân (
agents.list[].tools.elevated) chỉ có thể hạn chế thêm. /elevated on|off|ask|fulllưu trạng thái theo từng phiên; chỉ thị nội tuyến áp dụng cho một tin nhắn.execnâng cao bỏ qua sandbox và dùng đường dẫn thoát đã cấu hình (gatewaytheo mặc định, hoặcnodekhi mục tiêu exec lànode).
tools.exec
tools.loopDetection
Các kiểm tra an toàn vòng lặp công cụ bị tắt theo mặc định. Đặt enabled: true để kích hoạt phát hiện. Có thể định nghĩa thiết lập toàn cục trong tools.loopDetection và ghi đè theo từng tác nhân tại agents.list[].tools.loopDetection.
Lịch sử lệnh gọi công cụ tối đa được giữ lại để phân tích vòng lặp.
Ngưỡng mẫu lặp lại không có tiến triển để cảnh báo.
Ngưỡng lặp lại cao hơn để chặn các vòng lặp nghiêm trọng.
Ngưỡng dừng cứng cho bất kỳ lượt chạy không có tiến triển nào.
Cảnh báo khi lặp lại các lệnh gọi cùng công cụ/cùng tham số.
Cảnh báo/chặn trên các công cụ thăm dò đã biết (
process.poll, command_status, v.v.).Cảnh báo/chặn trên các mẫu cặp luân phiên không có tiến triển.
tools.web
tools.media
Định cấu hình khả năng hiểu phương tiện gửi đến (hình ảnh/âm thanh/video):
Media model entry fields
Media model entry fields
Mục nhập nhà cung cấp (
type: "provider" hoặc bị lược bỏ):provider: id nhà cung cấp API (openai,anthropic,google/gemini,groq, v.v.)model: ghi đè id mô hìnhprofile/preferredProfile: lựa chọn hồ sơauth-profiles.json
type: "cli"):command: tệp thực thi cần chạyargs: đối số theo mẫu (hỗ trợ{{MediaPath}},{{Prompt}},{{MaxChars}}, v.v.;openclaw doctor --fixdi chuyển các placeholder{input}đã ngừng dùng sang{{MediaPath}})
capabilities: danh sách tùy chọn (image,audio,video). Mặc định:openai/anthropic/minimax→ hình ảnh,google→ hình ảnh+âm thanh+video,groq→ âm thanh.prompt,maxChars,maxBytes,timeoutSeconds,language: ghi đè theo từng mục nhập.tools.media.image.timeoutSecondsvà các mục nhậptimeoutSecondstương ứng của mô hình hình ảnh cũng được áp dụng khi tác tử gọi công cụimagerõ ràng.- Lỗi sẽ chuyển sang mục nhập tiếp theo.
auth-profiles.json → biến môi trường → models.providers.*.apiKey.Trường hoàn tất bất đồng bộ:asyncCompletion.directSend: khi làtrue, các tác vụ bất đồng bộmusic_generatevàvideo_generateđã hoàn tất sẽ thử gửi trực tiếp tới kênh trước. Mặc định:false(đường dẫn cũ đánh thức phiên người yêu cầu/phân phối qua mô hình).
tools.agentToAgent
tools.sessions
Kiểm soát những phiên nào có thể được nhắm tới bởi các công cụ phiên (sessions_list, sessions_history, sessions_send).
Mặc định: tree (phiên hiện tại + các phiên do nó sinh ra, chẳng hạn như tác tử phụ).
Visibility scopes
Visibility scopes
self: chỉ khóa phiên hiện tại.tree: phiên hiện tại + các phiên do phiên hiện tại sinh ra (tác tử phụ).agent: bất kỳ phiên nào thuộc về id tác tử hiện tại (có thể bao gồm người dùng khác nếu bạn chạy các phiên theo từng người gửi dưới cùng một id tác tử).all: bất kỳ phiên nào. Nhắm mục tiêu xuyên tác tử vẫn yêu cầutools.agentToAgent.- Kẹp sandbox: khi phiên hiện tại đang ở trong sandbox và
agents.defaults.sandbox.sessionToolsVisibility="spawned", mức hiển thị bị ép thànhtreengay cả khitools.sessions.visibility="all".
tools.sessions_spawn
Kiểm soát hỗ trợ tệp đính kèm nội tuyến cho sessions_spawn.
Attachment notes
Attachment notes
- Tệp đính kèm chỉ được hỗ trợ cho
runtime: "subagent". Runtime ACP từ chối chúng. - Tệp được hiện thực hóa vào không gian làm việc con tại
.openclaw/attachments/<uuid>/cùng với.manifest.json. - Nội dung tệp đính kèm được tự động biên tập khỏi phần lưu bền transcript.
- Đầu vào Base64 được xác thực bằng kiểm tra bảng chữ cái/phần đệm nghiêm ngặt và chặn kích thước trước khi giải mã.
- Quyền tệp là
0700cho thư mục và0600cho tệp. - Dọn dẹp tuân theo chính sách
cleanup:deleteluôn xóa tệp đính kèm;keepchỉ giữ lại chúng khiretainOnSessionKeep: true.
tools.experimental
Cờ công cụ tích hợp thử nghiệm. Mặc định tắt trừ khi áp dụng quy tắc tự động bật GPT-5 tác tử nghiêm ngặt.
planTool: bật công cụupdate_plancó cấu trúc để theo dõi công việc nhiều bước không tầm thường.- Mặc định:
falsetrừ khiagents.defaults.embeddedPi.executionContract(hoặc ghi đè theo từng agent) được đặt thành"strict-agentic"cho một lần chạy thuộc họ GPT-5 của OpenAI hoặc OpenAI Codex. Đặttrueđể buộc bật công cụ ngoài phạm vi đó, hoặcfalseđể giữ tắt ngay cả với các lần chạy GPT-5 strict-agentic. - Khi bật, system prompt cũng thêm hướng dẫn sử dụng để model chỉ dùng công cụ này cho công việc đáng kể và giữ tối đa một bước ở trạng thái
in_progress.
agents.defaults.subagents
model: model mặc định cho các sub-agent được sinh ra. Nếu bỏ qua, sub-agent kế thừa model của bên gọi.allowAgents: allowlist mặc định gồm các id agent đích chosessions_spawnkhi agent yêu cầu không đặtsubagents.allowAgentsriêng (["*"]= bất kỳ; mặc định: chỉ cùng agent).runTimeoutSeconds: thời gian chờ mặc định (giây) chosessions_spawnkhi lời gọi công cụ bỏ quarunTimeoutSeconds.0nghĩa là không có thời gian chờ.- Chính sách công cụ theo từng subagent:
tools.subagents.tools.allow/tools.subagents.tools.deny.
Nhà cung cấp tùy chỉnh và URL cơ sở
OpenClaw dùng danh mục model tích hợp. Thêm nhà cung cấp tùy chỉnh quamodels.providers trong cấu hình hoặc ~/.openclaw/agents/<agentId>/agent/models.json.
Xác thực và thứ tự ưu tiên khi hợp nhất
Xác thực và thứ tự ưu tiên khi hợp nhất
- Dùng
authHeader: true+headerscho các nhu cầu xác thực tùy chỉnh. - Ghi đè gốc cấu hình agent bằng
OPENCLAW_AGENT_DIR(hoặcPI_CODING_AGENT_DIR, một bí danh biến môi trường cũ). - Thứ tự ưu tiên hợp nhất cho các ID nhà cung cấp khớp nhau:
- Các giá trị
baseUrlkhông rỗng trongmodels.jsoncủa agent được ưu tiên. - Các giá trị
apiKeykhông rỗng trong agent chỉ được ưu tiên khi nhà cung cấp đó không do SecretRef quản lý trong ngữ cảnh cấu hình/auth-profile hiện tại. - Các giá trị
apiKeycủa nhà cung cấp do SecretRef quản lý được làm mới từ marker nguồn (ENV_VAR_NAMEcho tham chiếu env,secretref-managedcho tham chiếu file/exec) thay vì lưu trữ secret đã phân giải. - Các giá trị header của nhà cung cấp do SecretRef quản lý được làm mới từ marker nguồn (
secretref-env:ENV_VAR_NAMEcho tham chiếu env,secretref-managedcho tham chiếu file/exec). apiKey/baseUrlcủa agent rỗng hoặc thiếu sẽ quay vềmodels.providerstrong cấu hình.contextWindow/maxTokenscủa model khớp nhau dùng giá trị cao hơn giữa cấu hình rõ ràng và giá trị danh mục ngầm định.contextTokenscủa model khớp nhau giữ nguyên giới hạn runtime rõ ràng khi có; dùng nó để giới hạn ngữ cảnh hiệu dụng mà không thay đổi metadata model gốc.- Dùng
models.mode: "replace"khi bạn muốn cấu hình ghi lại hoàn toànmodels.json. - Việc lưu marker lấy nguồn làm chuẩn: marker được ghi từ snapshot cấu hình nguồn đang hoạt động (trước phân giải), không phải từ các giá trị secret runtime đã phân giải.
- Các giá trị
Chi tiết trường của nhà cung cấp
Danh mục cấp cao nhất
Danh mục cấp cao nhất
models.mode: hành vi danh mục nhà cung cấp (mergehoặcreplace).models.providers: bản đồ nhà cung cấp tùy chỉnh, khóa theo id nhà cung cấp.- Chỉnh sửa an toàn: dùng
openclaw config set models.providers.<id> '<json>' --strict-json --mergehoặcopenclaw config set models.providers.<id>.models '<json-array>' --strict-json --mergecho các cập nhật bổ sung.config settừ chối các thay thế phá hủy trừ khi bạn truyền--replace.
- Chỉnh sửa an toàn: dùng
Kết nối và xác thực nhà cung cấp
Kết nối và xác thực nhà cung cấp
models.providers.*.api: bộ chuyển đổi yêu cầu (openai-completions,openai-responses,anthropic-messages,google-generative-ai, v.v.). Với backend/v1/chat/completionstự host như MLX, vLLM, SGLang và hầu hết máy chủ cục bộ tương thích OpenAI, dùngopenai-completions. Nhà cung cấp tùy chỉnh cóbaseUrlnhưng không cóapimặc định dùngopenai-completions; chỉ đặtopenai-responseskhi backend hỗ trợ/v1/responses.models.providers.*.apiKey: thông tin xác thực nhà cung cấp (ưu tiên SecretRef/thay thế env).models.providers.*.auth: chiến lược xác thực (api-key,token,oauth,aws-sdk).models.providers.*.contextWindow: cửa sổ ngữ cảnh gốc mặc định cho các model dưới nhà cung cấp này khi mục model không đặtcontextWindow.models.providers.*.contextTokens: giới hạn ngữ cảnh runtime hiệu dụng mặc định cho các model dưới nhà cung cấp này khi mục model không đặtcontextTokens.models.providers.*.maxTokens: giới hạn output-token mặc định cho các model dưới nhà cung cấp này khi mục model không đặtmaxTokens.models.providers.*.timeoutSeconds: thời gian chờ tùy chọn cho mỗi nhà cung cấp đối với yêu cầu HTTP model, tính bằng giây, bao gồm kết nối, header, body và xử lý hủy toàn bộ yêu cầu.models.providers.*.injectNumCtxForOpenAICompat: với Ollama +openai-completions, chènoptions.num_ctxvào yêu cầu (mặc định:true).models.providers.*.authHeader: buộc truyền thông tin xác thực trong headerAuthorizationkhi cần.models.providers.*.baseUrl: URL cơ sở của API upstream.models.providers.*.headers: header tĩnh bổ sung cho định tuyến proxy/tenant.
Ghi đè truyền tải yêu cầu
Ghi đè truyền tải yêu cầu
models.providers.*.request: ghi đè truyền tải cho yêu cầu HTTP đến nhà cung cấp model.request.headers: header bổ sung (hợp nhất với mặc định của nhà cung cấp). Giá trị chấp nhận SecretRef.request.auth: ghi đè chiến lược xác thực. Chế độ:"provider-default"(dùng xác thực tích hợp của nhà cung cấp),"authorization-bearer"(vớitoken),"header"(vớiheaderName,value, tùy chọnprefix).request.proxy: ghi đè HTTP proxy. Chế độ:"env-proxy"(dùng biến môi trườngHTTP_PROXY/HTTPS_PROXY),"explicit-proxy"(vớiurl). Cả hai chế độ đều chấp nhận một đối tượng contlstùy chọn.request.tls: ghi đè TLS cho kết nối trực tiếp. Trường:ca,cert,key,passphrase(tất cả chấp nhận SecretRef),serverName,insecureSkipVerify.request.allowPrivateNetwork: khitrue, cho phép HTTPS đếnbaseUrlkhi DNS phân giải thành private, CGNAT hoặc các dải tương tự, thông qua bộ bảo vệ fetch HTTP của nhà cung cấp (operator chọn tham gia cho các endpoint tự host tương thích OpenAI đáng tin cậy). URL stream của nhà cung cấp model qua loopback nhưlocalhost,127.0.0.1và[::1]được tự động cho phép trừ khi tùy chọn này được đặt rõ ràng thànhfalse; máy chủ LAN, tailnet và DNS riêng vẫn cần chọn tham gia. WebSocket dùng cùngrequestcho header/TLS nhưng không dùng cổng SSRF fetch đó. Mặc địnhfalse.
Mục danh mục model
Mục danh mục model
models.providers.*.models: các mục danh mục model rõ ràng của nhà cung cấp.models.providers.*.models.*.input: phương thức đầu vào của model. Dùng["text"]cho model chỉ văn bản và["text", "image"]cho model hình ảnh/vision gốc. Tệp đính kèm hình ảnh chỉ được đưa vào lượt agent khi model được chọn được đánh dấu là hỗ trợ hình ảnh.models.providers.*.models.*.contextWindow: metadata cửa sổ ngữ cảnh gốc của model. Trường này ghi đècontextWindowcấp nhà cung cấp cho model đó.models.providers.*.models.*.contextTokens: giới hạn ngữ cảnh runtime tùy chọn. Trường này ghi đècontextTokenscấp nhà cung cấp; dùng khi bạn muốn ngân sách ngữ cảnh hiệu dụng nhỏ hơncontextWindowgốc của model;openclaw models listhiển thị cả hai giá trị khi chúng khác nhau.models.providers.*.models.*.compat.supportsDeveloperRole: gợi ý tương thích tùy chọn. Vớiapi: "openai-completions"cóbaseUrlkhông rỗng và không phải gốc (host không phảiapi.openai.com), OpenClaw buộc giá trị này thànhfalseở runtime.baseUrlrỗng/bị bỏ qua giữ hành vi OpenAI mặc định.models.providers.*.models.*.compat.requiresStringContent: gợi ý tương thích tùy chọn cho endpoint chat tương thích OpenAI chỉ nhận chuỗi. Khitrue, OpenClaw làm phẳng các mảngmessages[].contentchỉ gồm văn bản thuần thành chuỗi đơn giản trước khi gửi yêu cầu.
Khám phá Amazon Bedrock
Khám phá Amazon Bedrock
plugins.entries.amazon-bedrock.config.discovery: gốc cài đặt tự động khám phá Bedrock.plugins.entries.amazon-bedrock.config.discovery.enabled: bật/tắt khám phá ngầm định.plugins.entries.amazon-bedrock.config.discovery.region: vùng AWS để khám phá.plugins.entries.amazon-bedrock.config.discovery.providerFilter: bộ lọc provider-id tùy chọn cho khám phá có mục tiêu.plugins.entries.amazon-bedrock.config.discovery.refreshInterval: khoảng thăm dò để làm mới khám phá.plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: cửa sổ ngữ cảnh dự phòng cho các model được khám phá.plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: số token đầu ra tối đa dự phòng cho các model được khám phá.
--custom-image-input để buộc metadata hỗ trợ hình ảnh hoặc --custom-text-input để buộc metadata chỉ văn bản.
Ví dụ về nhà cung cấp
Cerebras (GLM 4.7 / GPT OSS)
Cerebras (GLM 4.7 / GPT OSS)
Plugin nhà cung cấp Dùng
cerebras đi kèm có thể cấu hình phần này qua openclaw onboard --auth-choice cerebras-api-key. Chỉ dùng cấu hình nhà cung cấp rõ ràng khi ghi đè mặc định.cerebras/zai-glm-4.7 cho Cerebras; zai/glm-4.7 cho Z.AI trực tiếp.Kimi Coding
Kimi Coding
openclaw onboard --auth-choice kimi-code-api-key.Mô hình cục bộ (LM Studio)
Mô hình cục bộ (LM Studio)
Xem Mô hình cục bộ. Tóm tắt: chạy một mô hình cục bộ lớn qua API Responses của LM Studio trên phần cứng mạnh; giữ các mô hình được lưu trữ hợp nhất để dự phòng.
MiniMax M2.7 (trực tiếp)
MiniMax M2.7 (trực tiếp)
MINIMAX_API_KEY. Lối tắt: openclaw onboard --auth-choice minimax-global-api hoặc openclaw onboard --auth-choice minimax-cn-api. Danh mục mô hình mặc định chỉ dùng M2.7. Trên đường dẫn truyền phát tương thích Anthropic, OpenClaw tắt chế độ suy nghĩ của MiniMax theo mặc định trừ khi bạn tự đặt thinking rõ ràng. /fast on hoặc params.fastMode: true viết lại MiniMax-M2.7 thành MiniMax-M2.7-highspeed.Moonshot AI (Kimi)
Moonshot AI (Kimi)
baseUrl: "https://api.moonshot.cn/v1" hoặc openclaw onboard --auth-choice moonshot-api-key-cn.Các endpoint Moonshot gốc quảng bá khả năng tương thích usage khi truyền phát trên transport openai-completions dùng chung, và OpenClaw xác định điều đó dựa trên năng lực của endpoint thay vì chỉ dựa vào id provider tích hợp sẵn.OpenCode
OpenCode
OPENCODE_API_KEY (hoặc OPENCODE_ZEN_API_KEY). Dùng tham chiếu opencode/... cho danh mục Zen hoặc tham chiếu opencode-go/... cho danh mục Go. Lối tắt: openclaw onboard --auth-choice opencode-zen hoặc openclaw onboard --auth-choice opencode-go.Synthetic (tương thích Anthropic)
Synthetic (tương thích Anthropic)
/v1 (máy khách Anthropic sẽ thêm phần đó). Lối tắt: openclaw onboard --auth-choice synthetic-api-key.Z.AI (GLM-4.7)
Z.AI (GLM-4.7)
ZAI_API_KEY. z.ai/* và z-ai/* được chấp nhận làm bí danh. Lối tắt: openclaw onboard --auth-choice zai-api-key.- Endpoint chung:
https://api.z.ai/api/paas/v4 - Endpoint lập trình (mặc định):
https://api.z.ai/api/coding/paas/v4 - Với endpoint chung, hãy định nghĩa một provider tùy chỉnh với phần ghi đè URL cơ sở.
Liên quan
- Cấu hình — agents
- Cấu hình — channels
- Tham chiếu cấu hình — các khóa cấp cao nhất khác
- Công cụ và plugins