Configuration — tools and custom providers

기준일: 2026-07-26
공식 기준: Configuration — tools and custom providers

Configuration — tools and custom providers 문서는 OpenClaw 공식 문서(gateway/config-tools)를 한국어로 정리한 가이드입니다. Tools config (policy, experimental toggles, provider-backed tools) and custom provider/base-URL setup 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Tools config (policy, experimental toggles, provider-backed tools) and custom provider/base-URL setup

한국어 가이드 범위: gateway/config-tools 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• 도구
• Tool profiles
• Tool groups
• MCP and plugin tools inside sandbox tool policy
• tools.codeMode
• tools.allow / tools.deny
• tools.byProvider
• tools.toolsBySender
• tools.elevated
• tools.exec
• tools.loopDetection
• tools.web
• tools.media
• tools.agentToAgent
• tools.sessions
• tools.sessions_spawn
• tools.experimental
• agents.defaults.subagents
• Custom providers and base URLs
• Provider field details
• Provider examples
• 관련 문서

상세 내용

본문

tools.* config keys and custom provider / base-URL setup. For agents, channels, and other top-level config keys, see Configuration reference.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

도구

이 섹션의 세부 항목은 공식 문서 도구를 참고하세요.

Tool profiles

tools.profile sets a base allowlist before tools.allow/tools.deny:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Profile	Includes
minimal	session_status only
coding	group:fs, group:runtime, group:web, group:sessions, group:memory, cron, get_goal, create_goal, update_goal, update_plan, ask_user, skill_workshop, image, image_generate, music_generate, video_generate
messaging	group:messaging, sessions, sessions_list, sessions_history, sessions_search, conversations_list, conversations_send, conversations_turn, sessions_send, sessions_spawn, sessions_yield, subagents, session_status, ask_user
full	No restriction (same as unset)

Tool groups

spawn_task lets a coding agent propose confirmed follow-up work without starting it. The Control UI shows the title and summary as an actionable chip; a Gateway-backed TUI shows an equivalent interactive prompt. Accepting either creates a fresh managed-worktree session and sends the full prompt there while the current turn continues. dismiss_task withdraws a still-pending suggestion by the ephemeral task_id returned from spawn_task.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Group	Tools
group:runtime	exec, process, code_execution (bash is accepted as an alias for exec)
group:fs	read, write, edit, apply_patch
group:sessions	sessions, sessions_list, sessions_history, sessions_search, conversations_list, conversations_send, conversations_turn, sessions_send, sessions_spawn, sessions_yield, subagents, session_status, spawn_task, dismiss_task
group:memory	memory_search, memory_get
group:web	web_search, x_search, web_fetch
group:ui	browser, screen, terminal, canvas, show_widget
group:automation	heartbeat_respond, cron, gateway
group:messaging	message
group:nodes	nodes, computer
group:agents	agents_list, get_goal, create_goal, update_goal, update_plan, ask_user, skill_workshop
group:media	image, image_generate, music_generate, video_generate, tts
group:openclaw	All built-in tools above except read/write/edit/apply_patch/exec/process/canvas (excludes plugin tools)
group:plugins	Tools owned by loaded plugins, including configured MCP servers exposed through bundle-mcp

MCP and plugin tools inside sandbox tool policy

Configured MCP servers are exposed as plugin-owned tools under the bundle-mcp plugin id. Normal tool profiles can allow them, but tools.sandbox.tools is an additional gate for sandboxed sessions. If sandbox mode is "all" or "non-main", include one of these entries in the sandbox tool allowlist when MCP/plugin tools should be visible:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• bundle-mcp for OpenClaw-managed MCP servers from mcp.servers
• the plugin id for a specific native plugin
• group:plugins for all loaded plugin-owned tools
• exact MCP server tool names or server globs such as outlook__send_mail or outlook__* when you only want one server

{
  agents: { defaults: { sandbox: { mode: "all" } } },
  mcp: {
    servers: {
      outlook: { command: "node", args: ["./outlook-mcp.js"] },
    },
  },
  tools: {
    sandbox: {
      tools: {
        alsoAllow: ["web_search", "web_fetch", "memory_search", "memory_get", "bundle-mcp"],
      },
    },
  },
}

tools.codeMode

tools.codeMode enables the generic OpenClaw code-mode surface. When enabled for a run with tools, normal OpenClaw tools move behind the in-sandbox tools.* catalog bridge, and MCP tools are available through the generated MCP namespace. The model normally sees exec and wait; tools such as computer whose structured results cannot cross the JSON-only bridge stay direct.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

