tools.* і налаштування користувацького провайдера / базової URL-адреси. Для агентів, каналів та інших ключів конфігурації верхнього рівня див. Довідник конфігурації.
Інструменти
Профілі інструментів
tools.profile задає базовий список дозволених інструментів перед tools.allow/tools.deny:
Локальне початкове налаштування за замовчуванням встановлює для нових локальних конфігурацій
tools.profile: "coding", якщо значення не задано (наявні явно задані профілі зберігаються).| Профіль | Включає |
|---|---|
minimal | лише session_status |
coding | group:fs, group:runtime, group:web, group:sessions, group:memory, cron, image, image_generate, skill_workshop, 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 | heartbeat_respond, cron, gateway |
group:messaging | message |
group:nodes | nodes |
group:agents | agents_list, update_plan |
group:media | image, image_generate, music_generate, video_generate, tts |
group:openclaw | Усі вбудовані інструменти (без провайдерських plugins) |
group:plugins | Інструменти, якими володіють завантажені plugins, зокрема налаштовані MCP-сервери, відкриті через bundle-mcp |
MCP та інструменти plugin у політиці інструментів пісочниці
Налаштовані MCP-сервери доступні як інструменти, що належать plugin, під ідентифікатором pluginbundle-mcp. Звичайні профілі інструментів можуть їх дозволяти, але tools.sandbox.tools є додатковим бар’єром для сеансів у пісочниці. Якщо режим пісочниці має значення "all" або "non-main", додайте один із цих записів до списку дозволених інструментів пісочниці, коли інструменти MCP/plugin мають бути видимими:
bundle-mcpдля MCP-серверів, керованих OpenClaw, зmcp.servers- ідентифікатор plugin для конкретного нативного plugin
group:pluginsдля всіх завантажених інструментів, що належать plugin- точні назви інструментів MCP-сервера або серверні glob-шаблони, як-от
outlook__send_mailчиoutlook__*, коли потрібен лише один сервер
mcp.servers. Символи, відмінні від [A-Za-z0-9_-], стають -, назви, що не починаються з літери, отримують префікс mcp-, а довгі або дубліковані префікси можуть бути скорочені або отримати суфікс; наприклад, mcp.servers["Outlook Graph"] використовує glob-шаблон на кшталт outlook-graph__*.
openclaw doctor, щоб виявляти таку форму для MCP-серверів, керованих OpenClaw, у mcp.servers. MCP-сервери, завантажені з маніфестів bundled plugin або Claude .mcp.json, використовують той самий бар’єр пісочниці, але ця діагностика поки що не перелічує ці джерела; використовуйте ті самі записи списку дозволених, якщо їхні інструменти зникають у ходах у пісочниці.
tools.codeMode
tools.codeMode вмикає загальну поверхню режиму коду OpenClaw. Коли його ввімкнено
для запуску з інструментами, модель бачить лише exec і wait; звичайні інструменти OpenClaw
переміщуються за міст каталогу tools.* усередині пісочниці, а інструменти MCP
доступні через згенерований простір назв MCP.
API.list("mcp") і
API.read("mcp/<server>.d.ts"), щоб переглянути сигнатури у стилі TypeScript перед
викликом MCP.<server>.<tool>(). Див. Режим коду, щоб отримати
контракт виконання, обмеження та кроки налагодження.
tools.allow / tools.deny
Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Не чутлива до регістру, підтримує wildcard *. Застосовується навіть тоді, коли пісочницю Docker вимкнено.
write і apply_patch є окремими ідентифікаторами інструментів. allow: ["write"] також вмикає apply_patch для сумісних моделей, але deny: ["write"] не забороняє apply_patch. Щоб заблокувати всі зміни файлів, забороніть group:fs або явно перелічіть кожен інструмент, що змінює файли:
tools.byProvider
Додатково обмежує інструменти для конкретних провайдерів або моделей. Порядок: базовий профіль → профіль провайдера → дозволи/заборони.
tools.toolsBySender
Обмежує інструменти для конкретної ідентичності запитувача. Це поглиблений захист поверх контролю доступу каналу; значення відправника мають надходити з адаптера каналу, а не з тексту повідомлення.
channel:<channelId>:<senderId>, id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> або "*". Ідентифікатори каналів є канонічними ідентифікаторами OpenClaw; псевдоніми, як-от teams, нормалізуються до msteams. Застарілі ключі без префікса приймаються лише як id:. Порядок зіставлення: channel+id, id, e164, username, name, потім wildcard.
agents.list[].tools.toolsBySender для окремого агента перевизначає глобальне зіставлення відправника, коли воно збігається, навіть із порожньою політикою {}.
tools.elevated
Керує підвищеним доступом exec поза пісочницею:
- Перевизначення для окремого агента (
agents.list[].tools.elevated) може лише додатково обмежувати. /elevated on|off|ask|fullзберігає стан для кожного сеансу; inline-директиви застосовуються до одного повідомлення.- Підвищений
execобходить пісочницю та використовує налаштований шлях виходу (gatewayза замовчуванням абоnode, коли ціль exec —node).
tools.exec
tools.loopDetection
Перевірки безпеки циклів інструментів вимкнені за замовчуванням. Установіть enabled: true, щоб активувати виявлення. Налаштування можна визначити глобально в tools.loopDetection і перевизначити для окремого агента в agents.list[].tools.loopDetection.
Максимальна історія викликів інструментів, що зберігається для аналізу циклів.
Поріг повторюваного шаблону без прогресу для попереджень.
Вищий поріг повторень для блокування критичних циклів.
Поріг жорсткої зупинки для будь-якого запуску без прогресу.
Попереджати про повторні виклики того самого інструмента з тими самими аргументами.
Попереджати/блокувати відомі інструменти опитування (
process.poll, command_status тощо).Попереджати/блокувати змінні парні шаблони без прогресу.
tools.web
tools.media
Налаштовує розуміння вхідних медіа (зображення/аудіо/відео):
Media model entry fields
Media model entry fields
Запис постачальника (
type: "provider" або пропущено):provider: ідентифікатор постачальника API (openai,anthropic,google/gemini,groqтощо)model: перевизначення ідентифікатора моделі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моделі зображень також застосовуються, коли агент викликає явний інструментimage. Для розуміння зображень цей тайм-аут застосовується до самого запиту й не зменшується через попередню підготовчу роботу.- У разі помилки виконується перехід до наступного запису.
auth-profiles.json → змінні середовища → models.providers.*.apiKey.Поля асинхронного завершення:asyncCompletion.directSend: застарілий прапорець сумісності. Завершені асинхронні медіазавдання залишаються опосередкованими сеансом запитувача, щоб агент отримав результат, вирішив, як повідомити користувача, і використав інструмент повідомлень, коли цього вимагає доставка з джерела.
tools.agentToAgent
tools.sessions
Керує тим, на які сеанси можуть націлюватися інструменти сеансів (sessions_list, sessions_history, sessions_send).
Стандартне значення: tree (поточний сеанс + сеанси, породжені ним, наприклад субагенти).
Visibility scopes
Visibility scopes
self: лише ключ поточного сеансу.tree: поточний сеанс + сеанси, породжені поточним сеансом (субагенти).agent: будь-який сеанс, що належить поточному ідентифікатору агента (може включати інших користувачів, якщо ви запускаєте сеанси для кожного відправника під тим самим ідентифікатором агента).all: будь-який сеанс. Націлювання між агентами все одно потребуєtools.agentToAgent.- Обмеження sandbox: коли поточний сеанс працює в sandbox і
agents.defaults.sandbox.sessionToolsVisibility="spawned", видимість примусово встановлюється наtree, навіть якщоtools.sessions.visibility="all". - Коли значення не
all,sessions_listмістить компактне полеvisibility, яке описує ефективний режим, і попередження, що деякі сеанси можуть бути пропущені поза поточною областю видимості.
tools.sessions_spawn
Керує підтримкою вбудованих вкладень для sessions_spawn.
Attachment notes
Attachment notes
- Вкладення потребують
enabled: true. - Вкладення субагентів матеріалізуються в дочірньому робочому просторі за шляхом
.openclaw/attachments/<uuid>/з.manifest.json. - Вкладення ACP підтримують лише зображення й передаються вбудовано до середовища виконання ACP після проходження тих самих лімітів кількості файлів, байтів на файл і загальної кількості байтів.
- Вміст вкладень автоматично редагується перед збереженням транскриптів.
- Вхідні дані Base64 перевіряються строгими перевірками алфавіту/заповнення та запобіжником розміру перед декодуванням.
- Права доступу до файлів вкладень субагентів:
0700для директорій і0600для файлів. - Очищення субагентів дотримується політики
cleanup:deleteзавжди видаляє вкладення;keepзберігає їх лише колиretainOnSessionKeep: true.
tools.experimental
Експериментальні прапорці вбудованих інструментів. Типово вимкнено, якщо не застосовується правило автоматичного ввімкнення strict-agentic GPT-5.
planTool: вмикає структурований інструментupdate_planдля відстеження нетривіальної багатоетапної роботи.- Типово:
false, якщоagents.defaults.embeddedAgent.executionContract(або перевизначення для окремого агента) не встановлено в"strict-agentic"для запуску сімейства GPT-5 через OpenAI або OpenAI Codex. Установітьtrue, щоб примусово ввімкнути інструмент поза цією областю, абоfalse, щоб тримати його вимкненим навіть для strict-agentic запусків GPT-5. - Коли ввімкнено, системний промпт також додає настанови з використання, щоб модель застосовувала його лише для суттєвої роботи й тримала щонайбільше один крок
in_progress.
agents.defaults.subagents
model: типова модель для породжених субагентів. Якщо пропущено, субагенти успадковують модель викликача.allowAgents: типовий список дозволених налаштованих ідентифікаторів цільових агентів дляsessions_spawn, коли агент-запитувач не задає власнийsubagents.allowAgents(["*"]= будь-яка налаштована ціль; типово: лише той самий агент). Застарілі записи, конфігурацію агента яких було видалено, відхиляютьсяsessions_spawnі пропускаються вagents_list; виконайтеopenclaw doctor --fix, щоб їх очистити.runTimeoutSeconds: типовий таймаут (у секундах) дляsessions_spawn.0означає без таймауту.announceTimeoutMs: таймаут на виклик (у мілісекундах) для спроб доставки оголошенняagentчерез gateway. Типово:120000. Тимчасові повторні спроби можуть зробити загальне очікування оголошення довшим за один налаштований таймаут.- Політика інструментів для окремого субагента:
tools.subagents.tools.allow/tools.subagents.tools.deny.
Користувацькі провайдери й базові URL-адреси
Plugin провайдерів публікують власні рядки каталогу моделей. Додавайте користувацьких провайдерів черезmodels.providers у конфігурації або ~/.openclaw/agents/<agentId>/agent/models.json.
Налаштування baseUrl для користувацького/локального провайдера також є вузьким рішенням про мережеву довіру для HTTP-запитів моделі: OpenClaw дозволяє саме це джерело scheme://host:port через захищений шлях fetch, без додавання окремого параметра конфігурації або довіри до інших приватних джерел.
Auth and merge precedence
Auth and merge precedence
- Використовуйте
authHeader: true+headersдля користувацьких потреб автентифікації. - Перевизначте корінь конфігурації агента за допомогою
OPENCLAW_AGENT_DIR. - Пріоритет злиття для відповідних ідентифікаторів провайдерів:
- Непорожні значення
baseUrlз агентськогоmodels.jsonмають перевагу. - Непорожні значення
apiKeyагента мають перевагу лише коли цей провайдер не керується SecretRef у поточному контексті конфігурації/профілю автентифікації. - Значення
apiKeyпровайдера, керованого SecretRef, оновлюються з вихідних маркерів (ENV_VAR_NAMEдля посилань env,secretref-managedдля посилань file/exec) замість збереження розв’язаних секретів. - Значення заголовків провайдера, керованого SecretRef, оновлюються з вихідних маркерів (
secretref-env:ENV_VAR_NAMEдля посилань env,secretref-managedдля посилань file/exec). - Порожні або відсутні агентські
apiKey/baseUrlповертаються доmodels.providersу конфігурації. - Відповідні
contextWindow/maxTokensмоделі використовують більше значення між явною конфігурацією та неявними значеннями каталогу. - Відповідний
contextTokensмоделі зберігає явне обмеження середовища виконання, коли воно наявне; використовуйте його, щоб обмежити ефективний контекст без зміни нативних метаданих моделі. - Каталоги Plugin провайдерів зберігаються як згенеровані шардовані каталоги, що належать Plugin, у стані Plugin агента.
- Використовуйте
models.mode: "replace", коли хочете, щоб конфігурація повністю переписалаmodels.jsonі активні шардовані каталоги Plugin. - Збереження маркерів є авторитетним щодо джерела: маркери записуються з активного знімка вихідної конфігурації (до розв’язання), а не з розв’язаних значень секретів середовища виконання.
- Непорожні значення
Подробиці полів провайдера
Top-level catalog
Top-level catalog
models.mode: поведінка каталогу провайдерів (mergeабоreplace).models.providers: мапа користувацьких провайдерів, ключована ідентифікатором провайдера.- Безпечні редагування: використовуйте
openclaw config set models.providers.<id> '<json>' --strict-json --mergeабоopenclaw config set models.providers.<id>.models '<json-array>' --strict-json --mergeдля адитивних оновлень.config setвідхиляє руйнівні заміни, якщо не передати--replace.
- Безпечні редагування: використовуйте
Підключення постачальника та автентифікація
Підключення постачальника та автентифікація
models.providers.*.api: адаптер запитів (openai-completions,openai-responses,anthropic-messages,google-generative-aiтощо). Для самостійно розміщених бекендів/v1/chat/completions, таких як MLX, vLLM, SGLang і більшість локальних серверів, сумісних з OpenAI, використовуйтеopenai-completions. Користувацький постачальник ізbaseUrl, але безapi, типово використовуєopenai-completions; задавайтеopenai-responsesлише тоді, коли бекенд підтримує/v1/responses.models.providers.*.apiKey: облікові дані постачальника (бажано SecretRef/підстановка env).models.providers.*.auth: стратегія автентифікації (api-key,token,oauth,aws-sdk).models.providers.*.contextWindow: типове нативне контекстне вікно для моделей цього постачальника, коли запис моделі не задаєcontextWindow.models.providers.*.contextTokens: типове ефективне обмеження контексту під час виконання для моделей цього постачальника, коли запис моделі не задаєcontextTokens.models.providers.*.maxTokens: типове обмеження вихідних токенів для моделей цього постачальника, коли запис моделі не задаєmaxTokens.models.providers.*.timeoutSeconds: необов’язковий тайм-аут HTTP-запиту моделі для кожного постачальника в секундах, включно з підключенням, заголовками, тілом і загальною обробкою переривання запиту.models.providers.*.injectNumCtxForOpenAICompat: для Ollama +openai-completionsдодаватиoptions.num_ctxу запити (типово:true).models.providers.*.authHeader: примусово передавати облікові дані в заголовкуAuthorization, коли це потрібно.models.providers.*.baseUrl: базова URL-адреса upstream API.models.providers.*.headers: додаткові статичні заголовки для маршрутизації проксі/тенанта.
Перевизначення транспорту запитів
Перевизначення транспорту запитів
models.providers.*.request: перевизначення транспорту для HTTP-запитів до постачальника моделей.request.headers: додаткові заголовки (об’єднуються з типовими заголовками постачальника). Значення приймають SecretRef.request.auth: перевизначення стратегії автентифікації. Режими:"provider-default"(використовувати вбудовану автентифікацію постачальника),"authorization-bearer"(зtoken),"header"(зheaderName,value, необов’язковимprefix).request.proxy: перевизначення HTTP-проксі. Режими:"env-proxy"(використовувати змінні середовищаHTTP_PROXY/HTTPS_PROXY),"explicit-proxy"(зurl). Обидва режими приймають необов’язковий підоб’єктtls.request.tls: перевизначення TLS для прямих підключень. Поля:ca,cert,key,passphrase(усі приймають SecretRef),serverName,insecureSkipVerify.request.allowPrivateNetwork: колиtrue, дозволяє HTTP-запити до постачальника моделей у приватні, CGNAT або подібні діапазони через HTTP-захист fetch постачальника. Базові URL-адреси користувацьких/локальних постачальників уже довіряють точно налаштованому origin, крім metadata/link-local origin, які залишаються заблокованими без явного ввімкнення. Установіть це вfalse, щоб відмовитися від довіри до точного origin. WebSocket використовує той самийrequestдля заголовків/TLS, але не цей fetch SSRF gate. Типовоfalse.
Записи каталогу моделей
Записи каталогу моделей
models.providers.*.models: явні записи каталогу моделей постачальника.models.providers.*.models.*.input: модальності введення моделі. Використовуйте["text"]для моделей лише з текстом і["text", "image"]для нативних моделей із зображеннями/vision. Вкладення зображень додаються до ходів агента лише тоді, коли вибрана модель позначена як здатна працювати із зображеннями.models.providers.*.models.*.contextWindow: метадані нативного контекстного вікна моделі. Це перевизначаєcontextWindowрівня постачальника для цієї моделі.models.providers.*.models.*.contextTokens: необов’язкове обмеження контексту під час виконання. Це перевизначаєcontextTokensрівня постачальника; використовуйте його, коли потрібен менший ефективний бюджет контексту, ніж нативнеcontextWindowмоделі;openclaw models listпоказує обидва значення, коли вони відрізняються.models.providers.*.models.*.compat.supportsDeveloperRole: необов’язкова підказка сумісності. Дляapi: "openai-completions"із непорожнім ненативнимbaseUrl(хост неapi.openai.com) OpenClaw примусово встановлює це вfalseпід час виконання. Порожній/пропущенийbaseUrlзберігає типову поведінку OpenAI.models.providers.*.models.*.compat.requiresStringContent: необов’язкова підказка сумісності для сумісних з OpenAI chat-ендпоінтів лише з рядковим вмістом. Колиtrue, OpenClaw сплющує масиви чистого текстуmessages[].contentу звичайні рядки перед надсиланням запиту.models.providers.*.models.*.compat.strictMessageKeys: необов’язкова підказка сумісності для строгих сумісних з OpenAI chat-ендпоінтів. Колиtrue, OpenClaw обрізає вихідні об’єкти повідомлень Chat Completions доroleіcontentперед надсиланням запиту.models.providers.*.models.*.compat.thinkingFormat: необов’язкова підказка формату thinking payload. Використовуйте"together"для Together-стилюreasoning.enabled,"qwen"для верхньорівневогоenable_thinkingабо"qwen-chat-template"дляchat_template_kwargs.enable_thinkingна серверах сімейства Qwen, сумісних з OpenAI, які підтримують request-level chat-template kwargs, наприклад vLLM. Налаштовані моделі vLLM Qwen надають бінарні варіанти/think(off,on) для цих форматів.models.providers.*.models.*.compat.requiresReasoningContentOnAssistantMessages: необов’язкова підказка сумісності для бекендів Chat Completions у стилі DeepSeek, які вимагають зберігатиreasoning_contentу попередніх повідомленнях асистента під час повторного відтворення. Колиtrue, OpenClaw зберігає це поле у вихідних повідомленнях асистента. Використовуйте це під час підключення користувацького сумісного з DeepSeek проксі, який відхиляє запити після видаленого reasoning. Типовоfalse.
Виявлення 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: необов’язковий фільтр provider-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)
Офіційний зовнішній Plugin постачальника Використовуйте
cerebras може налаштувати це через openclaw onboard --auth-choice cerebras-api-key. Використовуйте явну конфігурацію постачальника лише під час перевизначення типових значень.cerebras/zai-glm-4.7 для Cerebras; zai/glm-4.7 для прямого Z.AI.Kimi Coding
Kimi Coding
openclaw onboard --auth-choice kimi-code-api-key.Локальні моделі (LM Studio)
Локальні моделі (LM Studio)
Див. Локальні моделі. Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; залишайте розміщені моделі об’єднаними для резервного варіанту.
MiniMax M3 (напряму)
MiniMax M3 (напряму)
MINIMAX_API_KEY. Скорочення: openclaw onboard --auth-choice minimax-global-api або openclaw onboard --auth-choice minimax-cn-api. Каталог моделей типово використовує M3 і також містить варіанти M2.7. На сумісному з Anthropic streaming-шляху OpenClaw типово вимикає MiniMax M2.x thinking, якщо ви явно не задасте thinking самостійно; MiniMax-M3 (і M3.x) типово залишається на omitted/adaptive 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 оголошують сумісність streaming usage на спільному транспорті openai-completions, а OpenClaw визначає це за можливостями ендпоінта, а не лише за вбудованим ID постачальника.OpenCode
OpenCode
OPENCODE_API_KEY (або OPENCODE_ZEN_API_KEY). Використовуйте refs opencode/... для каталогу Zen або refs opencode-go/... для каталогу Go. Скорочення: 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. Посилання на моделі використовують канонічний ідентифікатор провайдера zai/*. Скорочення: openclaw onboard --auth-choice zai-api-key.- Загальна кінцева точка:
https://api.z.ai/api/paas/v4 - Кінцева точка для кодування (типово):
https://api.z.ai/api/coding/paas/v4 - Для загальної кінцевої точки визначте власного провайдера з перевизначенням базового URL.
Пов’язане
- Конфігурація — агенти
- Конфігурація — канали
- Довідник конфігурації — інші ключі верхнього рівня
- Інструменти та plugins