OpenClaw 설치 및 OmniProxy 구성

OpenClaw는 자신의 컴퓨터에 설치하는 AI 어시스턴트입니다. 별도의 채팅 창을 계속 열어 둘 필요 없이 Telegram, Discord, WhatsApp 또는 Lark에서 바로 대화할 수 있습니다. 대화와 기록은 이 컴퓨터에 남으며, 로컬에서 후속 작업도 이어서 수행할 수 있습니다.

설치 전 준비

OpenClaw에는 Node 24.16 이상이 필요하며, Node 26.1 이상도 사용할 수 있습니다. Node 26 사용을 권장합니다. Node는 OpenClaw 실행에 필요한 기본 환경입니다.

macOS, Linux, Windows에 모두 설치할 수 있습니다. 컴퓨터에 적합한 Node가 없으면 설치 스크립트가 직접 준비합니다. macOS에서는 Node 26을, Linux에서는 Node 24 LTS를 준비합니다. 소스에서 OpenClaw를 빌드할 때만 pnpm이 필요합니다.

컴퓨터에 이전 버전의 Node가 이미 설치되어 있어도 바로 제거할 필요는 없습니다. 2026-10-09 테스트 당시 이 컴퓨터의 시스템 Node는 요구 버전인 24.16보다 낮은 24.2.0이었지만, 비대화형 설치 스크립트가 Node 24.21.0을 직접 준비했습니다.

창이 필요한 경우

데스크톱 도우미

Windows에서는 Hub 설치 패키지
macOS에서는 GitHub의 DMG
처음 실행할 때 로컬 Gateway 설치 가능

공식 권장

설치 스크립트

macOS Linux WSL2
Windows에서는 PowerShell 사용
--no-onboard 추가 가능

Node가 이미 있음

패키지 관리자

npm pnpm 또는 bun
그다음 onboard 실행
Node 버전은 설치 페이지 참조

창이 필요하면 데스크톱 컴패니언을 다운로드하세요. 터미널에서만 사용하려면 공식 설치 스크립트를 실행하세요.

설치 및 최초 실행

창이 있는 데스크톱 컴패니언을 설치하거나 터미널에서 바로 설치할 수 있습니다. Gateway는 메시지를 받고, 모델을 호출하고, 결과를 다시 전달하는 로컬 서비스입니다. 데스크톱 컴패니언을 처음 열 때 함께 준비할 수 있습니다.

창이 필요한 경우

Windows: OpenClawCompanion-Setup-x64.exe 또는 OpenClawCompanion-Setup-arm64.exe를 다운로드하여 실행합니다. 설치 패키지는 서명되어 있으며 설정, 트레이 상태, 채팅 및 node 모드를 포함합니다.
macOS: OpenClaw의 GitHub releases에서 OpenClaw의 .dmg를 다운로드합니다. dmg를 우선 사용하며 .zip도 사용할 수 있습니다. 설치한 후 OpenClaw.app을 엽니다. 해당 버전에 macOS 파일이 없다면 macOS 앱 페이지의 안내를 따릅니다.

처음 열 때 OpenClaw가 이 컴퓨터에 Gateway를 준비하도록 하거나, 기존 원격 Gateway에 연결할 수 있습니다.

터미널로 설치

macOS, Linux 및 WSL2에서는 다음을 사용합니다.

curl -fsSL https://openclaw.ai/install.sh | bash

Windows PowerShell에서는 다음을 사용합니다.

iwr -useb https://openclaw.ai/install.ps1 | iex

스크립트는 현재 시스템을 감지하고, 필요하면 Node를 설치한 다음 OpenClaw를 설치하고 초기 설정을 시작합니다. 안내에 따라 최초 설정을 완료할 수 있습니다.

당장은 초기 설정을 시작하지 않으려면 macOS, Linux 및 WSL2에서 다음 명령을 사용합니다.

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

Windows에서는 공식 -NoOnboard 옵션을 사용합니다.

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

Node를 직접 관리하고 있다면 npm, pnpm 또는 bun을 사용할 수도 있습니다. npm 12 및 npm 11.16 이상에서는 다음을 실행합니다.

npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

npm 11.15 이하에서는 --allow-scripts=openclaw를 제거해야 합니다. pnpm을 사용할 때는 --allow-build=openclaw를 추가해야 합니다. 구체적인 차이는 설치 페이지를 기준으로 확인하세요.

설치가 완료되면 다음 세 명령을 순서대로 실행합니다.

openclaw --version
openclaw doctor
openclaw gateway status

openclaw --version은 버전을 확인하고, openclaw doctor는 일반적인 환경 문제를 점검하며, openclaw gateway status는 Gateway가 실행 중인지 확인합니다. 세 명령 모두 정상적으로 출력되어야 기본 설치가 완료된 것입니다.