{
  tools: {
    codeMode: {
      enabled: true,
    },
  },
}

{
  tools: { codeMode: true },
}

tools.allow / tools.deny

Global tool allow/deny policy (deny wins). Case-insensitive, supports * wildcards. Applied even when Docker sandbox is off.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

{
  tools: { deny: ["browser", "canvas"] },
}

{
  tools: { deny: ["write", "edit", "apply_patch"] },
}

tools.byProvider

Further restrict tools for specific providers or models. Order: base profile → provider profile → allow/deny.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
      "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

tools.toolsBySender

Restricts tools for the current turn's originating requester. This is defense-in-depth on top of channel access control; sender values must come from the channel adapter, not message text. It does not authenticate other content in the model prompt; see Requester-scoped controls and prompt context.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

{
  tools: {
    toolsBySender: {
      "channel:discord:1234567890123": { alsoAllow: ["group:fs"] },
      "id:guest-user-id": { deny: ["group:runtime", "group:fs"] },
      "*": { deny: ["exec", "process", "write", "edit", "apply_patch"] },
    },
  },
}

tools.elevated

Controls elevated exec access outside the sandbox:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Per-agent override (agents.entries.*.tools.elevated) can only further restrict.
• /elevated on|off|ask|full stores state per session; inline directives apply to single message.
• Elevated exec bypasses sandboxing and uses the configured escape path (gateway by default, or node when the exec target is node).

{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        discord: ["1234567890123", "987654321098765432"],
      },
    },
  },
}

tools.exec

Values shown are defaults except applyPatch.allowModels (empty/unset by default, meaning any compatible model may use apply_patch). approvalRunningNoticeMs emits a running notice when approval-backed exec runs long; 0 disables it.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

{
  tools: {
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
      approvalRunningNoticeMs: 10000,
      notifyOnExit: true,
      notifyOnExitEmptySuccess: false,
      commandHighlighting: false,
      applyPatch: {
        enabled: true,
        allowModels: ["gpt-5.6-sol"],
      },
    },
  },
}

tools.loopDetection

Tool-loop safety checks are disabled by default. Set enabled: true to activate detection. Settings can be defined globally in tools.loopDetection and overridden per-agent at agents.entries.*.tools.loopDetection.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

{
  tools: {
    loopDetection: {
      enabled: true,
    },
  },
}

tools.web

Values shown are defaults except provider and userAgent. maxResponseBytes clamps to 32000–10000000; maxChars clamps to maxCharsCap (raise maxCharsCap to allow larger responses).

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "brave_api_key", // or BRAVE_API_KEY env (Brave provider)
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
      fetch: {
        enabled: true,
        provider: "firecrawl", // optional; omit for auto-detect
        maxChars: 20000,
        maxCharsCap: 20000,
        maxResponseBytes: 750000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        readability: true,
        userAgent: "custom-ua",
      },
    },
  },
}

tools.media

Configures inbound media understanding (image/audio/video):

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• provider: API provider id (openai, anthropic, google/gemini, groq, etc.)
• model: model id override
• profile / preferredProfile: auth-profiles.json profile selection
• command: executable to run
• args: templated args (supports {{AttachmentPath}}, {{AttachmentUrl}}, {{AttachmentContentType}}, {{AttachmentDir}}, {{AttachmentIndex}}, {{Prompt}}, {{MaxChars}}, etc.; openclaw doctor --fix migrates deprecated {input} placeholders to {{AttachmentPath}}). The older {{MediaPath}}, {{MediaUrl}}, {{MediaType}}, and {{MediaDir}} aliases remain available during their compatibility window but are deprecated.
• capabilities: list containing one or more of image, audio, and video.
• prompt, maxChars, maxBytes, timeoutSeconds, language: per-entry overrides.
• Matching image model timeoutSeconds entries also apply when the agent calls the explicit image tool. For image understanding, this timeout applies to the request itself and is not reduced by earlier preparation work.
• Failures fall back to the next entry.

{
  tools: {
    media: {
      concurrency: 2,
      models: [
        { provider: "openai", model: "gpt-4o-mini-transcribe", capabilities: ["audio"] },
        {
          type: "cli",
          command: "whisper",
          args: ["--model", "base", "{{AttachmentPath}}"],
          capabilities: ["audio"],
        },
        { provider: "ollama", model: "gemma4:26b", capabilities: ["image"] },
        { provider: "google", model: "gemini-3-flash-preview", capabilities: ["video"] },
      ],
      audio: { enabled: true, preferredModel: "openai/gpt-4o-mini-transcribe" },
      image: { enabled: true, preferredModel: "ollama/gemma4:26b" },
      video: { enabled: true },
    },
  },
}

