구성 — 도구 및 사용자 지정 제공자

Provider 항목(type: "provider" 또는 생략):

• provider: API 제공자 ID(openai, anthropic, google/gemini, groq 등)
• model: 모델 ID 재정의
• profile / preferredProfile: auth-profiles.json 프로필 선택

CLI 항목(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: 사용 중단된 호환성 플래그입니다. 완료된 비동기 미디어 작업은 요청자 세션을 통해 중재된 상태로 유지되어 에이전트가 결과를 받고, 사용자에게 알릴 방법을 결정하며, 소스 전달에 필요할 때 메시지 도구를 사용합니다.

• self: 현재 세션 키만 해당합니다.
• tree: 현재 세션 + 현재 세션이 생성한 세션(하위 에이전트).
• agent: 현재 에이전트 ID에 속한 모든 세션(동일한 에이전트 ID 아래에서 발신자별 세션을 실행하는 경우 다른 사용자를 포함할 수 있음).
• all: 모든 세션. 에이전트 간 대상 지정에는 여전히 tools.agentToAgent가 필요합니다.
• 샌드박스 제한: 현재 세션이 샌드박스 처리되어 있고 agents.defaults.sandbox.sessionToolsVisibility="spawned"인 경우, tools.sessions.visibility="all"이어도 가시성이 tree로 강제됩니다.

• 첨부 파일은 runtime: "subagent"에서만 지원됩니다. ACP 런타임은 이를 거부합니다.
• 파일은 자식 작업 공간의 .openclaw/attachments/<uuid>/에 .manifest.json과 함께 구체화됩니다.
• 첨부 파일 콘텐츠는 transcript 지속 저장에서 자동으로 수정 처리됩니다.
• Base64 입력은 엄격한 알파벳/패딩 검사와 디코딩 전 크기 가드로 검증됩니다.
• 파일 권한은 디렉터리의 경우 0700, 파일의 경우 0600입니다.
• 정리는 cleanup 정책을 따릅니다. delete는 항상 첨부 파일을 제거하고, keep은 retainOnSessionKeep: true일 때만 첨부 파일을 유지합니다.

• 사용자 지정 인증이 필요한 경우 authHeader: true + headers를 사용합니다.
• OPENCLAW_AGENT_DIR(또는 레거시 환경 변수 별칭인 PI_CODING_AGENT_DIR)로 에이전트 구성 루트를 재정의합니다.
• 일치하는 공급자 ID의 병합 우선순위:
  • 비어 있지 않은 에이전트 models.json baseUrl 값이 우선합니다.
  • 비어 있지 않은 에이전트 apiKey 값은 해당 공급자가 현재 구성/인증 프로필 컨텍스트에서 SecretRef 관리 대상이 아닐 때만 우선합니다.
  • SecretRef 관리 공급자 apiKey 값은 확인된 비밀을 지속 저장하는 대신 소스 마커(env 참조의 경우 ENV_VAR_NAME, 파일/exec 참조의 경우 secretref-managed)에서 새로 고쳐집니다.
  • SecretRef 관리 공급자 헤더 값은 소스 마커(env 참조의 경우 secretref-env:ENV_VAR_NAME, 파일/exec 참조의 경우 secretref-managed)에서 새로 고쳐집니다.
  • 비어 있거나 누락된 에이전트 apiKey/baseUrl는 구성의 models.providers로 폴백합니다.
  • 일치하는 모델 contextWindow/maxTokens는 명시적 구성 값과 암시적 카탈로그 값 중 더 높은 값을 사용합니다.
  • 일치하는 모델 contextTokens는 명시적 런타임 한도가 있으면 이를 보존합니다. 네이티브 모델 메타데이터를 변경하지 않고 유효 컨텍스트를 제한할 때 사용합니다.
  • 구성이 models.json을 완전히 다시 쓰도록 하려면 models.mode: "replace"를 사용합니다.
  • 마커 지속 저장은 소스 권위를 따릅니다. 마커는 확인된 런타임 비밀 값이 아니라 활성 소스 구성 스냅샷(확인 전)에서 작성됩니다.

• models.mode: 공급자 카탈로그 동작(merge 또는 replace)입니다.
• models.providers: 공급자 ID를 키로 사용하는 사용자 지정 공급자 맵입니다.
  • 안전한 편집: 추가 업데이트에는 openclaw config set models.providers.<id> '<json>' --strict-json --merge 또는 openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge를 사용합니다. config set은 --replace를 전달하지 않으면 파괴적 교체를 거부합니다.

• models.providers.*.api: 요청 어댑터(openai-completions, openai-responses, anthropic-messages, google-generative-ai 등)입니다. MLX, vLLM, SGLang 및 대부분의 OpenAI 호환 로컬 서버 같은 자체 호스팅 /v1/chat/completions 백엔드에는 openai-completions를 사용합니다. baseUrl은 있지만 api가 없는 사용자 지정 공급자는 기본적으로 openai-completions를 사용합니다. 백엔드가 /v1/responses를 지원할 때만 openai-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: 업스트림 API 기본 URL입니다.
• 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이면 DNS가 비공개, CGNAT 또는 유사 범위로 확인될 때 공급자 HTTP fetch 가드를 통해 baseUrl로의 HTTPS를 허용합니다(신뢰할 수 있는 자체 호스팅 OpenAI 호환 엔드포인트에 대한 운영자 옵트인). localhost, 127.0.0.1, [::1] 같은 loopback 모델 공급자 스트림 URL은 이를 명시적으로 false로 설정하지 않는 한 자동으로 허용됩니다. LAN, tailnet 및 비공개 DNS 호스트는 여전히 옵트인이 필요합니다. WebSocket은 헤더/TLS에 동일한 request를 사용하지만 해당 fetch SSRF 게이트는 사용하지 않습니다. 기본값은 false입니다.

• models.providers.*.models: 명시적 공급자 모델 카탈로그 항목입니다.
• models.providers.*.models.*.input: 모델 입력 모달리티입니다. 텍스트 전용 모델에는 ["text"]를 사용하고, 네이티브 이미지/비전 모델에는 ["text", "image"]를 사용합니다. 이미지 첨부 파일은 선택된 모델이 이미지 지원으로 표시된 경우에만 에이전트 턴에 주입됩니다.
• models.providers.*.models.*.contextWindow: 네이티브 모델 컨텍스트 창 메타데이터입니다. 이는 해당 모델에 대해 공급자 수준 contextWindow를 재정의합니다.
• models.providers.*.models.*.contextTokens: 선택적 런타임 컨텍스트 한도입니다. 이는 공급자 수준 contextTokens를 재정의합니다. 모델의 네이티브 contextWindow보다 더 작은 유효 컨텍스트 예산을 원할 때 사용합니다. openclaw models list는 두 값이 다를 때 둘 다 표시합니다.
• models.providers.*.models.*.compat.supportsDeveloperRole: 선택적 호환성 힌트입니다. 비어 있지 않은 비네이티브 baseUrl(호스트가 api.openai.com이 아님)이 있는 api: "openai-completions"의 경우 OpenClaw는 런타임에 이를 false로 강제합니다. 비어 있거나 생략된 baseUrl은 기본 OpenAI 동작을 유지합니다.
• models.providers.*.models.*.compat.requiresStringContent: 문자열 전용 OpenAI 호환 채팅 엔드포인트를 위한 선택적 호환성 힌트입니다. true이면 OpenClaw는 요청을 보내기 전에 순수 텍스트 messages[].content 배열을 일반 문자열로 평탄화합니다.
• models.providers.*.models.*.compat.strictMessageKeys: 엄격한 OpenAI 호환 채팅 엔드포인트를 위한 선택적 호환성 힌트입니다. true이면 OpenClaw는 요청을 보내기 전에 발신 Chat Completions 메시지 객체를 role과 content만 남기도록 제거합니다.
• models.providers.*.models.*.compat.thinkingFormat: 선택적 thinking 페이로드 힌트입니다. 최상위 enable_thinking에는 "qwen"을 사용하거나, vLLM 같은 요청 수준 채팅 템플릿 kwargs를 지원하는 Qwen 계열 OpenAI 호환 서버의 chat_template_kwargs.enable_thinking에는 "qwen-chat-template"을 사용합니다.

• plugins.entries.amazon-bedrock.config.discovery: Bedrock 자동 검색 설정 루트입니다.
• plugins.entries.amazon-bedrock.config.discovery.enabled: 암시적 검색을 켜거나 끕니다.
• plugins.entries.amazon-bedrock.config.discovery.region: 검색에 사용할 AWS 리전입니다.
• plugins.entries.amazon-bedrock.config.discovery.providerFilter: 대상 검색을 위한 선택적 공급자 ID 필터입니다.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: 검색 새로 고침의 폴링 간격입니다.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: 검색된 모델의 폴백 컨텍스트 창입니다.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: 검색된 모델의 폴백 최대 출력 토큰입니다.

번들된 cerebras 제공자 Plugin은 openclaw onboard --auth-choice cerebras-api-key를 통해 이를 구성할 수 있습니다. 기본값을 재정의할 때만 명시적 제공자 구성을 사용하세요.

{  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)" },        ],      },    },  },}

Cerebras에는 cerebras/zai-glm-4.7을 사용하고, Z.AI 직접 연결에는 zai/glm-4.7을 사용하세요.

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

Anthropic 호환 기본 제공 제공자입니다. 바로 가기: openclaw onboard --auth-choice kimi-code-api-key.

로컬 모델을 참조하세요. 요약: 고성능 하드웨어에서 LM Studio Responses API를 통해 대형 로컬 모델을 실행하고, 대체용으로 호스팅 모델을 병합된 상태로 유지하세요.

{  agents: {    defaults: {      model: { primary: "minimax/MiniMax-M2.7" },      models: {        "minimax/MiniMax-M2.7": { alias: "Minimax" },      },    },  },  models: {    mode: "merge",    providers: {      minimax: {        baseUrl: "https://api.minimax.io/anthropic",        apiKey: "${MINIMAX_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "MiniMax-M2.7",            name: "MiniMax M2.7",            reasoning: true,            input: ["text"],            cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },            contextWindow: 204800,            maxTokens: 131072,          },        ],      },    },  },}

MINIMAX_API_KEY를 설정하세요. 바로 가기: openclaw onboard --auth-choice minimax-global-api 또는 openclaw onboard --auth-choice minimax-cn-api. 모델 카탈로그는 기본적으로 M2.7만 사용합니다. Anthropic 호환 스트리밍 경로에서 OpenClaw는 사용자가 thinking을 명시적으로 직접 설정하지 않는 한 기본적으로 MiniMax 사고 기능을 비활성화합니다. /fast on 또는 params.fastMode: true는 MiniMax-M2.7을 MiniMax-M2.7-highspeed로 다시 작성합니다.

{  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,          },        ],      },    },  },}

