設定リファレンス
~/.openclaw/openclaw.json のコア設定リファレンスです。タスク指向の概要については、Configuration を参照してください。
このページでは、主要なOpenClawの設定面を扱い、サブシステムに独自のより詳細なリファレンスがある場合はリンクを示します。このページでは、すべてのchannel/plugin所有のコマンドカタログや、すべての詳細なmemory/QMDノブを1ページにインライン展開しようとはしていません。
コード上の真実:
openclaw config schemaは、検証およびControl UIで使用されるライブJSON Schemaを出力し、利用可能な場合はbundled/plugin/channelメタデータがマージされますconfig.schema.lookupは、詳細確認用ツール向けに1つのパススコープschemaノードを返しますpnpm config:docs:check/pnpm config:docs:genは、config-docベースラインハッシュを現在のschema面に対して検証します
agents.defaults.memorySearch.*、memory.qmd.*、memory.citations、およびplugins.entries.memory-core.config.dreaming配下のdreaming設定については Memory configuration reference- 現在の組み込み + bundledコマンドカタログについては Slash Commands
- channel固有のコマンド面については各所有channel/pluginページ
Channels
各channelは、その設定セクションが存在すれば自動的に開始されます(enabled: false の場合を除く)。
DMとグループアクセス
すべてのchannelはDMポリシーとグループポリシーをサポートします:| DM policy | 動作 |
|---|---|
pairing (default) | 未知の送信者には1回限りのペアリングコードが送られ、所有者が承認する必要があります |
allowlist | allowFrom(またはペア済みallowストア)内の送信者のみ |
open | すべての受信DMを許可(allowFrom: ["*"] が必要) |
disabled | すべての受信DMを無視 |
| Group policy | 動作 |
|---|---|
allowlist (default) | 設定されたallowlistに一致するグループのみ |
open | グループallowlistをバイパス(mention-gatingは引き続き適用) |
disabled | すべてのgroup/roomメッセージをブロック |
channels.defaults.groupPolicy は、providerの groupPolicy が未設定のときのデフォルトを設定します。
ペアリングコードは1時間後に期限切れになります。保留中のDMペアリング要求は channelごとに3件 に制限されます。
providerブロック自体が完全に欠けている場合(channels.<provider> が存在しない場合)、実行時のgroup policyは allowlist(fail-closed)にフォールバックし、起動時に警告が出ます。Channel modelオーバーライド
特定のchannel IDをmodelに固定するにはchannels.modelByChannel を使います。値には provider/model または設定済みmodel alias を指定できます。このchannelマッピングは、sessionにすでにmodelオーバーライド(たとえば /model で設定)がない場合に適用されます。
Channelのデフォルト値とheartbeat
provider間で共有するgroup-policyとheartbeat動作にはchannels.defaults を使います:
channels.defaults.groupPolicy: providerレベルのgroupPolicyが未設定のときのフォールバックgroup policy。channels.defaults.contextVisibility: 全channelの補足context可視性モードのデフォルト。値:all(デフォルト、引用/スレッド/履歴contextをすべて含む)、allowlist(allowlisted senderからのcontextのみ含む)、allowlist_quote(allowlistと同じだが明示的なquote/reply contextを保持)。channelごとのオーバーライド:channels.<channel>.contextVisibility。channels.defaults.heartbeat.showOk: 正常なchannelステータスをheartbeat出力に含めます。channels.defaults.heartbeat.showAlerts: 劣化/エラーステータスをheartbeat出力に含めます。channels.defaults.heartbeat.useIndicator: コンパクトなインジケーター形式のheartbeat出力を描画します。
マルチアカウントWhatsApp
マルチアカウントWhatsApp
- 送信コマンドは、
defaultアカウントが存在する場合はそれを、そうでない場合は最初に設定されたアカウントid(ソート順)をデフォルトで使用します。 - 任意の
channels.whatsapp.defaultAccountは、設定済みアカウントidと一致する場合、このフォールバックのデフォルトアカウント選択を上書きします。 - レガシーな単一アカウントBaileys認証ディレクトリは、
openclaw doctorによってwhatsapp/defaultへ移行されます。 - アカウントごとのオーバーライド:
channels.whatsapp.accounts.<id>.sendReadReceipts、channels.whatsapp.accounts.<id>.dmPolicy、channels.whatsapp.accounts.<id>.allowFrom。
Telegram
- Bot token:
channels.telegram.botTokenまたはchannels.telegram.tokenFile(通常ファイルのみ。symlinkは拒否)、デフォルトアカウントのフォールバックとしてTELEGRAM_BOT_TOKENも使用可能です。 - 任意の
channels.telegram.defaultAccountは、設定済みアカウントidと一致する場合、デフォルトアカウント選択を上書きします。 - マルチアカウント構成(2つ以上のアカウントid)では、フォールバックルーティングを避けるため明示的なデフォルト(
channels.telegram.defaultAccountまたはchannels.telegram.accounts.default)を設定してください。これが欠けているか無効な場合、openclaw doctorが警告します。 configWrites: falseは、Telegram起点のconfig書き込み(supergroup ID移行、/config set|unset)をブロックします。- 最上位の
bindings[]エントリーでtype: "acp"を持つものは、forum topic向けの永続ACPバインディングを設定します(match.peer.idには正規のchatId:topic:topicIdを使用)。フィールドの意味は ACP Agents と共通です。 - Telegramのstream previewは
sendMessage+editMessageTextを使用します(direct chatとgroup chatの両方で機能します)。 - Retryポリシー: Retry policy を参照してください。
Discord
- Token:
channels.discord.token。デフォルトアカウントのフォールバックとしてDISCORD_BOT_TOKENを使用します。 - 明示的なDiscord
tokenを指定する直接送信呼び出しでは、その呼び出しにそのtokenを使用します。アカウントのretry/policy設定は、アクティブなruntime snapshotで選択されたアカウントから引き続き取得されます。 - 任意の
channels.discord.defaultAccountは、設定済みアカウントidと一致する場合、デフォルトアカウント選択を上書きします。 - 配信先ターゲットには
user:<id>(DM)またはchannel:<id>(guild channel)を使用します。数字のみのIDは拒否されます。 - Guild slugは小文字で、空白は
-に置き換えられます。channelキーにはslug化された名前(#なし)を使用します。guild IDを優先してください。 - Bot自身が投稿したメッセージはデフォルトで無視されます。
allowBots: trueで有効化できます。botにmentionしたbotメッセージのみ受け入れるにはallowBots: "mentions"を使用します(自分自身のメッセージは引き続き除外されます)。 channels.discord.guilds.<id>.ignoreOtherMentions(およびchannelオーバーライド)は、別のユーザーまたはroleにmentionしているがbotにはmentionしていないメッセージを破棄します(@everyone/@hereは除く)。maxLinesPerMessage(デフォルト17)は、2000文字未満でも行数の多いメッセージを分割します。channels.discord.threadBindingsはDiscordのthread-bound routingを制御します:enabled: thread-bound session機能(/focus、/unfocus、/agents、/session idle、/session max-age、およびbound delivery/routing)のDiscordオーバーライドidleHours: 非アクティブ時の自動unfocusのDiscordオーバーライド(時間単位、0で無効)maxAgeHours: ハード最大期間のDiscordオーバーライド(時間単位、0で無効)spawnSubagentSessions:sessions_spawn({ thread: true })に対する自動thread作成/バインドのopt-inスイッチ
- 最上位の
bindings[]エントリーでtype: "acp"を持つものは、channelおよびthread向けの永続ACPバインディングを設定します(match.peer.idにはchannel/thread idを使用)。フィールドの意味は ACP Agents と共通です。 channels.discord.ui.components.accentColorは、Discord components v2 containerのアクセントカラーを設定します。channels.discord.voiceは、Discord voice channel会話と任意のauto-join + TTSオーバーライドを有効にします。channels.discord.voice.daveEncryptionおよびchannels.discord.voice.decryptionFailureToleranceは、@discordjs/voiceのDAVEオプションにそのまま渡されます(デフォルトはtrueと24)。- OpenClawはさらに、繰り返しdecrypt失敗が起きた後にvoice sessionを退出/再参加することでvoice receive recoveryも試みます。
channels.discord.streamingが正規のstream modeキーです。レガシーなstreamModeと真偽値streamingは自動移行されます。channels.discord.autoPresenceはruntimeの可用性をbot presenceに対応付けます(healthy => online、degraded => idle、exhausted => dnd)。任意のstatus textオーバーライドも可能です。channels.discord.dangerouslyAllowNameMatchingは、可変なname/tag一致を再有効化します(緊急避難用の互換モード)。channels.discord.execApprovals: Discordネイティブのexec承認配信と承認者認可。enabled:true、false、または"auto"(デフォルト)。autoモードでは、approversまたはcommands.ownerAllowFromから承認者を解決できる場合にexec承認が有効になります。approvers: exec要求を承認できるDiscord user ID。省略時はcommands.ownerAllowFromにフォールバックします。agentFilter: 任意のagent ID allowlist。省略するとすべてのagentの承認を転送します。sessionFilter: 任意のsession key pattern(部分文字列またはregex)。target: 承認プロンプトの送信先。"dm"(デフォルト)は承認者DMへ、"channel"は元channelへ、"both"は両方へ送信します。targetに"channel"を含む場合、ボタンは解決済み承認者のみ使用できます。cleanupAfterResolve:trueの場合、承認、拒否、またはtimeout後に承認DMを削除します。
off(なし)、own(botのメッセージ、デフォルト)、all(すべてのメッセージ)、allowlist(すべてのメッセージに対して guilds.<id>.users から)。
Google Chat
- Service account JSON: インライン(
serviceAccount)またはファイルベース(serviceAccountFile)。 - Service account SecretRefもサポートされています(
serviceAccountRef)。 - Envフォールバック:
GOOGLE_CHAT_SERVICE_ACCOUNTまたはGOOGLE_CHAT_SERVICE_ACCOUNT_FILE。 - 配信先ターゲットには
spaces/<spaceId>またはusers/<userId>を使用します。 channels.googlechat.dangerouslyAllowNameMatchingは、可変なemail principal一致を再有効化します(緊急避難用の互換モード)。
Slack
- Socket mode では
botTokenとappTokenの両方が必要です(デフォルトアカウントのenvフォールバックとしてSLACK_BOT_TOKEN+SLACK_APP_TOKEN)。 - HTTP mode では
botTokenとsigningSecret(ルートまたはアカウントごと)が必要です。 botToken、appToken、signingSecret、userTokenは平文文字列またはSecretRefオブジェクトを受け付けます。- Slackアカウントsnapshotは、
botTokenSource、botTokenStatus、appTokenStatus、HTTP modeではsigningSecretStatusなどの資格情報ごとのsource/statusフィールドを公開します。configured_unavailableは、そのアカウントがSecretRefで設定されているが、現在のcommand/runtime pathではsecret値を解決できなかったことを意味します。 configWrites: falseはSlack起点のconfig書き込みをブロックします。- 任意の
channels.slack.defaultAccountは、設定済みアカウントidと一致する場合、デフォルトアカウント選択を上書きします。 channels.slack.streaming.modeが正規のSlack stream modeキーです。channels.slack.streaming.nativeTransportはSlackのネイティブstreaming transportを制御します。レガシーなstreamMode、真偽値streaming、nativeStreamingは自動移行されます。- 配信先ターゲットには
user:<id>(DM)またはchannel:<id>を使用します。
off、own(デフォルト)、all、allowlist(reactionAllowlist から)。
Thread session isolation: thread.historyScope はthread単位(デフォルト)またはchannel共有です。thread.inheritParent は親channelのtranscriptを新しいthreadにコピーします。
- SlackネイティブstreamingとSlack assistant風の「is typing…」thread statusにはreply thread targetが必要です。最上位DMはデフォルトでthread外のままなので、thread風previewではなく
typingReactionまたは通常配信が使用されます。 typingReactionは、replyの実行中に受信Slackメッセージへ一時的にreactionを追加し、完了時に削除します。"hourglass_flowing_sand"のようなSlack emoji shortcodeを使用してください。channels.slack.execApprovals: Slackネイティブのexec承認配信と承認者認可。schemaはDiscordと同じです:enabled(true/false/"auto")、approvers(Slack user ID)、agentFilter、sessionFilter、target("dm"、"channel"、または"both")。
| Action group | Default | 注記 |
|---|---|---|
| reactions | enabled | React + reaction一覧 |
| messages | enabled | 読み取り/送信/編集/削除 |
| pins | enabled | Pin/unpin/list |
| memberInfo | enabled | Member情報 |
| emojiList | enabled | カスタムemoji一覧 |
Mattermost
Mattermostはpluginとして提供されます:openclaw plugins install @openclaw/mattermost。
oncall(@-mention時に応答、デフォルト)、onmessage(すべてのメッセージ)、onchar(トリガーprefixで始まるメッセージ)。
Mattermostネイティブコマンドが有効な場合:
commands.callbackPathはフルURLではなくパスでなければなりません(例:/api/channels/mattermost/command)。commands.callbackUrlはOpenClaw gateway endpointに解決され、Mattermostサーバーから到達可能である必要があります。- ネイティブslash callbackは、slash command登録時にMattermostが返すコマンドごとのtokenで認証されます。登録に失敗した場合、または有効なコマンドがない場合、OpenClawは callbackを
Unauthorized: invalid command token.で拒否します。 - 非公開/tailnet/internal callback hostでは、Mattermostが
ServiceSettings.AllowedUntrustedInternalConnectionsにcallback host/domainを含める必要があることがあります。 フルURLではなくhost/domain値を使用してください。 channels.mattermost.configWrites: Mattermost起点のconfig書き込みを許可または拒否します。channels.mattermost.requireMention: channel内で返信する前に@mentionを必須にします。channels.mattermost.groups.<channelId>.requireMention: channelごとのmention-gatingオーバーライド(デフォルトには"*")。- 任意の
channels.mattermost.defaultAccountは、設定済みアカウントidと一致する場合、デフォルトアカウント選択を上書きします。
Signal
off、own(デフォルト)、all、allowlist(reactionAllowlist から)。
channels.signal.account: channelの起動先を特定のSignalアカウントidentityに固定します。channels.signal.configWrites: Signal起点のconfig書き込みを許可または拒否します。- 任意の
channels.signal.defaultAccountは、設定済みアカウントidと一致する場合、デフォルトアカウント選択を上書きします。
BlueBubbles
BlueBubblesは推奨されるiMessage経路です(pluginベース、channels.bluebubbles 配下で設定)。
- ここで扱うコアキーパス:
channels.bluebubbles、channels.bluebubbles.dmPolicy。 - 任意の
channels.bluebubbles.defaultAccountは、設定済みアカウントidと一致する場合、デフォルトアカウント選択を上書きします。 - 最上位の
bindings[]エントリーでtype: "acp"を持つものは、BlueBubbles会話を永続ACP sessionにバインドできます。match.peer.idにはBlueBubbles handleまたはtarget文字列(chat_id:*、chat_guid:*、chat_identifier:*)を使用してください。共通フィールド意味: ACP Agents。 - 完全なBlueBubbles channel設定は BlueBubbles に記載されています。
iMessage
OpenClawはimsg rpc(stdio上のJSON-RPC)を起動します。daemonやportは不要です。
-
任意の
channels.imessage.defaultAccountは、設定済みアカウントidと一致する場合、デフォルトアカウント選択を上書きします。 - Messages DBへのFull Disk Accessが必要です。
-
chat_id:<id>ターゲットを推奨します。チャット一覧にはimsg chats --limit 20を使用してください。 -
cliPathはSSH wrapperを指すことができます。SCPでattachmentを取得するにはremoteHost(hostまたはuser@host)を設定します。 -
attachmentRootsとremoteAttachmentRootsは受信attachmentパスを制限します(デフォルト:/Users/*/Library/Messages/Attachments)。 -
SCPでは厳格なhost-keyチェックを使うため、relay host keyがすでに
~/.ssh/known_hostsに存在していることを確認してください。 -
channels.imessage.configWrites: iMessage起点のconfig書き込みを許可または拒否します。 -
最上位の
bindings[]エントリーでtype: "acp"を持つものは、iMessage会話を永続ACP sessionにバインドできます。match.peer.idには正規化されたhandleまたは明示的なchat target(chat_id:*、chat_guid:*、chat_identifier:*)を使用してください。共通フィールド意味: ACP Agents。
iMessage SSH wrapper例
iMessage SSH wrapper例
Matrix
Matrixはextensionベースで、channels.matrix 配下で設定します。
- Token認証は
accessTokenを使用し、password認証はuserId+passwordを使用します。 channels.matrix.proxyはMatrix HTTPトラフィックを明示的なHTTP(S) proxy経由にします。名前付きアカウントはchannels.matrix.accounts.<id>.proxyでこれを上書きできます。channels.matrix.network.dangerouslyAllowPrivateNetworkはprivate/internal homeserverを許可します。proxyとこのnetwork opt-inは独立した制御です。channels.matrix.defaultAccountはマルチアカウント構成で優先アカウントを選択します。channels.matrix.autoJoinのデフォルトはoffなので、招待されたroomや新しいDM風の招待は、autoJoin: "allowlist"とautoJoinAllowlist、またはautoJoin: "always"を設定するまで無視されます。channels.matrix.execApprovals: Matrixネイティブのexec承認配信と承認者認可。enabled:true、false、または"auto"(デフォルト)。autoモードでは、approversまたはcommands.ownerAllowFromから承認者を解決できる場合にexec承認が有効になります。approvers: exec要求を承認できるMatrix user ID(例:@owner:example.org)。agentFilter: 任意のagent ID allowlist。省略するとすべてのagentの承認を転送します。sessionFilter: 任意のsession key pattern(部分文字列またはregex)。target: 承認プロンプトの送信先。"dm"(デフォルト)、"channel"(元room)、または"both"。- アカウントごとのオーバーライド:
channels.matrix.accounts.<id>.execApprovals。
channels.matrix.dm.sessionScopeはMatrix DMがsessionへどうグループ化されるかを制御します:per-user(デフォルト)はroutingされたpeer単位で共有し、per-roomは各DM roomを分離します。- Matrix status probeとlive directory lookupはruntime trafficと同じproxy policyを使用します。
- 完全なMatrix設定、ターゲティングルール、セットアップ例は Matrix に記載されています。
Microsoft Teams
Microsoft Teamsはextensionベースで、channels.msteams 配下で設定します。
- ここで扱うコアキーパス:
channels.msteams、channels.msteams.configWrites。 - 完全なTeams設定(資格情報、webhook、DM/group policy、team/channelごとのオーバーライド)は Microsoft Teams に記載されています。
IRC
IRCはextensionベースで、channels.irc 配下で設定します。
- ここで扱うコアキーパス:
channels.irc、channels.irc.dmPolicy、channels.irc.configWrites、channels.irc.nickserv.*。 - 任意の
channels.irc.defaultAccountは、設定済みアカウントidと一致する場合、デフォルトアカウント選択を上書きします。 - 完全なIRC channel設定(host/port/TLS/channels/allowlist/mention gating)は IRC に記載されています。
マルチアカウント(全channel共通)
channelごとに複数アカウント(それぞれ独自のaccountId)を実行します:
accountIdが省略された場合、defaultが使われます(CLI + routing)。- Env tokenは default アカウントにのみ適用されます。
- ベースchannel設定は、アカウントごとに上書きされない限り、すべてのアカウントに適用されます。
- 各アカウントを異なるagentへルーティングするには
bindings[].match.accountIdを使用します。 - 単一アカウントの最上位channel configのまま
openclaw channels add(またはchannel onboarding)で非defaultアカウントを追加すると、OpenClawは最初にアカウントスコープの最上位単一アカウント値をそのchannel account mapへ昇格し、元のアカウントが引き続き動作するようにします。ほとんどのchannelではこれらをchannels.<channel>.accounts.defaultへ移動しますが、Matrixは既存の一致するnamed/default targetを保持できます。 - 既存のchannel専用binding(
accountIdなし)は引き続きdefaultアカウントに一致します。accountスコープbindingは引き続き任意です。 openclaw doctor --fixも、アカウントスコープの最上位単一アカウント値をそのchannelで選ばれた昇格先アカウントへ移動することで混在形状を修復します。ほとんどのchannelはaccounts.defaultを使用し、Matrixは既存の一致するnamed/default targetを保持できます。
その他のextension channel
多くのextension channelはchannels.<id> として設定され、専用のchannelページに記載されています(たとえば Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat、Twitch)。
完全なchannel索引: Channels。
グループチャットmention gating
グループメッセージはデフォルトで mention必須 です(メタデータmentionまたは安全なregex pattern)。WhatsApp、Telegram、Discord、Google Chat、iMessageのグループチャットに適用されます。 Mentionの種類:- Metadata mentions: ネイティブプラットフォームの @-mention。WhatsApp self-chat modeでは無視されます。
- Text patterns:
agents.list[].groupChat.mentionPatterns内の安全なregex pattern。無効なpatternや安全でない入れ子反復は無視されます。 - Mention gatingは、検出が可能な場合(ネイティブmentionまたは少なくとも1つのpatternがある場合)にのみ適用されます。
messages.groupChat.historyLimit はグローバルデフォルトを設定します。channel側で channels.<channel>.historyLimit(またはアカウントごと)で上書きできます。無効化するには 0 を設定します。
DM履歴上限
telegram、whatsapp、discord、slack、signal、imessage、msteams。
Self-chat mode
自分自身の番号をallowFrom に含めるとself-chat modeが有効になります(ネイティブ @-mentionを無視し、text patternにのみ応答):
Commands(チャットコマンド処理)
コマンド詳細
コマンド詳細
Agent defaults
agents.defaults.workspace
デフォルト: ~/.openclaw/workspace。
agents.defaults.repoRoot
system promptのRuntime行に表示される任意のrepository rootです。未設定の場合、OpenClawはworkspaceから上方向へたどって自動検出します。
agents.defaults.skills
agents.list[].skills を設定していないagent向けの任意のデフォルトskill allowlistです。
- デフォルトで制限なしのSkillsにするには
agents.defaults.skillsを省略します。 - デフォルト値を継承するには
agents.list[].skillsを省略します。 - skillなしにするには
agents.list[].skills: []を設定します。 - 空でない
agents.list[].skills一覧は、そのagentの最終セットです。デフォルトとはマージされません。
agents.defaults.skipBootstrap
workspace bootstrapファイル(AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md)の自動作成を無効化します。
agents.defaults.contextInjection
workspace bootstrapファイルがsystem promptに注入されるタイミングを制御します。デフォルトは "always" です。
"continuation-skip": 安全な継続ターン(assistantの応答完了後)ではworkspace bootstrapの再注入をスキップし、promptサイズを削減します。heartbeat実行やcompaction後の再試行では引き続きcontextを再構築します。
agents.defaults.bootstrapMaxChars
切り詰め前のworkspace bootstrapファイルごとの最大文字数。デフォルト: 20000。
agents.defaults.bootstrapTotalMaxChars
全workspace bootstrapファイルにまたがって注入される総最大文字数。デフォルト: 150000。
agents.defaults.bootstrapPromptTruncationWarning
bootstrap contextが切り詰められたときにagentへ見える警告文を制御します。
デフォルト: "once"。
"off": 警告文をsystem promptへ一切注入しません。"once": 一意の切り詰め署名ごとに1回だけ警告を注入します(推奨)。"always": 切り詰めが存在するたびに毎回警告を注入します。
agents.defaults.imageMaxDimensionPx
provider呼び出し前にtranscript/tool image blockで長辺に許可される最大ピクセルサイズ。
デフォルト: 1200。
低い値は通常、vision token使用量とrequest payloadサイズを削減します。
高い値はより多くの視覚的詳細を保持します。
agents.defaults.userTimezone
system prompt context用のtimezoneです(メッセージtimestampではありません)。ホストtimezoneにフォールバックします。
agents.defaults.timeFormat
system prompt内の時刻形式。デフォルト: auto(OS設定)。
agents.defaults.model
model: 文字列("provider/model")またはオブジェクト({ primary, fallbacks })のいずれかを受け付けます。- 文字列形式はprimary modelのみを設定します。
- オブジェクト形式はprimaryに加えて順序付きfailover modelを設定します。
imageModel: 文字列("provider/model")またはオブジェクト({ primary, fallbacks })のいずれかを受け付けます。imagetool pathがvision-model設定として使用します。- 選択済み/デフォルトmodelがimage入力を受け付けられない場合のフォールバックroutingにも使用されます。
imageGenerationModel: 文字列("provider/model")またはオブジェクト({ primary, fallbacks })のいずれかを受け付けます。- 共有image-generation capabilityと、将来のimage生成tool/plugin面で使用されます。
- 一般的な値: Geminiネイティブimage生成には
google/gemini-3.1-flash-image-preview、falにはfal/fal-ai/flux/dev、OpenAI Imagesにはopenai/gpt-image-1。 - provider/modelを直接選択する場合は、対応するprovider auth/API keyも設定してください(たとえば
google/*ならGEMINI_API_KEYまたはGOOGLE_API_KEY、openai/*ならOPENAI_API_KEY、fal/*ならFAL_KEY)。 - 省略した場合でも、
image_generateはauth付きproviderデフォルトを推測できます。まず現在のデフォルトproviderを試し、その後残りの登録済みimage-generation providerをprovider-id順に試します。
musicGenerationModel: 文字列("provider/model")またはオブジェクト({ primary, fallbacks })のいずれかを受け付けます。- 共有music-generation capabilityと組み込み
music_generatetoolで使用されます。 - 一般的な値:
google/lyria-3-clip-preview、google/lyria-3-pro-preview、またはminimax/music-2.5+。 - 省略した場合でも、
music_generateはauth付きproviderデフォルトを推測できます。まず現在のデフォルトproviderを試し、その後残りの登録済みmusic-generation providerをprovider-id順に試します。 - provider/modelを直接選択する場合は、対応するprovider auth/API keyも設定してください。
- 共有music-generation capabilityと組み込み
videoGenerationModel: 文字列("provider/model")またはオブジェクト({ primary, fallbacks })のいずれかを受け付けます。- 共有video-generation capabilityと組み込み
video_generatetoolで使用されます。 - 一般的な値:
qwen/wan2.6-t2v、qwen/wan2.6-i2v、qwen/wan2.6-r2v、qwen/wan2.6-r2v-flash、またはqwen/wan2.7-r2v。 - 省略した場合でも、
video_generateはauth付きproviderデフォルトを推測できます。まず現在のデフォルトproviderを試し、その後残りの登録済みvideo-generation providerをprovider-id順に試します。 - provider/modelを直接選択する場合は、対応するprovider auth/API keyも設定してください。
- bundledのQwen video-generation providerは、最大1本の出力video、1枚の入力image、4本の入力video、10秒のduration、およびproviderレベルの
size、aspectRatio、resolution、audio、watermarkオプションをサポートします。
- 共有video-generation capabilityと組み込み
pdfModel: 文字列("provider/model")またはオブジェクト({ primary, fallbacks })のいずれかを受け付けます。pdftoolのmodel routingに使用されます。- 省略時、PDF toolは
imageModelにフォールバックし、その後解決済みsession/default modelへフォールバックします。
pdfMaxBytesMb:pdftoolで呼び出し時にmaxBytesMbが渡されない場合のデフォルトPDFサイズ上限。pdfMaxPages:pdftoolの抽出フォールバックモードで考慮されるデフォルト最大ページ数。verboseDefault: agentのデフォルトverboseレベル。値:"off"、"on"、"full"。デフォルト:"off"。elevatedDefault: agentのデフォルトelevated-outputレベル。値:"off"、"on"、"ask"、"full"。デフォルト:"on"。model.primary: 形式はprovider/model(例:openai/gpt-5.4)。providerを省略すると、OpenClawはまずaliasを試し、次にその正確なmodel idに一致する一意のconfigured-provider matchを試し、その後でのみ設定済みデフォルトproviderへフォールバックします(レガシー互換動作のため非推奨なので、明示的なprovider/modelを推奨)。そのproviderが設定済みデフォルトmodelを提供しなくなった場合、OpenClawは古い削除済みproviderデフォルトを表示する代わりに、最初の設定済みprovider/modelへフォールバックします。models: 設定されたmodel catalogおよび/model用allowlistです。各エントリーにはalias(短縮名)とparams(provider固有、たとえばtemperature、maxTokens、cacheRetention、context1m)を含められます。params: すべてのmodelに適用されるグローバルデフォルトprovider parameterです。agents.defaults.paramsで設定します(例:{ cacheRetention: "long" })。paramsのマージ優先順位(config):agents.defaults.params(グローバルベース)はagents.defaults.models["provider/model"].params(modelごと)で上書きされ、その後agents.list[].params(一致するagent id)がキーごとに上書きします。詳細は Prompt Caching を参照してください。- これらのフィールドを変更するconfig writer(たとえば
/models set、/models set-image、fallback add/remove command)は、可能な限り既存fallback listを保持しつつ正規のobject formで保存します。 maxConcurrent: sessionをまたいだ並列agent実行の最大数(各session自体は引き続き直列化されます)。デフォルト: 4。
agents.defaults.models にある場合のみ適用):
| Alias | Model |
|---|---|
opus | anthropic/claude-opus-4-6 |
sonnet | anthropic/claude-sonnet-4-6 |
gpt | openai/gpt-5.4 |
gpt-mini | openai/gpt-5.4-mini |
gpt-nano | openai/gpt-5.4-nano |
gemini | google/gemini-3.1-pro-preview |
gemini-flash | google/gemini-3-flash-preview |
gemini-flash-lite | google/gemini-3.1-flash-lite-preview |
--thinking off を設定するか agents.defaults.models["zai/<model>"].params.thinking を自分で定義しない限り、自動的にthinking modeが有効になります。
Z.AI modelではtool call streaming向けにデフォルトで tool_stream が有効です。無効にするには agents.defaults.models["zai/<model>"].params.tool_stream を false に設定してください。
Anthropic Claude 4.6 modelでは、明示的なthinking levelが設定されていない場合、デフォルトで adaptive thinkingになります。
agents.defaults.cliBackends
text-onlyフォールバック実行(tool callなし)向けの任意のCLI backendです。API providerが失敗したときのバックアップとして便利です。
- CLI backendはtext-firstです。toolは常に無効です。
sessionArgが設定されていればsessionをサポートします。imageArgがfile pathを受け付ける場合、image pass-throughをサポートします。
agents.defaults.systemPromptOverride
OpenClawが組み立てたsystem prompt全体を固定文字列で置き換えます。デフォルトレベル(agents.defaults.systemPromptOverride)またはagentごと(agents.list[].systemPromptOverride)で設定します。agentごとの値が優先され、空または空白のみの値は無視されます。制御されたprompt実験に便利です。
agents.defaults.heartbeat
定期heartbeat実行です。
every: duration文字列(ms/s/m/h)。デフォルト:30m(API-key認証)または1h(OAuth認証)。無効化するには0mを設定します。includeSystemPromptSection: false の場合、system promptからHeartbeatセクションを省略し、bootstrap contextへのHEARTBEAT.md注入もスキップします。デフォルト:true。suppressToolErrorWarnings: true の場合、heartbeat実行中のtool error warning payloadを抑制します。directPolicy: direct/DM配信ポリシー。allow(デフォルト)はdirect-target配信を許可します。blockはdirect-target配信を抑制し、reason=dm-blockedを出力します。lightContext: true の場合、heartbeat実行は軽量bootstrap contextを使用し、workspace bootstrap fileからHEARTBEAT.mdのみを保持します。isolatedSession: true の場合、各heartbeatは以前の会話履歴を持たない新しいsessionで実行されます。cronのsessionTarget: "isolated"と同じ分離パターンです。heartbeatごとのtokenコストを約100Kから約2-5K tokenへ削減します。- agentごと:
agents.list[].heartbeatを設定します。いずれかのagentがheartbeatを定義すると、heartbeatを実行するのは それらのagentのみ になります。 - Heartbeatは完全なagent turnを実行します — 短い間隔ほど多くのtokenを消費します。
agents.defaults.compaction
mode:defaultまたはsafeguard(長い履歴向けのchunked summarization)。Compaction を参照してください。provider: 登録済みcompaction provider pluginのid。設定すると、組み込みLLM summarizationの代わりにそのproviderのsummarize()が呼ばれます。失敗時は組み込みへフォールバックします。providerを設定するとmode: "safeguard"が強制されます。Compaction を参照してください。timeoutSeconds: OpenClawが中止するまでの単一compaction操作の最大秒数。デフォルト:900。identifierPolicy:strict(デフォルト)、off、またはcustom。strictはcompaction summarization時に組み込みのopaque identifier保持ガイダンスを先頭に追加します。identifierInstructions:identifierPolicy=customのときに使う任意のカスタムidentifier保持文。postCompactionSections: compaction後に再注入する任意のAGENTS.md H2/H3セクション名。デフォルトは["Session Startup", "Red Lines"]。無効化するには[]を設定します。未設定、またはそのデフォルト組が明示設定されている場合、古いEvery Session/Safety見出しもレガシーフォールバックとして受け付けます。model: compaction summarization専用の任意のprovider/model-idオーバーライド。メインsessionはあるmodelを維持しつつ、compaction summaryだけ別modelで実行したい場合に使います。未設定時はcompactionはsessionのprimary modelを使用します。notifyUser:trueの場合、compaction開始時にユーザーへ短い通知(例: 「Compacting context…」)を送信します。compactionを静かに保つため、デフォルトでは無効です。memoryFlush: 自動compaction前に永続memoryを保存するためのサイレントagentic turn。workspaceがread-onlyの場合はスキップされます。
agents.defaults.contextPruning
LLMへ送信する前に、メモリ内contextから 古いtool result を剪定します。ディスク上のsession historyは変更しません。
cache-ttl modeの動作
cache-ttl modeの動作
mode: "cache-ttl"でpruning passが有効になります。ttlは、最後のcache touch後に再びpruningを実行できるまでの頻度を制御します。- Pruningは、必要に応じてまず大きすぎるtool resultをsoft-trimし、その後より古いtool resultをhard-clearします。
... を挿入します。Hard-clear はtool result全体をplaceholderで置き換えます。注記:- Image blockは切り詰め/クリアされません。
- 比率はtoken数ではなく文字数ベース(概算)です。
keepLastAssistants未満のassistant messageしか存在しない場合、pruningはスキップされます。
Block streaming
- Telegram以外のchannelでは、block replyを有効にするには明示的な
*.blockStreaming: trueが必要です。 - Channelごとのオーバーライド:
channels.<channel>.blockStreamingCoalesce(およびアカウントごとの変種)。Signal/Slack/Discord/Google ChatのデフォルトはminChars: 1500です。 humanDelay: block reply間のランダムな待機。natural= 800–2500ms。agentごとのオーバーライド:agents.list[].humanDelay。
Typing indicators
- デフォルト: direct chat/mentionでは
instant、mentionされていないgroup chatではmessage。 - Sessionごとのオーバーライド:
session.typingMode、session.typingIntervalSeconds。
agents.defaults.sandbox
埋め込みagent向けの任意のsandbox化です。完全なガイドは Sandboxing を参照してください。
Sandbox詳細
Sandbox詳細
Backend:OpenShell mode:
docker: ローカルDocker runtime(デフォルト)ssh: 汎用SSHベースのremote runtimeopenshell: OpenShell runtime
backend: "openshell" を選択した場合、runtime固有設定は
plugins.entries.openshell.config へ移動します。SSH backend設定:target:user@host[:port]形式のSSH targetcommand: SSH client command(デフォルト:ssh)workspaceRoot: スコープごとのworkspaceに使用する絶対remote rootidentityFile/certificateFile/knownHostsFile: OpenSSHへ渡される既存のローカルファイルidentityData/certificateData/knownHostsData: OpenClawがruntime時に一時ファイルへ実体化するインライン内容またはSecretRefstrictHostKeyChecking/updateHostKeys: OpenSSHのhost-key policyノブ
identityDataがidentityFileに優先certificateDataがcertificateFileに優先knownHostsDataがknownHostsFileに優先- SecretRefベースの
*Data値は、sandbox session開始前にアクティブsecrets runtime snapshotから解決されます
- 作成または再作成後にremote workspaceを1回seedする
- その後はremote SSH workspaceを正本として維持する
exec、file tool、media pathをSSH経由でルーティングする- remote変更を自動でホストへ同期しない
- sandbox browser containerをサポートしない
none:~/.openclaw/sandboxes配下のスコープごとのsandbox workspacero: sandbox workspaceは/workspace、agent workspaceは読み取り専用で/agentにmountrw: agent workspaceを読み書き可能で/workspaceにmount
session: sessionごとのcontainer + workspaceagent: agentごとに1つのcontainer + workspace(デフォルト)shared: 共有containerおよびworkspace(session間分離なし)
mirror: exec前にlocalからremoteへseedし、exec後に同期し戻す。local workspaceが正本のままになりますremote: sandbox作成時に1度だけremoteへseedし、その後はremote workspaceを正本として維持します
remote modeでは、OpenClaw外で行われたホストローカル編集は、seedステップ後にsandboxへ自動同期されません。
転送はOpenShell sandboxへのSSHですが、sandboxのライフサイクルと任意のmirror syncはpluginが所有します。setupCommand はcontainer作成後に1回だけ実行されます(sh -lc 経由)。network egress、書き込み可能root、root userが必要です。Containerのデフォルトは network: "none" です — agentに送信アクセスが必要なら "bridge"(またはカスタムbridge network)に設定してください。
"host" はブロックされます。"container:<id>" もデフォルトでブロックされますが、
sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true を明示設定した場合のみ許可されます(緊急避難用)。受信attachment はアクティブworkspace内の media/inbound/* にステージングされます。docker.binds は追加のhost directoryをmountします。グローバルとagentごとのbindはマージされます。Sandboxed browser(sandbox.browser.enabled): container内のChromium + CDP。noVNC URLがsystem promptに注入されます。openclaw.json で browser.enabled を必要としません。
noVNC observer accessはデフォルトでVNC認証を使用し、OpenClawは共有URLにpasswordを露出する代わりに短命token URLを発行します。allowHostControl: false(デフォルト)は、sandboxed sessionがhost browserを対象にすることをブロックします。networkのデフォルトはopenclaw-sandbox-browser(専用bridge network)です。グローバルbridge接続が明示的に必要な場合にのみbridgeに設定してください。cdpSourceRangeは、container境界でCDP ingressをCIDR範囲(例:172.21.0.1/32)へ任意に制限します。sandbox.browser.bindsは追加のhost directoryをsandbox browser containerのみにmountします。設定された場合([]を含む)、browser containerではdocker.bindsを置き換えます。- 起動デフォルトは
scripts/sandbox-browser-entrypoint.shで定義され、container host向けに調整されています:--remote-debugging-address=127.0.0.1--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>--user-data-dir=${HOME}/.chrome--no-first-run--no-default-browser-check--disable-3d-apis--disable-gpu--disable-software-rasterizer--disable-dev-shm-usage--disable-background-networking--disable-features=TranslateUI--disable-breakpad--disable-crash-reporter--renderer-process-limit=2--no-zygote--metrics-recording-only--disable-extensions(デフォルトで有効)--disable-3d-apis、--disable-software-rasterizer、--disable-gpuは デフォルトで有効であり、WebGL/3D利用に必要な場合はOPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0で無効化できます。OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0は、workflowがextensionに依存する場合に extensionを再有効化します。--renderer-process-limit=2はOPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>で変更できます。Chromiumの デフォルトprocess上限を使うには0を設定してください。- 加えて、
noSandboxが有効な場合は--no-sandboxと--disable-setuid-sandbox。 - デフォルトはcontainer imageのベースラインです。containerデフォルトを変更するには、 カスタムentrypointを持つ独自browser imageを使用してください。
sandbox.docker.binds はDocker専用です。
imageのビルド:
agents.list(agentごとのオーバーライド)
id: 安定したagent id(必須)。default: 複数設定されている場合は最初が勝ちます(警告を記録)。どれも設定されていない場合、最初のlist entryがデフォルトです。model: 文字列形式はprimaryのみを上書きし、object形式{ primary, fallbacks }は両方を上書きします([]でグローバルfallbackを無効化)。primaryだけを上書きするcron jobは、fallbacks: []を設定しない限りデフォルトfallbackを継承します。params: 選択されたmodel entryに対してagents.defaults.modelsの上にマージされるagentごとのstream params。cacheRetention、temperature、maxTokensなどagent固有の上書きに使用し、model catalog全体の複製を避けます。skills: 任意のagentごとのskill allowlist。省略時、そのagentは設定されていればagents.defaults.skillsを継承します。明示listはデフォルトとマージせず置き換え、[]はskillなしを意味します。thinkingDefault: 任意のagentごとのデフォルトthinking level(off | minimal | low | medium | high | xhigh | adaptive)。message単位またはsession単位の上書きが未設定のとき、このagentに対してagents.defaults.thinkingDefaultを上書きします。reasoningDefault: 任意のagentごとのデフォルトreasoning visibility(on | off | stream)。message単位またはsession単位のreasoningオーバーライドが未設定のときに適用されます。fastModeDefault: 任意のagentごとのfast modeデフォルト(true | false)。message単位またはsession単位のfast-modeオーバーライドが未設定のときに適用されます。runtime: 任意のagentごとのruntime descriptor。agentがデフォルトでACP harness sessionを使うべき場合は、type: "acp"とruntime.acpのデフォルト(agent、backend、mode、cwd)を使用してください。identity.avatar: workspace相対path、http(s)URL、またはdata:URI。identityはデフォルトを導出します:emojiからackReaction、name/emojiからmentionPatterns。subagents.allowAgents:sessions_spawn用agent id allowlist(["*"]= 任意。デフォルト: 同じagentのみ)。- Sandbox継承ガード: 要求元sessionがsandbox化されている場合、
sessions_spawnはsandbox化されないターゲットを拒否します。 subagents.requireAgentId: true の場合、agentIdを省略したsessions_spawn呼び出しをブロックします(明示的なprofile選択を強制。デフォルト: false)。
マルチagent routing
1つのGateway内で複数の分離されたagentを実行します。Multi-Agent を参照してください。Binding matchフィールド
type(任意): 通常のroutingにはroute(type未指定もroute扱い)、永続ACP会話bindingにはacpmatch.channel(必須)match.accountId(任意。*= 任意のアカウント、省略 = デフォルトアカウント)match.peer(任意。{ kind: direct|group|channel, id })match.guildId/match.teamId(任意。channel固有)acp(任意。type: "acp"のみ):{ mode, label, cwd, backend }
match.peermatch.guildIdmatch.teamIdmatch.accountId(peer/guild/teamなしの完全一致)match.accountId: "*"(channel全体)- デフォルトagent
bindings エントリーが勝ちます。
type: "acp" エントリーでは、OpenClawは正確な会話identity(match.channel + account + match.peer.id)で解決し、上記のroute binding tier順序は使用しません。
Agentごとのaccess profile
完全アクセス(sandboxなし)
完全アクセス(sandboxなし)
読み取り専用tools + workspace
読み取り専用tools + workspace
ファイルシステムアクセスなし(メッセージングのみ)
ファイルシステムアクセスなし(メッセージングのみ)
Session
Sessionフィールド詳細
Sessionフィールド詳細
scope: group-chat context向けの基本session grouping戦略。per-sender(デフォルト): channel context内で各senderごとに分離sessionを持ちます。global: channel context内の全参加者が1つのsessionを共有します(共有contextが意図されている場合にのみ使用してください)。
dmScope: DMのグルーピング方法。main: すべてのDMがmain sessionを共有します。per-peer: channelをまたいでsender idごとに分離します。per-channel-peer: channel + senderごとに分離します(複数ユーザーinboxに推奨)。per-account-channel-peer: account + channel + senderごとに分離します(マルチアカウントに推奨)。
identityLinks: channel間session共有のため、provider prefix付きpeerへ正規idをマップします。reset: 主要resetポリシー。dailyはローカル時刻のatHourにresetし、idleはidleMinutes後にresetします。両方が設定されている場合、先に期限切れになる方が優先されます。resetByType: typeごとのオーバーライド(direct、group、thread)。レガシーdmはdirectのaliasとして受け付けます。parentForkMaxTokens: forked thread session作成時に許可する親sessiontotalTokensの最大値(デフォルト100000)。- 親の
totalTokensがこの値を超える場合、OpenClawは親transcript historyを継承せず、新しいthread sessionを開始します。 - このガードを無効化し、常に親forkを許可するには
0を設定します。
- 親の
mainKey: レガシーフィールド。runtimeはmain direct-chat bucketに常に"main"を使用します。agentToAgent.maxPingPongTurns: agent間やり取り中の応答往復回数の最大値(整数、範囲:0–5)。0はping-pong連鎖を無効化します。sendPolicy:channel、chatType(direct|group|channel。レガシーdmaliasあり)、keyPrefix、またはrawKeyPrefixでmatchします。最初のdenyが勝ちます。maintenance: session-storeのcleanup + retention制御。mode:warnは警告のみ、enforceはcleanupを適用します。pruneAfter: 古いentryの期限(デフォルト30d)。maxEntries:sessions.json内の最大entry数(デフォルト500)。rotateBytes:sessions.jsonがこのサイズを超えたときにローテーションします(デフォルト10mb)。resetArchiveRetention:*.reset.<timestamp>transcript archiveの保持期間。デフォルトはpruneAfter。無効にするにはfalseを設定します。maxDiskBytes: 任意のsessions directoryディスク予算。warnmodeでは警告を記録し、enforcemodeでは最も古いartifact/sessionから削除します。highWaterBytes: 予算cleanup後の任意target。デフォルトはmaxDiskBytesの80%。
threadBindings: thread-bound session機能のグローバルデフォルト。enabled: マスターデフォルトスイッチ(provider側で上書き可能。Discordはchannels.discord.threadBindings.enabledを使用)idleHours: 非アクティブ時の自動unfocusデフォルト(時間単位。0で無効。provider側で上書き可能)maxAgeHours: ハード最大期間デフォルト(時間単位。0で無効。provider側で上書き可能)
Messages
Response prefix
channel/アカウントごとのオーバーライド:channels.<channel>.responsePrefix、channels.<channel>.accounts.<id>.responsePrefix。
解決順(最も具体的なものが勝つ): account → channel → global。"" は無効化し、cascadeを止めます。"auto" は [{identity.name}] を導出します。
Template変数:
| Variable | 説明 | 例 |
|---|---|---|
{model} | 短いmodel名 | claude-opus-4-6 |
{modelFull} | 完全なmodel識別子 | anthropic/claude-opus-4-6 |
{provider} | Provider名 | anthropic |
{thinkingLevel} | 現在のthinking level | high, low, off |
{identity.name} | Agent identity名 | ("auto" と同じ) |
{think} は {thinkingLevel} のaliasです。
Ack reaction
- デフォルトはアクティブagentの
identity.emoji、なければ"👀"。無効化するには""を設定します。 - Channelごとのオーバーライド:
channels.<channel>.ackReaction、channels.<channel>.accounts.<id>.ackReaction。 - 解決順: account → channel →
messages.ackReaction→ identity fallback。 - Scope:
group-mentions(デフォルト)、group-all、direct、all。 removeAckAfterReply: Slack、Discord、Telegramでreply後にackを削除します。messages.statusReactions.enabled: Slack、Discord、Telegramでライフサイクルstatus reactionを有効にします。 SlackとDiscordでは、未設定の場合、ack reactionが有効ならstatus reactionも有効のままです。 Telegramでは、ライフサイクルstatus reactionを有効にするには明示的にtrueを設定してください。
Inbound debounce
同じsenderからの高速なtext-only messageを1つのagent turnにまとめます。media/attachmentは即時flushされます。control commandはdebouncingをバイパスします。TTS(text-to-speech)
autoはデフォルトの自動TTS modeを制御します:off、always、inbound、またはtagged。/tts on|offはローカル設定を上書きでき、/tts statusは有効状態を表示します。summaryModelは自動summary用にagents.defaults.model.primaryを上書きします。modelOverridesはデフォルトで有効です。modelOverrides.allowProviderはデフォルトでfalse(opt-in)です。- API keyのフォールバックは
ELEVENLABS_API_KEY/XI_API_KEYとOPENAI_API_KEYです。 openai.baseUrlはOpenAI TTS endpointを上書きします。解決順はconfig、次にOPENAI_TTS_BASE_URL、最後にhttps://api.openai.com/v1です。openai.baseUrlがOpenAI以外のendpointを指す場合、OpenClawはそれをOpenAI互換TTS serverとして扱い、model/voice validationを緩和します。
Talk
Talk mode(macOS/iOS/Android)のデフォルト値です。talk.providerは、複数のTalk providerが設定されている場合、talk.providers内のキーと一致している必要があります。- レガシーなフラットTalkキー(
talk.voiceId、talk.voiceAliases、talk.modelId、talk.outputFormat、talk.apiKey)は互換性専用であり、自動的にtalk.providers.<provider>へ移行されます。 - Voice IDは
ELEVENLABS_VOICE_IDまたはSAG_VOICE_IDにフォールバックします。 providers.*.apiKeyは平文文字列またはSecretRefオブジェクトを受け付けます。ELEVENLABS_API_KEYフォールバックは、Talk API keyが設定されていない場合にのみ適用されます。providers.*.voiceAliasesにより、Talk directiveでフレンドリー名を使用できます。silenceTimeoutMsは、Talk modeがユーザーの無音後どれだけ待ってからtranscriptを送信するかを制御します。未設定時はプラットフォーム既定の待機時間が維持されます(macOSとAndroidでは700 ms、iOSでは900 ms)。
Tools
Tool profile
tools.profile は tools.allow/tools.deny より前に基本allowlistを設定します:
ローカルonboardingでは、未設定の新しいローカルconfigに対してデフォルトで tools.profile: "coding" を設定します(既存の明示profileは保持されます)。
| Profile | 含まれるもの |
|---|---|
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 | 制限なし(未設定と同じ) |
Tool group
| Group | Tools |
|---|---|
group:runtime | exec, process, code_execution(bash は exec のaliasとして受け付けられます) |
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 | すべての組み込みtool(provider pluginを除く) |
tools.allow / tools.deny
グローバルtool allow/deny policy(denyが優先)。大文字小文字を区別せず、* wildcardをサポートします。Docker sandboxがオフでも適用されます。
tools.byProvider
特定のproviderまたはmodelに対してtoolをさらに制限します。順序: base profile → provider profile → allow/deny。
tools.elevated
sandbox外のelevated execアクセスを制御します:
- agentごとのオーバーライド(
agents.list[].tools.elevated)はさらに制限することしかできません。 /elevated on|off|ask|fullは状態をsessionごとに保存します。インラインdirectiveは単一messageに適用されます。- Elevated
execはsandboxをバイパスし、設定されたescape path(デフォルトはgateway、exec targetがnodeの場合はnode)を使います。
tools.exec
tools.loopDetection
tool-loop安全性チェックは デフォルトで無効 です。有効にするには enabled: true を設定します。
設定はグローバルの tools.loopDetection で定義でき、agentごとに agents.list[].tools.loopDetection で上書きできます。
historySize: loop分析用に保持する最大tool-call history数。warningThreshold: 警告用の繰り返し無進捗pattern閾値。criticalThreshold: 重大なloopをブロックするためのより高い繰り返し閾値。globalCircuitBreakerThreshold: 任意の無進捗実行に対するハード停止閾値。detectors.genericRepeat: 同じtool/同じargs呼び出しの繰り返しに警告します。detectors.knownPollNoProgress: 既知のpoll tool(process.poll、command_statusなど)に対する無進捗に警告/ブロックします。detectors.pingPong: 交互に発生する無進捗ペアpatternに警告/ブロックします。warningThreshold >= criticalThresholdまたはcriticalThreshold >= globalCircuitBreakerThresholdの場合、validationは失敗します。
tools.web
tools.media
受信media理解(image/audio/video)を設定します:
Media model entryフィールド
Media model entryフィールド
Provider entry(
type: "provider" または省略時):provider: API provider id(openai、anthropic、google/gemini、groqなど)model: model idオーバーライドprofile/preferredProfile:auth-profiles.jsonprofile選択
type: "cli"):command: 実行するexecutableargs: template化されたargs({{MediaPath}}、{{Prompt}}、{{MaxChars}}などをサポート)
capabilities: 任意の一覧(image、audio、video)。デフォルト:openai/anthropic/minimax→ image、google→ image+audio+video、groq→ audio。prompt、maxChars、maxBytes、timeoutSeconds、language: entryごとのオーバーライド。- 失敗時は次のentryへフォールバックします。
auth-profiles.json → env vars → models.providers.*.apiKey。Async completionフィールド:asyncCompletion.directSend:trueの場合、完了したasyncmusic_generateおよびvideo_generateタスクは、まずdirect channel配信を試みます。デフォルト:false(レガシーのrequester-session wake/model-delivery path)。
tools.agentToAgent
tools.sessions
session tool(sessions_list、sessions_history、sessions_send)でターゲットにできるsessionを制御します。
デフォルト: tree(現在のsession + そこからspawnされたsession。subagentなど)。
self: 現在のsession keyのみ。tree: 現在のsession + 現在のsessionからspawnされたsession(subagent)。agent: 現在のagent idに属する任意のsession(同じagent idの下でper-sender sessionを実行している場合、他ユーザーを含むことがあります)。all: 任意のsession。cross-agent targetingには依然としてtools.agentToAgentが必要です。- Sandbox clamp: 現在のsessionがsandbox化されており、
agents.defaults.sandbox.sessionToolsVisibility="spawned"の場合、tools.sessions.visibility="all"であっても可視性はtreeに強制されます。
tools.sessions_spawn
sessions_spawn のインラインattachmentサポートを制御します。
- Attachmentは
runtime: "subagent"でのみサポートされます。ACP runtimeでは拒否されます。 - Fileは子workspaceの
.openclaw/attachments/<uuid>/に.manifest.jsonとともに実体化されます。 - Attachment内容はtranscript永続化から自動的にredactされます。
- Base64入力は、厳格なalphabet/paddingチェックとdecode前サイズガードで検証されます。
- File permissionはdirectoryに
0700、fileに0600です。 - Cleanupは
cleanuppolicyに従います:deleteは常にattachmentを削除し、keepはretainOnSessionKeep: trueの場合にのみ保持します。
tools.experimental
実験的な組み込みtoolフラグです。runtime固有の自動有効化ルールが適用されない限り、デフォルトはオフです。
planTool: 構造化されたupdate_plantoolを有効にし、単純でない複数ステップ作業の追跡に使用します。- デフォルト: OpenAI以外のproviderでは
false。OpenAIおよびOpenAI Codex実行では未設定時に自動有効化されます。自動有効化を無効にするにはfalseを設定してください。 - 有効時、system promptにも利用ガイダンスが追加され、modelがこれを実質的な作業にのみ使い、
in_progressのステップを最大1つに保つようにします。
agents.defaults.subagents
model: spawnされるsub-agent用のデフォルトmodel。省略時、sub-agentは呼び出し元のmodelを継承します。allowAgents: 要求元agentが独自のsubagents.allowAgentsを設定していない場合のsessions_spawnターゲットagent idデフォルトallowlist(["*"]= 任意。デフォルト: 同じagentのみ)。runTimeoutSeconds: tool callでrunTimeoutSecondsを省略した場合のsessions_spawnデフォルトtimeout(秒)。0はtimeoutなしを意味します。- subagentごとのtool policy:
tools.subagents.tools.allow/tools.subagents.tools.deny。
カスタムproviderとbase URL
OpenClawは組み込みmodel catalogを使用します。カスタムproviderはconfig内のmodels.providers または ~/.openclaw/agents/<agentId>/agent/models.json で追加してください。
- カスタム認証が必要な場合は
authHeader: true+headersを使用してください。 - Agent config rootは
OPENCLAW_AGENT_DIR(またはレガシー環境変数aliasのPI_CODING_AGENT_DIR)で上書きできます。 - 一致するprovider IDに対するマージ優先順位:
- 空でないagent
models.jsonのbaseUrl値が優先されます。 - 空でないagent
apiKey値は、そのproviderが現在のconfig/auth-profile contextでSecretRef管理されていない場合にのみ優先されます。 - SecretRef管理されたprovider
apiKey値は、解決済みsecretを永続化する代わりに、source marker(env refならENV_VAR_NAME、file/exec refならsecretref-managed)から更新されます。 - SecretRef管理されたprovider header値は、source marker(env refなら
secretref-env:ENV_VAR_NAME、file/exec refならsecretref-managed)から更新されます。 - agentの
apiKey/baseUrlが空または欠落している場合は、config内のmodels.providersにフォールバックします。 - 一致するmodelの
contextWindow/maxTokensには、明示config値と暗黙catalog値の高い方が使われます。 - 一致するmodelの
contextTokensは、明示的なruntime capが存在する場合はそれを保持します。ネイティブmodel metadataを変更せずに有効contextを制限したい場合に使用してください。 - configで
models.jsonを完全に書き換えたい場合はmodels.mode: "replace"を使ってください。 - Marker永続化はsource-authoritativeです: markerは解決済みruntime secret値からではなく、アクティブなsource config snapshot(解決前)から書き込まれます。
- 空でないagent
Providerフィールド詳細
models.mode: provider catalogの動作(mergeまたはreplace)。models.providers: provider idをキーとするカスタムprovider map。models.providers.*.api: request adapter(openai-completions、openai-responses、anthropic-messages、google-generative-aiなど)。models.providers.*.apiKey: provider資格情報(SecretRef/env substitution推奨)。models.providers.*.auth: 認証戦略(api-key、token、oauth、aws-sdk)。models.providers.*.injectNumCtxForOpenAICompat: Ollama +openai-completions用にoptions.num_ctxをrequestへ注入します(デフォルト:true)。models.providers.*.authHeader: 必要な場合に資格情報をAuthorizationheaderで送るよう強制します。models.providers.*.baseUrl: 上流API base URL。models.providers.*.headers: proxy/tenant routing用の追加静的header。models.providers.*.request: model-provider HTTP request用の転送オーバーライド。request.headers: 追加header(providerデフォルトとマージ)。値はSecretRefを受け付けます。request.auth: 認証戦略オーバーライド。モード:"provider-default"(provider組み込み認証を使用)、"authorization-bearer"(tokenとともに使用)、"header"(headerName、value、任意のprefixとともに使用)。request.proxy: HTTP proxyオーバーライド。モード:"env-proxy"(HTTP_PROXY/HTTPS_PROXYenv varsを使用)、"explicit-proxy"(urlとともに使用)。両モードとも任意のtlsサブオブジェクトを受け付けます。request.tls: direct connection用TLSオーバーライド。フィールド:ca、cert、key、passphrase(いずれもSecretRefを受け付けます)、serverName、insecureSkipVerify。
models.providers.*.models: 明示的なprovider model catalog entry。models.providers.*.models.*.contextWindow: ネイティブmodel context window metadata。models.providers.*.models.*.contextTokens: 任意のruntime context cap。modelのネイティブcontextWindowより小さい有効context budgetを使いたい場合に使用してください。models.providers.*.models.*.compat.supportsDeveloperRole: 任意の互換性ヒント。api: "openai-completions"かつ空でない非ネイティブbaseUrl(hostがapi.openai.comではない)の場合、OpenClawはruntime時にこれをfalseに強制します。空または省略されたbaseUrlではデフォルトのOpenAI動作が維持されます。models.providers.*.models.*.compat.requiresStringContent: string-onlyのOpenAI互換chat endpoint向けの任意互換性ヒント。trueの場合、OpenClawは純粋なtextmessages[].content配列をrequest送信前に単純文字列へ平坦化します。plugins.entries.amazon-bedrock.config.discovery: Bedrock auto-discovery設定ルート。plugins.entries.amazon-bedrock.config.discovery.enabled: 暗黙discoveryのオン/オフ。plugins.entries.amazon-bedrock.config.discovery.region: discovery用のAWS region。plugins.entries.amazon-bedrock.config.discovery.providerFilter: 対象discovery用の任意provider-id filter。plugins.entries.amazon-bedrock.config.discovery.refreshInterval: discovery refreshのpolling interval。plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: 発見されたmodel用のフォールバックcontext window。plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: 発見されたmodel用のフォールバック最大出力token数。
Provider例
Cerebras (GLM 4.6 / 4.7)
Cerebras (GLM 4.6 / 4.7)
cerebras/zai-glm-4.7、Z.AI directには zai/glm-4.7 を使用してください。OpenCode
OpenCode
OPENCODE_API_KEY(または OPENCODE_ZEN_API_KEY)を設定してください。Zen catalogには opencode/... ref、Go catalogには opencode-go/... refを使用します。ショートカット: openclaw onboard --auth-choice opencode-zen または openclaw onboard --auth-choice opencode-go。Z.AI (GLM-4.7)
Z.AI (GLM-4.7)
ZAI_API_KEY を設定してください。z.ai/* と z-ai/* は受け付けられるaliasです。ショートカット: openclaw onboard --auth-choice zai-api-key。- 一般endpoint:
https://api.z.ai/api/paas/v4 - Coding endpoint(デフォルト):
https://api.z.ai/api/coding/paas/v4 - 一般endpointを使う場合は、base URLオーバーライド付きのカスタムproviderを定義してください。
Moonshot AI (Kimi)
Moonshot AI (Kimi)
baseUrl: "https://api.moonshot.cn/v1" または openclaw onboard --auth-choice moonshot-api-key-cn を使用してください。ネイティブMoonshot endpointは、共有
openai-completions transport上でstreaming使用互換性を提示し、OpenClawは組み込みprovider id単独ではなく
そのendpoint capabilityに基づいて処理します。Kimi Coding
Kimi Coding
openclaw onboard --auth-choice kimi-code-api-key。Synthetic (Anthropic互換)
Synthetic (Anthropic互換)
/v1 を含めないでください(Anthropic clientが付加します)。ショートカット: openclaw onboard --auth-choice synthetic-api-key。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。
model catalogのデフォルトはM2.7のみです。
Anthropic互換streaming pathでは、OpenClawは明示的に thinking を設定しない限り
デフォルトでMiniMax thinkingを無効にします。/fast on または
params.fastMode: true は MiniMax-M2.7 を
MiniMax-M2.7-highspeed に書き換えます。ローカルmodel (LM Studio)
ローカルmodel (LM Studio)
Local Models を参照してください。要点: 十分なハードウェア上でLM Studio Responses API経由の大規模ローカルmodelを実行し、フォールバック用にhosted modelはマージしたままにしてください。