tools.agentToAgent

{
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },
}

tools.sessions

Controls which sessions can be targeted by the session tools (sessions_list, sessions_history, sessions_send).

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• self: only the current session key.
• tree: current session + sessions spawned by the current session (subagents). For read operations, it also includes same-agent group sessions that the current session watches through ambient group awareness.
• agent: any session belonging to the current agent id (can include other users if you run per-sender sessions under the same agent id).
• all: any session. Cross-agent targeting still requires tools.agentToAgent.
• Sandbox clamp: when the current session is sandboxed and agents.defaults.sandbox.sessionToolsVisibility="spawned" (the default), visibility is forced to tree even if tools.sessions.visibility="all".
• When not all, sessions_list includes a compact visibility field

{
  tools: {
    sessions: {
      // "self" | "tree" | "agent" | "all"
      visibility: "tree",
    },
  },
}

tools.sessions_spawn

Controls inline attachment support for sessions_spawn.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Attachments require enabled: true.
• Subagent attachments are materialized into the child workspace at .openclaw/attachments/<uuid>/ with a .manifest.json.
• ACP attachments are image-only and forwarded inline to the ACP runtime after the same file count, per-file byte, and total byte limits pass.
• Attachment content is automatically redacted from transcript persistence.
• Base64 inputs are validated with strict alphabet/padding checks and a pre-decode size guard.
• Subagent attachment file permissions are 0700 for directories and 0600 for files.
• Subagent cleanup follows the cleanup policy: delete always removes attachments; keep retains them only when retainOnSessionKeep: true.

{
  tools: {
    sessions_spawn: {
      attachments: {
        enabled: false, // opt-in: set true to allow inline file attachments
        maxTotalBytes: 5242880, // 5 MB total across all files
        maxFiles: 50,
        maxFileBytes: 1048576, // 1 MB per file
        retainOnSessionKeep: false, // keep attachments when cleanup="keep"
      },
    },
  },
}

tools.experimental

Experimental built-in tool flags. Default off unless a strict-agentic GPT-5 auto-enable rule applies.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• planTool: enables the structured update_plan tool for non-trivial multi-step work tracking.
• 기본값: false unless agents.defaults.embeddedAgent.executionContract (or a per-agent override) is set to "strict-agentic" for an openai provider run against a GPT-5-family model id (this covers OpenAI Codex CLI runs too, since Codex auth/model routing lives under the openai provider). Set true to force the tool on outside that scope, or false to keep it off even for strict-agentic GPT-5 runs.
• When enabled, the system prompt also adds usage guidance so the model only uses it for substantial work and keeps at most one step in_progress.

{
  tools: {
    experimental: {
      planTool: true, // enable experimental update_plan
    },
  },
}

agents.defaults.subagents

주요 항목:

• model: default model for spawned sub-agents. If omitted, sub-agents inherit the caller's model.
• allowAgents: default allowlist of configured target agent ids for sessions_spawn when the requester agent does not set its own subagents.allowAgents (["*"] = any configured target; default: same agent only). Stale entries whose agent config was deleted are rejected by sessions_spawn and omitted from agents_list; run openclaw doctor --fix to clean them up.
• maxConcurrent: max concurrent sub-agent runs. 기본값: 8.
• runTimeoutSeconds: timeout (seconds) for sessions_spawn when the caller does not pass its own override. 기본값: 0 (no timeout); the 900 shown above is a common opt-in value, not the built-in default.
• announceTimeoutMs: per-call timeout (milliseconds) for gateway agent announce delivery attempts. 기본값: 120000. Transient retries can make the total announce wait longer than one configured timeout.
• archiveAfterMinutes: minutes after a sub-agent session completes before it is auto-archived. 기본값: 60; 0 disables auto-archive.
• Per-subagent tool policy: tools.subagents.tools.allow / tools.subagents.tools.deny.

{
  agents: {
    defaults: {
      subagents: {
        allowAgents: ["research"],
        model: "minimax/MiniMax-M2.7",
        maxConcurrent: 8,
        runTimeoutSeconds: 900,
        announceTimeoutMs: 120000,
        archiveAfterMinutes: 60,
      },
    },
  },
}

Custom providers and base URLs