터미널에서 openclaw를 찾을 수 없다고 표시되면 일반적으로 npm의 전역 bin 디렉터리가 PATH에 포함되지 않은 것입니다. PATH는 터미널이 프로그램을 찾는 위치 목록입니다. node -v, npm prefix -g, echo "$PATH"를 비교해 확인하고 해당 bin 디렉터리를 PATH에 추가한 다음 터미널을 다시 여세요.

~/.openclaw에 이미 사용 중인 구성이 있으면 기본 설치 스크립트는 이 디렉터리를 사용합니다. 기존 구성을 변경하지 않고 별도로 설치하려면 비대화형 스크립트를 실행하면서 새 디렉터리를 지정합니다.

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix "$HOME/openclaw-omniproxy" --no-onboard

--no-onboard는 이 스크립트의 기본 동작입니다. 2026-10-09에 이 명령으로 OpenClaw 2026.9.9를 설치했습니다. 설치가 완료되면 해당 디렉터리의 bin 안에 있는 openclaw를 실행해야 합니다.

OmniProxy에서 연결 매개변수 가져오기

먼저 OmniProxy가 실행 중인지 확인한 다음 모델 목록을 열고 다음 세 항목을 준비합니다.

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: OmniProxy의 현재 모델 목록에서 전체 ID를 복사

baseUrl은 OpenClaw가 모델 요청을 보내는 주소이며 /v1로 끝나야 합니다. OmniProxy에 연결할 때 api에는 openai-completions를 사용합니다. 해당 모델이 실제로 /v1/responses를 통해 작동할 때만 openai-responses로 변경하세요.

Model ID는 목록에 표시된 모델의 전체 식별자입니다. 목록에 나온 그대로 복사하고, 슬래시가 있다면 슬래시도 유지하세요. 다음 두 이름은 2026-10-09 공급자 문서와 대조하기 위한 예시일 뿐입니다. 목록에 없다면 사용하지 마세요: claude-sonnet-5-5, gpt-6-luna.

게이트웨이가 키를 검사하지 않더라도 apiKey에는 값을 입력해야 합니다. 이 컴퓨터에서만 사용하는 임의의 자리표시자 문자열을 사용할 수 있습니다. 실제 키는 저장소에 커밋하지 마세요.

도구 구성 입력

Provider는 OpenClaw가 모델 서비스를 찾는 데 사용하는 연결 설정 모음으로 이해할 수 있습니다. 여기서는 Provider 이름을 omniproxy로 지정합니다.

터미널에서 다음 명령을 실행하되 주소, 키, 두 모델 ID를 자신의 값으로 바꾸세요.

openclaw config set models.providers.omniproxy '{"baseUrl":"https://your-omniproxy-origin.example/v1","apiKey":"<YOUR_OMNIPROXY_API_KEY>","api":"openai-completions","models":[{"id":"claude-sonnet-5-5","name":"Claude Sonnet 5.5"},{"id":"gpt-6-luna","name":"GPT-6 Luna"}]}' --strict-json --merge

이 명령은 Provider와 모델 목록을 구성에 기록합니다. 명령이 성공하면 Gateway를 다시 시작할 필요가 없습니다.

그다음 기본 모델을 지정합니다. 모델 참조는 omniproxy/와 모델 ID로 구성되며, ID에 원래 포함된 슬래시는 모두 유지합니다. 모델 목록의 ID가 아래의 짧은 이름보다 길다면 목록에 있는 전체 내용을 사용하세요.

openclaw config set agents.defaults.model.primary '"omniproxy/claude-sonnet-5-5"' --strict-json

reasoning, input, cost, contextWindow, maxTokens는 생략할 수 있습니다. 입력하지 않으면 텍스트 모델이 기본 방식으로 처리됩니다.

같은 설정을 구성 파일에 직접 기록할 수도 있습니다. 기본 구성의 Provider는 models.providers에 있습니다. 각 agent에는 별도의 models.json이 있을 수도 있습니다. agent는 실제로 작업을 받고 모델을 호출하는 어시스턴트 인스턴스입니다. 파일 위치는 ~/.openclaw/agents/ 아래에 있는 해당 agent 디렉터리의 agent/models.json입니다.

이 models.json에 비어 있지 않은 baseUrl이 설정되어 있으면 기본 구성의 주소를 덮어씁니다.

설치 확인

명령 세 개

openclaw --version
openclaw doctor
gateway status

설정

models.providers

baseUrl은 /v1로 끝나야 함
api에는 completions 사용
모델에는 최소한 id 입력

선택

provider/모델

