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.* 設定鍵和自訂 provider / base-URL 設定。如需 agents、channels 和其他頂層設定鍵,請參閱設定參考。
Tools
工具設定檔
tools.profile 會在 tools.allow/tools.deny 之前設定基礎允許清單:
本機 onboarding 會在未設定時,將新的本機設定預設為
tools.profile: "coding"(既有的明確設定檔會保留)。| 設定檔 | 包含 |
|---|---|
minimal | 僅 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 | 無限制(等同於未設定) |
工具群組
| 群組 | 工具 |
|---|---|
group:runtime | exec, process, code_execution(bash 會被接受為 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 | 所有內建工具(不包含 provider plugins) |
tools.allow / tools.deny
全域工具允許/拒絕政策(拒絕優先)。不區分大小寫,支援 * 萬用字元。即使 Docker sandbox 關閉也會套用。
tools.byProvider
進一步限制特定 provider 或模型的工具。順序:基礎設定檔 → provider 設定檔 → 允許/拒絕。
tools.elevated
控制 sandbox 外的提升權限 exec 存取:
- 每個 agent 的覆寫(
agents.list[].tools.elevated)只能進一步限制。 /elevated on|off|ask|full會依 session 儲存狀態;行內指令只套用於單則訊息。- 提升權限的
exec會繞過 sandboxing,並使用已設定的逃逸路徑(預設為gateway,或當 exec 目標為node時使用node)。
tools.exec
tools.loopDetection
工具迴圈安全檢查預設停用。設定 enabled: true 以啟用偵測。設定可在全域 tools.loopDetection 定義,並可在每個 agent 的 agents.list[].tools.loopDetection 覆寫。
保留用於迴圈分析的最大工具呼叫歷史。
重複無進展模式的警告閾值。
用於封鎖嚴重迴圈的較高重複閾值。
任何無進展執行的硬性停止閾值。
對重複的相同工具/相同引數呼叫發出警告。
對已知輪詢工具(
process.poll, command_status 等)發出警告/封鎖。對交替出現的無進展成對模式發出警告/封鎖。
tools.web
tools.media
設定傳入媒體理解(圖片/音訊/影片):
媒體模型項目欄位
媒體模型項目欄位
Provider 項目(
type: "provider" 或省略):provider:API 提供者 ID(openai、anthropic、google/gemini、groq等)model:模型 ID 覆寫profile/preferredProfile:auth-profiles.json設定檔選擇
type: "cli"):command:要執行的可執行檔args:範本化引數(支援{{MediaPath}}、{{Prompt}}、{{MaxChars}}等;openclaw doctor --fix會將已棄用的{input}預留位置遷移至{{MediaPath}})
capabilities:選用清單(image、audio、video)。預設值:openai/anthropic/minimax→ 圖片,google→ 圖片+音訊+影片,groq→ 音訊。prompt、maxChars、maxBytes、timeoutSeconds、language:逐項目覆寫。tools.media.image.timeoutSeconds和相符的圖片模型timeoutSeconds項目,也會在 agent 呼叫明確的image工具時套用。- 失敗時會退回到下一個項目。
auth-profiles.json → env vars → models.providers.*.apiKey。非同步完成欄位:asyncCompletion.directSend:為true時,已完成的非同步music_generate與video_generate任務會先嘗試直接傳送到 channel。預設值:false(舊版請求者 session 喚醒/模型傳送路徑)。
tools.agentToAgent
tools.sessions
控制 session 工具(sessions_list、sessions_history、sessions_send)可以指定哪些 session。
預設值:tree(目前 session + 由它產生的 session,例如 subagents)。
可見性範圍
可見性範圍
self:只有目前的 session key。tree:目前 session + 由目前 session 產生的 session(subagents)。agent:屬於目前 agent ID 的任何 session(如果你在同一個 agent ID 下執行依 sender 區分的 session,可能包含其他使用者)。all:任何 session。跨 agent 指定仍需要tools.agentToAgent。- sandbox 限制:當目前 session 處於 sandbox,且
agents.defaults.sandbox.sessionToolsVisibility="spawned"時,即使tools.sessions.visibility="all",可見性也會被強制為tree。
tools.sessions_spawn
控制 sessions_spawn 的行內附件支援。
附件注意事項
附件注意事項
- 附件僅支援
runtime: "subagent"。ACP runtime 會拒絕它們。 - 檔案會實體化到子工作區的
.openclaw/attachments/<uuid>/,並附有.manifest.json。 - 附件內容會自動從 transcript 持久化中遮蔽。
- Base64 輸入會使用嚴格的字母表/padding 檢查,以及解碼前大小防護進行驗證。
- 目錄的檔案權限為
0700,檔案為0600。 - 清理會遵循
cleanup政策:delete一律移除附件;只有在retainOnSessionKeep: true時,keep才會保留附件。
tools.experimental
實驗性內建工具旗標。預設關閉,除非套用嚴格 agentic GPT-5 自動啟用規則。
planTool:啟用結構化的update_plan工具,用於追蹤非瑣碎的多步驟工作。- 預設值:
false,除非agents.defaults.embeddedPi.executionContract(或個別代理覆寫)在 OpenAI 或 OpenAI Codex GPT-5 系列執行中設為"strict-agentic"。設為true可在該範圍外強制啟用工具,或設為false可即使在 strict-agentic GPT-5 執行中也保持停用。 - 啟用後,系統提示也會加入使用指引,讓模型只在實質工作中使用它,並且最多只保留一個步驟為
in_progress。
agents.defaults.subagents
model:已產生子代理的預設模型。若省略,子代理會繼承呼叫者的模型。allowAgents:當請求代理未設定自己的subagents.allowAgents時,sessions_spawn的預設目標代理 ID 允許清單(["*"]= 任意;預設:僅同一代理)。runTimeoutSeconds:工具呼叫省略runTimeoutSeconds時,sessions_spawn的預設逾時(秒)。0表示無逾時。- 個別子代理工具政策:
tools.subagents.tools.allow/tools.subagents.tools.deny。
自訂提供者與基底 URL
OpenClaw 使用內建模型目錄。透過設定中的models.providers 或 ~/.openclaw/agents/<agentId>/agent/models.json 新增自訂提供者。
驗證與合併優先順序
驗證與合併優先順序
- 使用
authHeader: true+headers來處理自訂驗證需求。 - 使用
OPENCLAW_AGENT_DIR(或PI_CODING_AGENT_DIR,舊版環境變數別名)覆寫代理設定根目錄。 - 相符提供者 ID 的合併優先順序:
- 非空的代理
models.jsonbaseUrl值勝出。 - 非空的代理
apiKey值只有在該提供者於目前設定/驗證設定檔情境中不是由 SecretRef 管理時才會勝出。 - SecretRef 管理的提供者
apiKey值會從來源標記重新整理(環境變數參照為ENV_VAR_NAME,檔案/exec 參照為secretref-managed),而不是持久化已解析的密鑰。 - SecretRef 管理的提供者標頭值會從來源標記重新整理(環境變數參照為
secretref-env:ENV_VAR_NAME,檔案/exec 參照為secretref-managed)。 - 空白或缺少的代理
apiKey/baseUrl會回退到設定中的models.providers。 - 相符模型的
contextWindow/maxTokens會使用明確設定與隱含目錄值之間較高的值。 - 相符模型的
contextTokens會在存在時保留明確的執行階段上限;用它來限制有效情境,而不變更原生模型中繼資料。 - 當你希望設定完整重寫
models.json時,使用models.mode: "replace"。 - 標記持久化以來源為權威:標記會從作用中的來源設定快照(解析前)寫入,而不是從已解析的執行階段密鑰值寫入。
- 非空的代理
提供者欄位詳細資料
頂層目錄
頂層目錄
models.mode:提供者目錄行為(merge或replace)。models.providers:以提供者 ID 為鍵的自訂提供者對應。- 安全編輯:使用
openclaw config set models.providers.<id> '<json>' --strict-json --merge或openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge進行增量更新。除非傳入--replace,否則config set會拒絕破壞性取代。
- 安全編輯:使用
提供者連線與驗證
提供者連線與驗證
請求傳輸覆寫
請求傳輸覆寫
模型目錄項目
模型目錄項目
models.providers.*.models:明確的提供者模型目錄項目。models.providers.*.models.*.input:模型輸入模態。純文字模型使用["text"],原生圖片/視覺模型使用["text", "image"]。只有在所選模型標記為支援圖片時,圖片附件才會注入代理回合。models.providers.*.models.*.contextWindow:原生模型情境視窗中繼資料。這會覆寫該模型的提供者層級contextWindow。models.providers.*.models.*.contextTokens:選用的執行階段情境上限。這會覆寫提供者層級contextTokens;當你想要比模型原生contextWindow更小的有效情境預算時使用;openclaw models list會在兩個值不同時顯示兩者。models.providers.*.models.*.compat.supportsDeveloperRole:選用的相容性提示。對於具有非空非原生baseUrl(主機不是api.openai.com)的api: "openai-completions",OpenClaw 會在執行階段強制此值為false。空白/省略的baseUrl會保留預設 OpenAI 行為。models.providers.*.models.*.compat.requiresStringContent:針對僅接受字串的 OpenAI 相容聊天端點的選用相容性提示。當為true時,OpenClaw 會在傳送請求前,將純文字messages[].content陣列攤平成純字串。
Amazon Bedrock 探索
Amazon Bedrock 探索
plugins.entries.amazon-bedrock.config.discovery:Bedrock 自動探索設定根。plugins.entries.amazon-bedrock.config.discovery.enabled:開啟/關閉隱含探索。plugins.entries.amazon-bedrock.config.discovery.region:探索用的 AWS 區域。plugins.entries.amazon-bedrock.config.discovery.providerFilter:用於目標探索的選用提供者 ID 篩選器。plugins.entries.amazon-bedrock.config.discovery.refreshInterval:探索重新整理的輪詢間隔。plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow:探索到模型的備援情境視窗。plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens:探索到模型的備援最大輸出權杖數。
--custom-image-input 可強制使用支援圖片的中繼資料,或傳入 --custom-text-input 可強制使用純文字中繼資料。
提供者範例
Cerebras (GLM 4.7 / GPT OSS)
Cerebras (GLM 4.7 / GPT OSS)
隨附的 Cerebras 請使用
cerebras 提供者 Plugin 可透過 openclaw onboard --auth-choice cerebras-api-key 設定此項。只有在覆寫預設值時才使用明確的提供者設定。cerebras/zai-glm-4.7;Z.AI 直連請使用 zai/glm-4.7。Kimi Coding
Kimi Coding
openclaw onboard --auth-choice kimi-code-api-key。本地模型 (LM Studio)
本地模型 (LM Studio)
請參閱本地模型。簡而言之:在高階硬體上透過 LM Studio Responses API 執行大型本地模型;保留合併的託管模型作為後援。
MiniMax M2.7 (direct)
MiniMax M2.7 (direct)
MINIMAX_API_KEY。捷徑:openclaw onboard --auth-choice minimax-global-api 或 openclaw onboard --auth-choice minimax-cn-api。模型目錄預設僅包含 M2.7。在 Anthropic 相容的串流路徑上,除非你明確自行設定 thinking,否則 OpenClaw 預設會停用 MiniMax thinking。/fast on 或 params.fastMode: true 會將 MiniMax-M2.7 改寫為 MiniMax-M2.7-highspeed。Moonshot AI (Kimi)
Moonshot AI (Kimi)
baseUrl: "https://api.moonshot.cn/v1" 或 openclaw onboard --auth-choice moonshot-api-key-cn。原生 Moonshot 端點會在共用的 openai-completions 傳輸上宣告串流使用量相容性,而 OpenClaw 會依據端點能力判定,而不是只依內建提供者 ID 判定。OpenCode
OpenCode
OPENCODE_API_KEY(或 OPENCODE_ZEN_API_KEY)。Zen 目錄使用 opencode/... refs,Go 目錄使用 opencode-go/... refs。捷徑:openclaw onboard --auth-choice opencode-zen 或 openclaw onboard --auth-choice opencode-go。Synthetic(Anthropic 相容)
Synthetic(Anthropic 相容)
/v1(Anthropic 用戶端會附加它)。捷徑:openclaw onboard --auth-choice synthetic-api-key。Z.AI (GLM-4.7)
Z.AI (GLM-4.7)
ZAI_API_KEY。z.ai/* 和 z-ai/* 都是可接受的別名。捷徑:openclaw onboard --auth-choice zai-api-key。- 一般端點:
https://api.z.ai/api/paas/v4 - 程式碼端點(預設):
https://api.z.ai/api/coding/paas/v4 - 若使用一般端點,請定義自訂提供者並覆寫基礎 URL。
相關
- 設定 — agents
- 設定 — channels
- 設定參考 — 其他頂層鍵
- 工具和 plugins