중국 엔드포인트의 경우: baseUrl: "https://api.moonshot.cn/v1" 또는 openclaw onboard --auth-choice moonshot-api-key-cn.

네이티브 Moonshot 엔드포인트는 공유 openai-completions 전송에서 스트리밍 사용량 호환성을 알리며, OpenClaw는 기본 제공 제공자 ID만이 아니라 엔드포인트 기능을 기준으로 이를 판단합니다.

{  agents: {    defaults: {      model: { primary: "opencode/claude-opus-4-6" },      models: { "opencode/claude-opus-4-6": { alias: "Opus" } },    },  },}

OPENCODE_API_KEY(또는 OPENCODE_ZEN_API_KEY)를 설정하세요. Zen 카탈로그에는 opencode/... 참조를 사용하고, Go 카탈로그에는 opencode-go/... 참조를 사용하세요. 바로 가기: openclaw onboard --auth-choice opencode-zen 또는 openclaw onboard --auth-choice opencode-go.

{  env: { SYNTHETIC_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" },      models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "MiniMax M2.5" } },    },  },  models: {    mode: "merge",    providers: {      synthetic: {        baseUrl: "https://api.synthetic.new/anthropic",        apiKey: "${SYNTHETIC_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "hf:MiniMaxAI/MiniMax-M2.5",            name: "MiniMax M2.5",            reasoning: true,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 192000,            maxTokens: 65536,          },        ],      },    },  },}

기본 URL에는 /v1을 생략해야 합니다(Anthropic 클라이언트가 이를 추가합니다). 바로 가기: openclaw onboard --auth-choice synthetic-api-key.

{  agents: {    defaults: {      model: { primary: "zai/glm-4.7" },      models: { "zai/glm-4.7": {} },    },  },}

ZAI_API_KEY를 설정하세요. z.ai/* 및 z-ai/*는 허용되는 별칭입니다. 바로 가기: openclaw onboard --auth-choice zai-api-key.

• 일반 엔드포인트: https://api.z.ai/api/paas/v4
• 코딩 엔드포인트(기본값): https://api.z.ai/api/coding/paas/v4
• 일반 엔드포인트의 경우, 기본 URL 재정의를 포함한 사용자 지정 제공자를 정의하세요.