primary에 이 참조 사용
키에는 환경 변수를 우선 사용
목록은 게이트웨이를 기준으로 함

먼저 명령을 찾을 수 있는지 확인한 다음 주소와 모델을 입력하세요. 모델 참조에는 Provider 이름이 포함되어야 합니다.

실제 작업 검증

일반 프로젝트 디렉터리로 이동해 매우 짧은 메시지를 보냅니다. 명령의 모델 참조를 자신의 전체 Model ID로 바꾸세요.

openclaw agent --local --model omniproxy/claude-sonnet-5-5 --timeout 300 --message "한 단어로 답하세요."

--local은 이번 agent 작업을 로컬에서 실행한다는 의미이고, --model은 이번에 사용할 모델을 지정하며, --timeout 300은 최대 300초 동안 기다린다는 의미입니다.

터미널에 실제 모델 응답이 표시되어야 합니다. 2026-10-09에 OpenClaw 2026.9.9에서 이 명령을 사용해 응답을 받았습니다. 첫 호출에는 1~2분이 걸릴 수 있습니다.

원문 오류 Request timed out before a response was generated가 표시되면 먼저 --timeout 값을 늘린 다음 다시 전송하세요. 이는 대개 대기 시간이 부족하다는 의미이며 주소가 반드시 잘못되었다는 뜻은 아닙니다.

짧은 응답이 성공하면 지정한 로컬 파일을 읽도록 요청하세요. 그런 다음 OmniProxy의 호출 기록을 열어 기록의 출처와 모델 ID를 확인합니다. 버전 번호나 doctor 출력만으로는 모델 연결 구성이 완료되었다고 볼 수 없습니다.

설치

명령이 응답함

버전 번호가 출력됨
doctor에서 차단 문제가 없음
Gateway 상태를 확인할 수 있음

작업

간단한 작업 하나를 수행함

예: 로컬 파일 하나 읽기
응답이 오류가 아님
모델 참조가 올바름

기록

게이트웨이에서 확인 가능

소스가 OpenClaw임
모델 ID가 일치함
키가 저장소에 포함되지 않음

버전 명령이 출력된 후에도 실제 응답을 한 번 받아야 합니다.

자주 발생하는 오류

openclaw를 찾을 수 없음: npm 전역 bin을 PATH에 추가한 다음 터미널을 다시 여세요. 지정한 디렉터리에 설치했다면 해당 디렉터리의 bin에 있는 프로그램을 실행하세요.
node -v가 24.16보다 낮음: 이전 버전을 먼저 제거할 필요는 없습니다. 설치 스크립트가 준비한 Node를 확인하거나 설치 페이지에 따라 24.16+ 또는 26.1+를 사용하세요. Node 26을 권장합니다.
모델이 표시되지 않음: 모델은 models.providers의 models 배열에 있어야 하며, 최소한 동일한 id가 있어야 합니다. agents.defaults.models만 작성해도 새 모델이 별도로 등록되지는 않습니다.
400을 반환하고 developer 역할을 언급함: 주소의 호스트가 api.openai.com이 아니라면 기본값을 유지하고 supportsDeveloperRole을 true로 설정하지 마세요. true로 설정해도 덮어씌워집니다.
너무 빨리 시간 초과됨: 먼저 주소를 변경하지 말고 --timeout을 300초 이상으로 늘리세요.
gpt-6-luna를 선택했지만 도구 호출이 실패함: 이 모델은 Chat Completions를 지원합니다. Chat Completions에서 함수 호출은 reasoning_effort가 none일 때만 지원됩니다. 목록의 ID가 이와 다르면 목록을 기준으로 사용하세요.
주소에 연결할 수 없음: OmniProxy가 실행 중인지, baseUrl이 /v1로 끝나는지, 구성에 기록한 주소에 접근할 수 있는지 확인하세요. 다른 사설 네트워크 주소는 별도로 접근을 허용해야 합니다.
구성 후에도 다른 주소로 요청이 전송됨: 해당 agent의 models.json에 다른 baseUrl이 설정되어 있는지 확인하세요.

공식 참고 자료

설치 절차는 OpenClaw install을 참고하세요. 사용자 지정 Provider 설정 방법은 Custom providers와 구성 필드를 참고하세요. 예시에 사용된 모델 ID는 Claude 모델 개요와 GPT-6 Luna에서 대조할 수 있습니다.

모든 플레이스홀더를 고유한 OmniProxy 구성의 값으로 바꾸세요. 실제 키를 게시하지 마세요.

저장된 결과나 HTTP 200 만으로는 전체 에이전트 호환성이 입증되지 않습니다. OmniProxy 호출 기록에서 소스와 모델을 확인하세요.

공식 소스 · OpenClaw ↗