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

제공자 항목 (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). 각 제공자 Plugin은 자체 기본 기능 집합을 선언합니다. 예를 들어 번들 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로 강제됩니다.
• all이 아닐 때 sessions_list에는 유효 모드를 설명하는 간략한 visibility 필드와 현재 범위를 벗어난 일부 세션이 생략될 수 있다는 경고가 포함됩니다.

• 첨부 파일을 사용하려면 enabled: true가 필요합니다.
• 하위 에이전트 첨부 파일은 .manifest.json과 함께 하위 작업 공간의 .openclaw/attachments/<uuid>/에 생성됩니다.
• ACP 첨부 파일은 이미지만 지원하며 동일한 파일 수, 파일당 바이트 및 총 바이트 제한을 통과한 후 ACP 런타임에 인라인으로 전달됩니다.
• 첨부 파일 콘텐츠는 트랜스크립트 영속화에서 자동으로 마스킹됩니다.
• Base64 입력은 엄격한 알파벳/패딩 검사와 디코딩 전 크기 제한 검사를 통해 유효성이 확인됩니다.
• 하위 에이전트 첨부 파일 권한은 디렉터리의 경우 0700, 파일의 경우 0600입니다.
• 하위 에이전트 정리는 cleanup 정책을 따릅니다. delete는 항상 첨부 파일을 제거하며, keep은 retainOnSessionKeep: true인 경우에만 첨부 파일을 유지합니다.

• 사용자 지정 인증이 필요한 경우 authHeader: true + headers를 사용합니다.
• OPENCLAW_AGENT_DIR로 에이전트 구성 루트를 재정의합니다.
• 일치하는 제공자 ID의 병합 우선순위:
  • 비어 있지 않은 에이전트 models.json의 baseUrl 값이 우선합니다.
  • 비어 있지 않은 에이전트 apiKey 값은 현재 구성/인증 프로필 컨텍스트에서 해당 제공자가 SecretRef로 관리되지 않는 경우에만 우선합니다.
  • SecretRef로 관리되는 제공자의 apiKey 값은 확인된 비밀을 영구 저장하는 대신 소스 마커(환경 변수 참조의 경우 ENV_VAR_NAME, 파일/실행 참조의 경우 secretref-managed)에서 새로 고쳐집니다.
  • SecretRef로 관리되는 제공자 헤더 값은 소스 마커(환경 변수 참조의 경우 secretref-env:ENV_VAR_NAME, 파일/실행 참조의 경우 secretref-managed)에서 새로 고쳐집니다.
  • 비어 있거나 누락된 에이전트 apiKey/baseUrl은 구성의 models.providers로 대체됩니다.
  • 일치하는 모델의 contextWindow/maxTokens: 명시적 구성 값이 존재하고 유효한 경우(양의 유한수) 해당 값이 우선하며, 그렇지 않으면 암시적/생성된 카탈로그 값이 사용됩니다.
  • 일치하는 모델의 contextTokens에도 동일하게 명시적 값 우선, 없으면 암시적 값 사용 규칙이 적용됩니다. 네이티브 모델 메타데이터를 변경하지 않고 유효 컨텍스트를 제한하는 데 사용합니다.
  • 제공자 Plugin 카탈로그는 에이전트의 Plugin 상태 아래에 생성된 Plugin 소유 카탈로그 샤드로 저장됩니다.
  • 구성이 models.json을 완전히 다시 작성하고 Plugin 소유 카탈로그 샤드 병합을 건너뛰게 하려면 models.mode: "replace"를 사용합니다.
  • 마커 영구 저장은 소스를 기준으로 합니다. 마커는 확인된 런타임 비밀 값이 아니라 활성 소스 구성 스냅샷(확인 전)에서 기록됩니다.

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

• models.providers.*.api: 요청 어댑터(openai-completions, openai-responses, openai-chatgpt-responses, anthropic-messages, google-generative-ai, google-vertex, github-copilot, bedrock-converse-stream, ollama, azure-openai-responses). MLX, vLLM, SGLang 및 대부분의 OpenAI 호환 로컬 서버와 같은 자체 호스팅 /v1/chat/completions 백엔드에는 openai-completions를 사용합니다. baseUrl은 있지만 api가 없는 사용자 지정 제공자는 기본적으로 openai-completions를 사용합니다. 백엔드가 /v1/responses를 지원하는 경우에만 openai-responses를 설정합니다.
• models.providers.*.apiKey: 제공자 자격 증명(SecretRef/환경 변수 치환 권장).
• 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이면 제공자 HTTP 가져오기 보호를 통해 사설, CGNAT 또는 유사 범위로 모델 제공자 HTTP 요청을 허용합니다. 사용자 지정/로컬 제공자 기본 URL은 이미 정확히 구성된 오리진을 신뢰하지만, 메타데이터/링크 로컬 오리진은 명시적으로 허용하지 않는 한 계속 차단됩니다. 정확한 오리진 신뢰를 사용하지 않으려면 이를 false로 설정합니다. WebSocket은 헤더/TLS에 동일한 request를 사용하지만 해당 가져오기 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: 선택적 사고 페이로드 힌트. Together 스타일 reasoning.enabled에는 "together"를, 최상위 enable_thinking에는 "qwen"을, vLLM처럼 요청 수준 채팅 템플릿 키워드 인수를 지원하는 Qwen 계열 OpenAI 호환 서버의 chat_template_kwargs.enable_thinking에는 "qwen-chat-template"을 사용합니다. 구성된 vLLM Qwen 모델은 이러한 형식에 대해 이진 /think 선택지(off, on)를 제공합니다.
• models.providers.*.models.*.compat.requiresReasoningContentOnAssistantMessages: 재생 시 이전 어시스턴트 메시지에 reasoning_content를 유지해야 하는 DeepSeek 스타일 Chat Completions 백엔드를 위한 선택적 호환성 힌트. true이면 OpenClaw는 발신 어시스턴트 메시지에서 해당 필드를 보존합니다. 추론이 제거된 후 요청을 거부하는 사용자 지정 DeepSeek 호환 프록시를 연결할 때 사용합니다. 기본값은 false입니다.

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

MINIMAX_API_KEY를 설정하세요. 단축 명령: openclaw onboard --auth-choice minimax-global-api 또는 openclaw onboard --auth-choice minimax-cn-api. 모델 카탈로그의 기본값은 M3이며 M2.7 변형도 포함합니다. Anthropic 호환 스트리밍 경로에서 OpenClaw는 사용자가 thinking을 명시적으로 설정하지 않는 한 기본적으로 MiniMax M2.x의 사고 기능을 비활성화합니다. MiniMax-M3 및 M3.x는 기본적으로 공급자의 생략형/적응형 사고 경로를 유지합니다. /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를 설정하세요. 모델 참조에는 표준 zai/* 공급자 ID를 사용합니다. 단축 명령: openclaw onboard --auth-choice zai-api-key.

• 일반 엔드포인트: https://api.z.ai/api/paas/v4
• 코딩 엔드포인트: https://api.z.ai/api/coding/paas/v4
• 기본 zai-api-key 인증 선택지는 키를 검사하여 해당 키가 어느 엔드포인트에 속하는지 자동으로 감지합니다. 감지 결과가 확실하지 않으면 입력을 요청하며, 기본값은 글로벌입니다. 명시적으로 선택할 수 있는 전용 CN 및 Coding-Plan 인증 선택지도 제공됩니다.
• 일반 엔드포인트의 경우 기본 URL을 재정의한 사용자 지정 공급자를 정의하세요.