Provider plugins publish their own model catalog rows. Add custom providers via models.providers in config or ~/.openclaw/agents//agent/models.json.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Use authHeader: true + headers for custom auth needs.
• Override agent config root with OPENCLAW_AGENT_DIR.
• Merge precedence for matching provider IDs:
• Non-empty agent models.json baseUrl values win.
• Non-empty agent apiKey values win only when that provider is not SecretRef-managed in current config/auth-profile context.
• SecretRef-managed provider apiKey values are refreshed from source markers (ENV_VAR_NAME for env refs, secretref-managed for file/exec refs) instead of persisting resolved secrets.
• SecretRef-managed provider header values are refreshed from source markers (secretref-env:ENV_VAR_NAME for env refs, secretref-managed for file/exec refs).
• Empty or missing agent apiKey/baseUrl fall back to models.providers in config.
• Matching model contextWindow/maxTokens: the explicit config value wins when present and valid (a positive finite number); otherwise the implicit/generated catalog value is used.
• Matching model contextTokens follows the same explicit-wins-else-implicit rule; use it to limit effective context without changing native model metadata.
• Provider-plugin catalogs are stored as generated plugin-owned catalog shards under the agent's plugin state.
• Use models.mode: "replace" when you want config to fully rewrite models.json and skip merging in plugin-owned catalog shards.
• Marker persistence is source-authoritative: markers are written from the active source config snapshot (pre-resolution), not from resolved runtime secret values.

