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

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

• provider: API provider ID(openai, anthropic, google/gemini, groq 등)
• model: 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 항목은 agent가 명시적 image 도구를 호출할 때도 적용됩니다.
• 실패하면 다음 항목으로 폴백합니다.

Provider 인증은 표준 순서를 따릅니다: auth-profiles.json → 환경 변수 → models.providers.*.apiKey.

비동기 완료 필드:

• asyncCompletion.directSend: 더 이상 사용되지 않는 호환성 플래그입니다. 완료된 비동기 미디어 작업은 requester-session을 통해 중재된 상태로 유지되므로 agent가 결과를 받고, 사용자에게 알릴 방법을 결정하며, 원본 전달에 필요할 때 메시지 도구를 사용합니다.

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

• 첨부 파일은 runtime: "subagent"에서만 지원됩니다. ACP 런타임은 이를 거부합니다.
• 파일은 하위 작업 공간의 .openclaw/attachments/<uuid>/에 .manifest.json과 함께 실체화됩니다.
• 첨부 파일 내용은 트랜스크립트 지속 저장에서 자동으로 편집됩니다.
• 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 ref의 경우 ENV_VAR_NAME, file/exec ref의 경우 secretref-managed)에서 새로 고쳐집니다.
  • SecretRef로 관리되는 제공자 헤더 값은 소스 마커(env ref의 경우 secretref-env:ENV_VAR_NAME, file/exec ref의 경우 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이면 제공자 HTTP fetch 보호 장치를 통해 DNS가 비공개, CGNAT 또는 유사 범위로 확인되는 경우에도 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 배열을 일반 문자열로 평탄화합니다.

• 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-code" },
      models: { "kimi/kimi-code": { alias: "Kimi Code" } },
    },
  },
}

Anthropic 호환 내장 provider입니다. 단축 명령: 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 호환 스트리밍 경로에서는 직접 thinking을 설정하지 않는 한 OpenClaw가 기본적으로 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,
          },
        ],
      },
    },
  },
}

중국 endpoint의 경우: baseUrl: "https://api.moonshot.cn/v1" 또는 openclaw onboard --auth-choice moonshot-api-key-cn.

네이티브 Moonshot endpoint는 공유 openai-completions 전송에서 스트리밍 사용량 호환성을 알리며, OpenClaw는 내장 provider id만이 아니라 endpoint 기능을 기준으로 이를 판단합니다.

{
  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/... refs를, Go 카탈로그에는 opencode-go/... refs를 사용하세요. 단축 명령: 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.

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