추론 CLI

openclaw infer는 공급자 기반 추론 워크플로를 위한 표준 헤드리스 표면입니다.

이는 원시 Gateway RPC 이름이나 원시 에이전트 도구 ID가 아니라, 의도적으로 기능 패밀리를 노출합니다.

infer를 skill로 전환하기

이 내용을 에이전트에 복사하여 붙여넣으세요.

Read https://docs.openclaw.ai/cli/infer, then create a skill that routes my common workflows to `openclaw infer`.Focus on model runs, image generation, video generation, audio transcription, TTS, web search, and embeddings.

좋은 infer 기반 skill은 다음을 해야 합니다.

• 일반적인 사용자 의도를 올바른 infer 하위 명령에 매핑
• 다루는 워크플로에 대한 몇 가지 표준 infer 예시 포함
• 예시와 제안에서 openclaw infer ... 선호
• skill 본문 안에서 전체 infer 표면을 다시 문서화하지 않기

일반적인 infer 중심 skill 범위:

• openclaw infer model run
• openclaw infer image generate
• openclaw infer audio transcribe
• openclaw infer tts convert
• openclaw infer web search
• openclaw infer embedding create

infer를 사용하는 이유

openclaw infer는 OpenClaw 안에서 공급자 기반 추론 작업을 위한 일관된 CLI 하나를 제공합니다.

이점:

• 각 백엔드마다 일회성 래퍼를 연결하는 대신 OpenClaw에 이미 구성된 공급자와 모델을 사용합니다.
• 모델, 이미지, 오디오 전사, TTS, 비디오, 웹, 임베딩 워크플로를 하나의 명령 트리 아래에 유지합니다.
• 스크립트, 자동화, 에이전트 구동 워크플로를 위해 안정적인 --json 출력 형태를 사용합니다.
• 작업의 본질이 "추론 실행"인 경우 OpenClaw의 퍼스트파티 표면을 선호합니다.
• 대부분의 infer 명령에서 Gateway를 요구하지 않고 일반 로컬 경로를 사용합니다.

엔드투엔드 공급자 확인의 경우, 더 낮은 수준의 공급자 테스트가 통과한 뒤에는 openclaw infer ...를 선호하세요. 이는 공급자 요청이 이루어지기 전에 출시된 CLI, 구성 로드, 기본 에이전트 해석, 번들 Plugin 활성화, 공유 기능 런타임을 실행합니다.

명령 트리

 openclaw infer  list  inspect   model    run    list    inspect    providers    auth login    auth logout    auth status   image    generate    edit    describe    describe-many    providers   audio    transcribe    providers   tts    convert    voices    providers    status    enable    disable    set-provider   video    generate    describe    providers   web    search    fetch    providers   embedding    create    providers

일반 작업

이 표는 일반적인 추론 작업을 해당 infer 명령에 매핑합니다.

동작