{
  models: {
    mode: "merge", // merge (default) | replace
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai | etc.
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            contextTokens: 96000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}

Provider field details

models.providers.*.request: transport overrides for model-provider HTTP requests.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• models.mode: provider catalog behavior (merge or replace).
• models.providers: custom provider map keyed by provider id.
• Safe edits: use openclaw config set models.providers.<id> '<json>' --strict-json --merge or openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge for additive updates. config set refuses destructive replacements unless you pass --replace.
• models.providers.*.api: request adapter (openai-completions, openai-responses, openai-chatgpt-responses, anthropic-messages, google-generative-ai, google-vertex, github-copilot, bedrock-converse-stream, ollama, azure-openai-responses). For self-hosted /v1/chat/completions backends such as MLX, vLLM, SGLang, and most OpenAI-compatible local servers, use openai-completions. A custom provider with baseUrl but no api defaults to openai-completions; set openai-responses only when the backend supports /v1/responses.
• models.providers.*.apiKey: provider credential (prefer SecretRef/env substitution).
• models.providers.*.auth: auth strategy (api-key, token, oauth, aws-sdk).
• models.providers.*.contextWindow: default native context window for models under this provider when the model entry does not set contextWindow.
• models.providers.*.contextTokens: default effective runtime context cap for models under this provider when the model entry does not set contextTokens.
• models.providers.*.maxTokens: default output-token cap for models under this provider when the model entry does not set maxTokens.
• models.providers.*.timeoutSeconds: optional per-provider model HTTP request timeout in seconds, including connect, headers, body, and total request abort handling.
• models.providers.*.injectNumCtxForOpenAICompat: for Ollama + openai-completions, inject options.num_ctx into requests (default: true).
• models.providers.*.authHeader: force credential transport in the Authorization header when required.
• models.providers.*.baseUrl: upstream API base URL.
• models.providers.*.headers: extra static headers for proxy/tenant routing.
• request.headers: extra headers (merged with provider defaults). Values accept SecretRef.
• request.auth: auth strategy override. Modes: "provider-default" (use provider's built-in auth), "authorization-bearer" (with token), "header" (with headerName, value, optional prefix).
• request.proxy: HTTP proxy override. Modes: "env-proxy" (use HTTP_PROXY/HTTPS_PROXY env vars), "explicit-proxy" (with url). Both modes accept an optional tls sub-object.
• request.tls: TLS override for direct connections. Fields: ca, cert, key, passphrase (all accept SecretRef), serverName, insecureSkipVerify.
• request.allowPrivateNetwork: when true, allow model-provider HTTP requests to private, CGNAT, or similar ranges through the provider HTTP fetch guard. Custom/local provider base URLs already trust the exact configured origin, except metadata/link-local origins, which remain blocked without explicit opt-in. Set this to false to opt out of exact-origin trust. WebSocket uses the same request for headers/TLS but not that fetch SSRF gate. Default false.
• models.providers.*.models: explicit provider model catalog entries.
• models.providers.*.models.*.input: model input modalities. Use ["text"] for text-only models and ["text", "image"] for native image/vision models. Image attachments are only injected into agent turns when the selected model is marked image-capable.
• models.providers.*.models.*.contextWindow: native model context window metadata. This overrides provider-level contextWindow for that model.
• models.providers.*.models.*.contextTokens: optional runtime context cap. This overrides provider-level contextTokens; use it when you want a smaller effective context budget than the model's native contextWindow; openclaw models list shows both values when they differ.
• plugins.entries.amazon-bedrock.config.discovery: Bedrock auto-discovery settings root.
• plugins.entries.amazon-bedrock.config.discovery.enabled: turn implicit discovery on/off.

Provider examples

The official external cerebras provider plugin can configure this via openclaw onboard --auth-choice cerebras-api-key. Use explicit provider config only when overriding defaults.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• General endpoint: https://api.z.ai/api/paas/v4
• Coding endpoint: https://api.z.ai/api/coding/paas/v4
• The default zai-api-key auth choice probes your key and auto-detects which endpoint it belongs to (falling back to a prompt, defaulting to Global, if detection is inconclusive). Dedicated CN and Coding-Plan auth choices are also available for explicit selection.
• For the general endpoint, define a custom provider with the base URL override.

{
      env: { CEREBRAS_API_KEY: "sk-..." },
      agents: {
        defaults: {
          model: {
            primary: "cerebras/zai-glm-4.7",
            fallbacks: ["cerebras/gpt-oss-120b"],
          },
          models: {
            "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },
            "cerebras/gpt-oss-120b": { alias: "GPT OSS 120B (Cerebras)" },
          },
        },
      },
      models: {
        mode: "merge",
        providers: {
          cerebras: {
            baseUrl: "https://api.cerebras.ai/v1",
            apiKey: "${CEREBRAS_API_KEY}",
            api: "openai-completions",
            models: [
              { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },
              { id: "gpt-oss-120b", name: "GPT OSS 120B (Cerebras)" },
            ],
          },
        },
      },
    }

{
      env: { KIMI_API_KEY: "sk-..." },
      agents: {
        defaults: {
          model: { primary: "kimi/kimi-for-coding" },
          models: { "kimi/kimi-for-coding": { alias: "Kimi Code" } },
        },
      },
    }

{
      agents: {
        defaults: {
          model: { primary: "minimax/MiniMax-M3" },
          models: {
            "minimax/MiniMax-M3": { alias: "Minimax" },
          },
        },
      },
      models: {
        mode: "merge",
        providers: {
          minimax: {
            baseUrl: "https://api.minimax.io/anthropic",
            apiKey: "${MINIMAX_API_KEY}",
            api: "anthropic-messages",
            models: [
              {
                id: "MiniMax-M3",
                name: "MiniMax M3",
                reasoning: true,
                input: ["text", "image"],
                cost: { input: 0.6, output: 2.4, cacheRead: 0.12, cacheWrite: 0 },
                contextWindow: 1000000,
                maxTokens: 131072,
              },
            ],
          },
        },
      },
    }

{
      env: { MOONSHOT_API_KEY: "sk-..." },
      agents: {
        defaults: {
          model: { primary: "moonshot/kimi-k2.6" },
          models: { "moonshot/kimi-k2.6": { alias: "Kimi K2.6" } },
        },
      },
      models: {
        mode: "merge",
        providers: {
          moonshot: {
            baseUrl: "https://api.moonshot.ai/v1",
            apiKey: "${MOONSHOT_API_KEY}",
            api: "openai-completions",
            models: [
              {
                id: "kimi-k2.6",
                name: "Kimi K2.6",
                reasoning: false,
                input: ["text", "image"],
                cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
                contextWindow: 262144,
                maxTokens: 262144,
              },
            ],
          },
        },
      },
    }

관련 문서

주요 항목:

• Configuration — agents
• Configuration — channels
• Configuration reference — other top-level keys
• Tools and plugins

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/config-tools
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

{
  agents: { defaults: { sandbox: { mode: "all" } } },
  mcp: {
    servers: {
      outlook: { command: "node", args: ["./outlook-mcp.js"] },
    },
  },
  tools: {
    sandbox: {
      tools: {
        alsoAllow: ["web_search", "web_fetch", "memory_search", "memory_get", "bundle-mcp"],
      },
    },
  },
}

{
  tools: {
    codeMode: {
      enabled: true,
    },
  },
}

{
  tools: { codeMode: true },
}

{
  tools: { deny: ["browser", "canvas"] },
}

{
  tools: { deny: ["write", "edit", "apply_patch"] },
}

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
      "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

관련 링크

• 공식 원문: gateway/config-tools
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.