tools.* 구성 키와 사용자 지정 provider / base-URL 설정입니다. agents, channels 및 기타 최상위 구성 키는 구성 참조를 참조하세요.
도구
도구 프로필
tools.profile은 tools.allow/tools.deny보다 먼저 기본 허용 목록을 설정합니다.
로컬 온보딩은 설정되지 않은 새 로컬 구성을 기본적으로
tools.profile: "coding"으로 설정합니다(기존의 명시적 프로필은 보존됨).| 프로필 | 포함 항목 |
|---|---|
minimal | session_status만 |
coding | group:fs, group:runtime, group:web, group:sessions, group:memory, cron, image, image_generate, skill_workshop, video_generate |
messaging | group:messaging, sessions_list, sessions_history, sessions_send, session_status |
full | 제한 없음(설정되지 않은 경우와 동일) |
도구 그룹
| 그룹 | 도구 |
|---|---|
group:runtime | exec, process, code_execution(bash는 exec의 별칭으로 허용됨) |
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 | heartbeat_respond, cron, gateway |
group:messaging | message |
group:nodes | nodes |
group:agents | agents_list, update_plan |
group:media | image, image_generate, music_generate, video_generate, tts |
group:openclaw | 모든 기본 제공 도구(provider plugins 제외) |
group:plugins | bundle-mcp를 통해 노출된 구성된 MCP 서버를 포함하여, 로드된 plugins가 소유한 도구 |
샌드박스 도구 정책 내 MCP 및 plugin 도구
구성된 MCP 서버는bundle-mcp plugin id 아래에서 plugin 소유 도구로 노출됩니다. 일반 도구 프로필은 이를 허용할 수 있지만, tools.sandbox.tools는 샌드박스 세션을 위한 추가 게이트입니다. 샌드박스 모드가 "all" 또는 "non-main"인 경우 MCP/plugin 도구가 표시되어야 한다면 샌드박스 도구 허용 목록에 다음 항목 중 하나를 포함하세요.
mcp.servers의 OpenClaw 관리 MCP 서버에는bundle-mcp- 특정 네이티브 plugin에는 해당 plugin id
- 로드된 모든 plugin 소유 도구에는
group:plugins - 하나의 서버만 원하는 경우
outlook__send_mail또는outlook__*같은 정확한 MCP 서버 도구 이름 또는 서버 glob
mcp.servers 키가 아니라 provider 안전 MCP 서버 접두사를 사용합니다. [A-Za-z0-9_-]가 아닌 문자는 -가 되고, 문자로 시작하지 않는 이름에는 mcp- 접두사가 붙으며, 길거나 중복된 접두사는 잘리거나 접미사가 붙을 수 있습니다. 예를 들어 mcp.servers["Outlook Graph"]는 outlook-graph__* 같은 glob을 사용합니다.
openclaw doctor를 사용해 mcp.servers의 OpenClaw 관리 서버에서 이 형태를 포착하세요. 번들 plugin 매니페스트 또는 Claude .mcp.json에서 로드된 MCP 서버도 동일한 샌드박스 게이트를 사용하지만, 이 진단은 아직 해당 소스를 열거하지 않습니다. 샌드박스 턴에서 해당 도구가 사라지면 동일한 허용 목록 항목을 사용하세요.
tools.codeMode
tools.codeMode는 일반 OpenClaw 코드 모드 표면을 활성화합니다. 도구가 있는 실행에서 활성화되면 모델에는 exec와 wait만 표시됩니다. 일반 OpenClaw 도구는 샌드박스 내부 tools.* 카탈로그 브리지 뒤로 이동하며, MCP 도구는 생성된 MCP 네임스페이스를 통해 사용할 수 있습니다.
MCP.<server>.<tool>()을 호출하기 전에 API.list("mcp") 및 API.read("mcp/<server>.d.ts")를 호출하여 TypeScript 스타일 시그니처를 검사할 수 있습니다. 런타임 계약, 제한, 디버깅 단계는 코드 모드를 참조하세요.
tools.allow / tools.deny
전역 도구 허용/거부 정책입니다(거부가 우선). 대소문자를 구분하지 않으며 * 와일드카드를 지원합니다. Docker 샌드박스가 꺼져 있어도 적용됩니다.
write와 apply_patch는 별도의 도구 id입니다. allow: ["write"]는 호환 모델에서 apply_patch도 활성화하지만, deny: ["write"]는 apply_patch를 거부하지 않습니다. 모든 파일 변경을 차단하려면 group:fs를 거부하거나 각 변경 도구를 명시적으로 나열하세요.
tools.byProvider
특정 provider 또는 모델에 대해 도구를 추가로 제한합니다. 순서: 기본 프로필 → provider 프로필 → 허용/거부.
tools.toolsBySender
특정 요청자 신원에 대해 도구를 제한합니다. 이는 채널 접근 제어 위의 심층 방어입니다. sender 값은 메시지 텍스트가 아니라 채널 어댑터에서 와야 합니다.
channel:<channelId>:<senderId>, id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> 또는 "*". 채널 id는 표준 OpenClaw id입니다. teams 같은 별칭은 msteams로 정규화됩니다. 레거시 무접두사 키는 id:로만 허용됩니다. 매칭 순서는 channel+id, id, e164, username, name, 그다음 와일드카드입니다.
에이전트별 agents.list[].tools.toolsBySender는 일치할 때 전역 sender 매치를 재정의하며, 빈 {} 정책이어도 마찬가지입니다.
tools.elevated
샌드박스 외부의 elevated exec 접근을 제어합니다.
- 에이전트별 재정의(
agents.list[].tools.elevated)는 더 제한적으로만 설정할 수 있습니다. /elevated on|off|ask|full은 세션별로 상태를 저장하며, 인라인 지시문은 단일 메시지에 적용됩니다.- Elevated
exec는 샌드박싱을 우회하고 구성된 탈출 경로(기본값은gateway, exec 대상이node일 때는node)를 사용합니다.
tools.exec
tools.loopDetection
도구 루프 안전 검사는 기본적으로 비활성화되어 있습니다. 감지를 활성화하려면 enabled: true를 설정하세요. 설정은 전역적으로 tools.loopDetection에 정의할 수 있으며, 에이전트별로 agents.list[].tools.loopDetection에서 재정의할 수 있습니다.
루프 분석을 위해 보존되는 최대 도구 호출 기록입니다.
경고를 위한 반복 무진행 패턴 임계값입니다.
치명적 루프를 차단하기 위한 더 높은 반복 임계값입니다.
모든 무진행 실행에 대한 강제 중지 임계값입니다.
동일 도구/동일 인수 호출이 반복될 때 경고합니다.
알려진 폴링 도구(
process.poll, command_status 등)에 대해 경고/차단합니다.교대로 나타나는 무진행 쌍 패턴에 대해 경고/차단합니다.
tools.web
tools.media
인바운드 미디어 이해(이미지/오디오/비디오)를 구성합니다:
미디어 모델 항목 필드
미디어 모델 항목 필드
프로바이더 항목(
type: "provider" 또는 생략):provider: API 프로바이더 ID(openai,anthropic,google/gemini,groq등)model: 모델 ID 재정의profile/preferredProfile:auth-profiles.json프로필 선택
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: 사용 중단된 호환성 플래그입니다. 완료된 비동기 미디어 작업은 에이전트가 결과를 받고, 사용자에게 알릴 방법을 결정하며, 소스 전달에 필요할 때 메시지 도구를 사용하도록 요청자 세션 매개 상태로 유지됩니다.
tools.agentToAgent
tools.sessions
세션 도구(sessions_list, sessions_history, sessions_send)가 대상으로 지정할 수 있는 세션을 제어합니다.
기본값: tree(현재 세션 + 하위 에이전트처럼 현재 세션에서 생성된 세션).
가시성 범위
가시성 범위
self: 현재 세션 키만.tree: 현재 세션 + 현재 세션에서 생성된 세션(하위 에이전트).agent: 현재 에이전트 ID에 속한 모든 세션(같은 에이전트 ID 아래에서 발신자별 세션을 실행하는 경우 다른 사용자를 포함할 수 있음).all: 모든 세션. 에이전트 간 대상 지정에는 여전히tools.agentToAgent가 필요합니다.- 샌드박스 클램프: 현재 세션이 샌드박스 처리되어 있고
agents.defaults.sandbox.sessionToolsVisibility="spawned"이면tools.sessions.visibility="all"이더라도 가시성이tree로 강제됩니다. all이 아닌 경우sessions_list는 유효 모드를 설명하고 현재 범위 밖의 일부 세션이 생략될 수 있다는 경고를 포함하는 간결한visibility필드를 포함합니다.
tools.sessions_spawn
sessions_spawn의 인라인 첨부 파일 지원을 제어합니다.
첨부 파일 참고 사항
첨부 파일 참고 사항
- 첨부 파일에는
enabled: true가 필요합니다. - 하위 에이전트 첨부 파일은 하위 작업 공간의
.openclaw/attachments/<uuid>/에.manifest.json과 함께 구체화됩니다. - ACP 첨부 파일은 이미지만 가능하며, 동일한 파일 수, 파일당 바이트, 총 바이트 제한을 통과한 후 ACP 런타임으로 인라인 전달됩니다.
- 첨부 파일 콘텐츠는 트랜스크립트 영속화에서 자동으로 마스킹됩니다.
- Base64 입력은 엄격한 알파벳/패딩 검사와 디코딩 전 크기 가드로 검증됩니다.
- 하위 에이전트 첨부 파일 권한은 디렉터리의 경우
0700, 파일의 경우0600입니다. - 하위 에이전트 정리는
cleanup정책을 따릅니다.delete는 항상 첨부 파일을 제거하고,keep은retainOnSessionKeep: true인 경우에만 첨부 파일을 유지합니다.
tools.experimental
실험적 기본 제공 도구 플래그입니다. 엄격한 에이전트형 GPT-5 자동 활성화 규칙이 적용되지 않는 한 기본적으로 꺼져 있습니다.
planTool: 사소하지 않은 다단계 작업 추적을 위해 구조화된update_plan도구를 활성화합니다.- 기본값: OpenAI 또는 OpenAI Codex GPT-5 계열 실행에서
agents.defaults.embeddedAgent.executionContract(또는 에이전트별 재정의)가"strict-agentic"으로 설정된 경우가 아니면false입니다. 해당 범위 밖에서 도구를 강제로 켜려면true를 설정하고, 엄격한 에이전트형 GPT-5 실행에서도 꺼진 상태로 유지하려면false를 설정합니다. - 활성화되면 시스템 프롬프트도 사용 지침을 추가하여 모델이 실질적인 작업에만 사용하고
in_progress단계는 최대 하나만 유지하도록 합니다.
agents.defaults.subagents
model: 생성된 하위 에이전트의 기본 모델입니다. 생략하면 하위 에이전트는 호출자의 모델을 상속합니다.allowAgents: 요청자 에이전트가 자체subagents.allowAgents를 설정하지 않은 경우sessions_spawn에 대해 구성된 대상 에이전트 ID의 기본 허용 목록입니다(["*"]= 구성된 모든 대상, 기본값: 같은 에이전트만). 에이전트 구성이 삭제된 오래된 항목은sessions_spawn에서 거부되고agents_list에서 생략됩니다. 정리하려면openclaw doctor --fix를 실행하세요.runTimeoutSeconds:sessions_spawn의 기본 제한 시간(초)입니다.0은 제한 시간이 없음을 의미합니다.announceTimeoutMs: Gatewayagent알림 전달 시도에 대한 호출별 제한 시간(밀리초)입니다. 기본값:120000. 일시적 재시도로 인해 총 알림 대기 시간이 구성된 제한 시간 하나보다 길어질 수 있습니다.- 하위 에이전트별 도구 정책:
tools.subagents.tools.allow/tools.subagents.tools.deny.
사용자 지정 프로바이더 및 기본 URL
프로바이더 Plugin은 자체 모델 카탈로그 행을 게시합니다. 구성 또는~/.openclaw/agents/<agentId>/agent/models.json의 models.providers를 통해 사용자 지정 프로바이더를 추가하세요.
사용자 지정/로컬 프로바이더 baseUrl 구성은 모델 HTTP 요청에 대한 좁은 네트워크 신뢰 결정이기도 합니다. OpenClaw는 별도 구성 옵션을 추가하거나 다른 비공개 출처를 신뢰하지 않고, 보호된 fetch 경로를 통해 정확히 해당 scheme://host:port 출처를 허용합니다.
인증 및 병합 우선순위
인증 및 병합 우선순위
- 사용자 지정 인증 요구 사항에는
authHeader: true+headers를 사용하세요. OPENCLAW_AGENT_DIR로 에이전트 구성 루트를 재정의하세요.- 일치하는 프로바이더 ID의 병합 우선순위:
- 비어 있지 않은 에이전트
models.jsonbaseUrl값이 우선합니다. - 비어 있지 않은 에이전트
apiKey값은 해당 프로바이더가 현재 구성/auth-profile 컨텍스트에서 SecretRef 관리 대상이 아닐 때만 우선합니다. - SecretRef 관리 프로바이더
apiKey값은 해석된 비밀을 영속화하는 대신 소스 마커(환경 변수 참조의 경우ENV_VAR_NAME, 파일/exec 참조의 경우secretref-managed)에서 새로 고쳐집니다. - SecretRef 관리 프로바이더 헤더 값은 소스 마커(환경 변수 참조의 경우
secretref-env:ENV_VAR_NAME, 파일/exec 참조의 경우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를 사용하세요.config set은--replace를 전달하지 않는 한 파괴적 대체를 거부합니다.
- 안전한 편집: 추가 업데이트에는
모델 카탈로그 항목
모델 카탈로그 항목
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처럼 요청 수준 chat-template kwargs를 지원하는 Qwen 계열 OpenAI 호환 서버의chat_template_kwargs.enable_thinking에는"qwen-chat-template"을 사용하세요. 구성된 vLLM Qwen 모델은 이러한 형식에 대해 이진/think선택지(off,on)를 노출합니다.models.providers.*.models.*.compat.requiresReasoningContentOnAssistantMessages: 이전 assistant 메시지가 재생 시reasoning_content를 유지해야 하는 DeepSeek 스타일 Chat Completions 백엔드를 위한 선택적 호환성 힌트입니다.true이면 OpenClaw는 나가는 assistant 메시지에서 해당 필드를 보존합니다. 제거된 reasoning 때문에 요청을 거부하는 사용자 지정 DeepSeek 호환 프록시를 연결할 때 사용하세요. 기본값은false입니다.
Amazon Bedrock 검색
Amazon Bedrock 검색
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: 검색된 모델을 위한 대체 최대 출력 토큰입니다.
--custom-image-input을, 텍스트 전용 메타데이터를 강제하려면 --custom-text-input을 전달하세요.
제공자 예시
Cerebras (GLM 4.7 / GPT OSS)
Cerebras (GLM 4.7 / GPT OSS)
공식 외부 Cerebras에는
cerebras 제공자 Plugin은 openclaw onboard --auth-choice cerebras-api-key를 통해 이를 구성할 수 있습니다. 기본값을 재정의할 때만 명시적 제공자 구성을 사용하세요.cerebras/zai-glm-4.7을 사용하고, Z.AI 직접 연결에는 zai/glm-4.7을 사용하세요.Kimi Coding
Kimi Coding
openclaw onboard --auth-choice kimi-code-api-key.로컬 모델(LM Studio)
로컬 모델(LM Studio)
로컬 모델을 참조하세요. 요약: 충분한 하드웨어에서 LM Studio Responses API를 통해 대형 로컬 모델을 실행하고, 대체용으로 호스팅 모델은 병합된 상태로 유지하세요.
MiniMax M3 (직접)
MiniMax M3 (직접)
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 thinking을 비활성화합니다. MiniMax-M3(및 M3.x)는 기본적으로 제공자의 생략/적응형 thinking 경로를 유지합니다. /fast on 또는 params.fastMode: true는 MiniMax-M2.7을 MiniMax-M2.7-highspeed로 다시 씁니다.Moonshot AI (Kimi)
Moonshot AI (Kimi)
baseUrl: "https://api.moonshot.cn/v1" 또는 openclaw onboard --auth-choice moonshot-api-key-cn.네이티브 Moonshot 엔드포인트는 공유 openai-completions 전송에서 스트리밍 사용량 호환성을 알리며, OpenClaw는 내장 제공자 ID만이 아니라 엔드포인트 기능을 기준으로 이를 판단합니다.OpenCode
OpenCode
OPENCODE_API_KEY(또는 OPENCODE_ZEN_API_KEY)를 설정하세요. Zen 카탈로그에는 opencode/... 참조를, Go 카탈로그에는 opencode-go/... 참조를 사용하세요. 바로 가기: openclaw onboard --auth-choice opencode-zen 또는 openclaw onboard --auth-choice opencode-go.Synthetic (Anthropic 호환)
Synthetic (Anthropic 호환)
/v1을 포함하지 않아야 합니다(Anthropic 클라이언트가 이를 추가함). 바로 가기: openclaw onboard --auth-choice synthetic-api-key.Z.AI (GLM-4.7)
Z.AI (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 - 일반 엔드포인트의 경우 기본 URL 재정의를 포함한 사용자 지정 제공자를 정의하세요.
관련
- 구성 — 에이전트
- 구성 — 채널
- 구성 참조 — 기타 최상위 키
- 도구 및 plugins