• openclaw infer ...는 이러한 워크플로의 기본 CLI 표면입니다.
• 출력이 다른 명령이나 스크립트에서 소비될 경우 --json을 사용하세요.
• 특정 백엔드가 필요할 때는 --provider 또는 --model provider/model을 사용하세요.
• 실행을 원시 상태로 유지하면서 일회성 사고/추론 수준(off, minimal, low, medium, high, adaptive, xhigh, 또는 max)을 전달하려면 model run --thinking <level>을 사용하세요.
• image describe, audio transcribe, video describe의 경우 --model은 <provider/model> 형식을 사용해야 합니다.
• image describe의 경우 --file은 로컬 경로와 HTTP(S) 이미지 URL을 허용합니다. 원격 URL은 일반 미디어 가져오기 SSRF 정책을 사용합니다.
• image describe의 경우 명시적 --model은 해당 공급자/모델을 먼저 실행한 다음, 모델 호출이 실패하면 구성된 agents.defaults.imageModel.fallbacks를 시도합니다. 누락된 파일이나 지원되지 않는 URL 같은 입력 준비 오류는 폴백 시도 전에 실패합니다. 모델은 모델 카탈로그 또는 공급자 구성에서 이미지 기능이 있어야 합니다. codex/<model>은 제한된 Codex 앱 서버 이미지 이해 턴을 실행하고, openai/<model>은 API 키 또는 ChatGPT/Codex OAuth 인증을 사용해 OpenAI 공급자 경로를 사용합니다.
• 상태 비저장 실행 명령은 기본적으로 로컬을 사용합니다.
• Gateway 관리 상태 명령은 기본적으로 Gateway를 사용합니다.
• 일반 로컬 경로는 Gateway가 실행 중일 필요가 없습니다.
• 로컬 model run은 간결한 일회성 공급자 완료입니다. 구성된 에이전트 모델과 인증을 해석하지만, 채팅 에이전트 턴을 시작하거나 도구를 로드하거나 번들 MCP 서버를 열지 않습니다.
• model run --file은 이미지 파일을 허용하고, MIME 유형을 감지하며, 제공된 프롬프트와 함께 선택한 모델로 보냅니다. 여러 이미지에는 --file을 반복하세요.
• model run --file은 이미지가 아닌 입력을 거부합니다. 오디오 파일에는 infer audio transcribe를, 비디오 파일에는 infer video describe를 사용하세요.
• model run --gateway는 Gateway 라우팅, 저장된 인증, 공급자 선택, 임베디드 런타임을 실행하지만 여전히 원시 모델 프로브로 실행됩니다. 이전 세션 전사, 부트스트랩/AGENTS 컨텍스트, 컨텍스트 엔진 조립, 도구 또는 번들 MCP 서버 없이 제공된 프롬프트와 이미지 첨부를 보냅니다.
• model run --gateway --model <provider/model>은 요청이 Gateway에 일회성 공급자/모델 재정의를 실행하도록 요구하므로 신뢰할 수 있는 운영자 Gateway 자격 증명이 필요합니다.
• 로컬 model run --thinking은 간결한 공급자 완료 경로를 사용합니다. adaptive 및 max 같은 공급자별 수준은 가장 가까운 이식 가능한 단순 완료 수준으로 매핑됩니다.

모델

공급자 기반 텍스트 추론과 모델/공급자 검사를 위해 model을 사용하세요.

openclaw infer model run --prompt "Reply with exactly: smoke-ok" --jsonopenclaw infer model run --prompt "Summarize this changelog entry" --model openai/gpt-5.4 --jsonopenclaw infer model run --prompt "Describe this image in one sentence" --file ./photo.jpg --model google/gemini-2.5-flash --jsonopenclaw infer model run --prompt "Use more reasoning here" --thinking high --jsonopenclaw infer model providers --jsonopenclaw infer model inspect --name gpt-5.5 --json

Gateway를 시작하거나 전체 에이전트 도구 표면을 로드하지 않고 특정 공급자를 스모크 테스트하려면 전체 <provider/model> 참조를 사용하세요.

openclaw infer model run --local --model anthropic/claude-sonnet-4-6 --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model cerebras/zai-glm-4.7 --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model google/gemini-2.5-flash --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model groq/llama-3.1-8b-instant --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model mistral/mistral-medium-3-5 --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model mistral/mistral-small-latest --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model openai/gpt-5.5 --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model ollama/qwen2.5vl:7b --prompt "Describe this image." --file ./photo.jpg --json

참고:

• 로컬 model run은 공급자/모델/인증 상태를 확인하는 가장 좁은 CLI 스모크입니다. Codex가 아닌 공급자의 경우 선택한 모델에 제공된 프롬프트만 보내기 때문입니다.
• 로컬 model run --model <provider/model>은 해당 공급자가 구성에 기록되기 전에 models list --all의 정확한 번들 정적 카탈로그 행을 사용할 수 있습니다. 공급자 인증은 여전히 필요하며, 자격 증명이 없으면 Unknown model이 아니라 인증 오류로 실패합니다.
• Mistral Medium 3.5 추론 프로브의 경우 temperature를 설정하지 않고 기본값으로 두세요. Mistral은 reasoning_effort="high"와 temperature: 0의 조합을 거부합니다. 기본 temperature로 mistral/mistral-medium-3-5를 사용하거나 0.7 같은 0이 아닌 reasoning-mode 값을 사용하세요.
• Codex Responses 로컬 프로브는 좁은 예외입니다. OpenClaw는 전체 에이전트 컨텍스트, 도구, 메모리 또는 세션 전사를 추가하지 않고, 전송 계층이 필수 instructions 필드를 채울 수 있도록 최소한의 시스템 지시를 추가합니다.
• 로컬 model run --file은 그 간결한 경로를 유지하며 이미지 콘텐츠를 단일 사용자 메시지에 직접 첨부합니다. PNG, JPEG, WebP 같은 일반 이미지 파일은 MIME 유형이 image/*로 감지되면 작동합니다. 지원되지 않거나 인식되지 않는 파일은 공급자가 호출되기 전에 실패합니다.
• 선택한 멀티모달 텍스트 모델을 직접 테스트하려면 model run --file이 가장 적합합니다. OpenClaw의 이미지 이해 공급자 선택과 기본 이미지 모델 라우팅을 원할 때는 infer image describe를 사용하세요.
• 선택한 모델은 이미지 입력을 지원해야 합니다. 텍스트 전용 모델은 공급자 계층에서 요청을 거부할 수 있습니다.
• model run --prompt에는 공백이 아닌 텍스트가 포함되어야 합니다. 빈 프롬프트는 로컬 공급자 또는 Gateway가 호출되기 전에 거부됩니다.
• 로컬 model run은 공급자가 텍스트 출력을 반환하지 않으면 0이 아닌 코드로 종료하므로, 도달할 수 없는 로컬 공급자와 빈 완료가 성공한 프로브처럼 보이지 않습니다.
• 모델 입력을 원시 상태로 유지하면서 Gateway 라우팅, 에이전트 런타임 설정 또는 Gateway 관리 공급자 상태를 테스트해야 할 때는 model run --gateway를 사용하세요. 전체 에이전트 컨텍스트, 도구, 메모리, 세션 전사를 원할 때는 openclaw agent 또는 채팅 표면을 사용하세요.
• model auth login, model auth logout, model auth status는 저장된 공급자 인증 상태를 관리합니다.

이미지

생성, 편집, 설명에는 image를 사용하세요.

openclaw infer image generate --prompt "friendly lobster illustration" --jsonopenclaw infer image generate --prompt "cinematic product photo of headphones" --jsonopenclaw infer image generate --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "simple red circle sticker on a transparent background" --jsonopenclaw infer image generate --model openai/gpt-image-2 --quality low --openai-moderation low --prompt "low-cost draft poster" --jsonopenclaw infer image generate --prompt "slow image backend" --timeout-ms 180000 --jsonopenclaw infer image edit --file ./logo.png --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "keep the logo, remove the background" --jsonopenclaw infer image edit --file ./poster.png --prompt "make this a vertical story ad" --size 2160x3840 --aspect-ratio 9:16 --resolution 4K --jsonopenclaw infer image describe --file ./photo.jpg --jsonopenclaw infer image describe --file https://example.com/photo.png --jsonopenclaw infer image describe --file ./receipt.jpg --prompt "Extract the merchant, date, and total" --jsonopenclaw infer image describe-many --file ./before.png --file ./after.png --prompt "Compare the screenshots and list visible UI changes" --jsonopenclaw infer image describe --file ./ui-screenshot.png --model openai/gpt-5.4-mini --jsonopenclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --prompt "Describe the image in one sentence" --timeout-ms 300000 --json

참고:

• 기존 입력 파일에서 시작할 때는 image edit을 사용하세요.

• 참조 이미지 편집에서 지오메트리 힌트를 지원하는 제공자/모델에는 image edit과 함께 --size, --aspect-ratio 또는 --resolution을 사용하세요.

• 투명 배경 OpenAI PNG 출력에는 --model openai/gpt-image-1.5와 함께 --output-format png --background transparent를 사용하세요. --openai-background는 OpenAI 전용 별칭으로 계속 사용할 수 있습니다. 배경 지원을 선언하지 않는 제공자는 해당 힌트를 무시된 재정의로 보고합니다.

• OpenAI를 포함해 이미지 품질 힌트를 지원하는 제공자에는 --quality low|medium|high|auto를 사용하세요. OpenAI는 제공자별 검토 힌트로 --openai-moderation low|auto도 허용합니다.

• 어떤 번들 이미지 제공자가 검색 가능하고, 구성되어 있으며, 선택되었는지, 그리고 각 제공자가 어떤 생성/편집 기능을 노출하는지 확인하려면 image providers --json을 사용하세요.

• 이미지 생성 변경 사항에 대한 가장 좁은 실시간 CLI 스모크 테스트로 image generate --model <provider/model> --json을 사용하세요. 예:

  openclaw infer image providers --jsonopenclaw infer image generate \  --model google/gemini-3.1-flash-image-preview \  --prompt "Minimal flat test image: one blue square on a white background, no text." \  --output ./openclaw-infer-image-smoke.png \  --json

  JSON 응답은 ok, provider, model, attempts, 기록된 출력 경로를 보고합니다. --output이 설정된 경우 최종 확장자는 제공자가 반환한 MIME 유형을 따를 수 있습니다.

• image describe와 image describe-many에서는 OCR, 비교, UI 검사 또는 간결한 캡션 작성 같은 작업별 지시를 비전 모델에 제공하려면 --prompt를 사용하세요.

• 느린 로컬 비전 모델이나 콜드 Ollama 시작에는 --timeout-ms를 사용하세요.

• image describe에서 --model은 이미지 기능이 있는 <provider/model>이어야 합니다. 설정하면 OpenClaw는 먼저 해당 명시적 모델을 시도한 다음 모델 호출이 실패할 경우 구성된 이미지 모델 폴백을 시도합니다.

• 로컬 Ollama 비전 모델의 경우 먼저 모델을 가져오고 OLLAMA_API_KEY를 임의의 플레이스홀더 값(예: ollama-local)으로 설정하세요. Ollama를 참조하세요.

오디오

파일 전사에는 audio를 사용하세요.

openclaw infer audio transcribe --file ./memo.m4a --jsonopenclaw infer audio transcribe --file ./team-sync.m4a --language en --prompt "Focus on names and action items" --jsonopenclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --json

참고:

• audio transcribe는 파일 전사용이며 실시간 세션 관리용이 아닙니다.
• --model은 <provider/model>이어야 합니다.

TTS

음성 합성과 TTS 제공자 상태에는 tts를 사용하세요.

openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --jsonopenclaw infer tts convert --text "Your build is complete" --output ./build-complete.mp3 --jsonopenclaw infer tts providers --jsonopenclaw infer tts status --json

참고:

• tts status는 Gateway가 관리하는 TTS 상태를 반영하므로 기본값이 Gateway입니다.
• TTS 동작을 검사하고 구성하려면 tts providers, tts voices, tts set-provider를 사용하세요.

비디오

생성과 설명에는 video를 사용하세요.

openclaw infer video generate --prompt "cinematic sunset over the ocean" --jsonopenclaw infer video generate --prompt "slow drone shot over a forest lake" --resolution 768P --duration 6 --jsonopenclaw infer video describe --file ./clip.mp4 --jsonopenclaw infer video describe --file ./clip.mp4 --model openai/gpt-5.4-mini --json

참고:

• video generate는 --size, --aspect-ratio, --resolution, --duration, --audio, --watermark, --timeout-ms를 허용하며 이를 비디오 생성 런타임에 전달합니다.
• video describe에서 --model은 <provider/model>이어야 합니다.

웹

검색 및 가져오기 워크플로에는 web을 사용하세요.

openclaw infer web search --query "OpenClaw docs" --jsonopenclaw infer web search --query "OpenClaw infer web providers" --jsonopenclaw infer web fetch --url https://docs.openclaw.ai/cli/infer --jsonopenclaw infer web providers --json

참고:

• 사용 가능하고, 구성되어 있으며, 선택된 제공자를 검사하려면 web providers를 사용하세요.

임베딩

벡터 생성과 임베딩 제공자 검사에는 embedding을 사용하세요.

openclaw infer embedding create --text "friendly lobster" --jsonopenclaw infer embedding create --text "customer support ticket: delayed shipment" --model openai/text-embedding-3-large --jsonopenclaw infer embedding providers --json

JSON 출력

Infer 명령은 공유 엔벌로프 아래에서 JSON 출력을 정규화합니다.

{  "ok": true,  "capability": "image.generate",  "transport": "local",  "provider": "openai",  "model": "gpt-image-2",  "attempts": [],  "outputs": []}

최상위 필드는 안정적입니다.

• ok
• capability
• transport
• provider
• model
• attempts
• outputs
• error

생성된 미디어 명령의 경우 outputs에는 OpenClaw가 기록한 파일이 포함됩니다. 자동화에서는 사람이 읽을 수 있는 stdout을 파싱하지 말고 해당 배열의 path, mimeType, size 및 미디어별 차원을 사용하세요.

일반적인 함정

# Badopenclaw infer media image generate --prompt "friendly lobster" # Goodopenclaw infer image generate --prompt "friendly lobster"

# Badopenclaw infer audio transcribe --file ./memo.m4a --model whisper-1 --json # Goodopenclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --json

참고

• openclaw capability ...는 openclaw infer ...의 별칭입니다.

관련 항목

• CLI 참조
• 모델