OpenClaw API Key와 모델 설정
2026 설치·구성 완전 가이드
OpenClaw 설치가 끝나도 모델이 연결되지 않으면 껍데기에 가깝습니다. API Key 오입력, 로컬 추론 서비스 미기동, 작업과 맞지 않는 기본 모델, 네트워크 불통은 모두 「OpenClaw 자체가 고장」처럼 보이게 합니다. 본문은 2026년 설치부터 첫 검증까지의 완전 가이드이며, 모델·키·첫 수용 검증 체인을 더 두껍게 다룹니다. 클라우드·로컬 선택, 키 보관, Dashboard로 실제 모델 호출을 확인하는 방법까지 정리합니다.
Key → provider → 모델명 → 네트워크 → 로그
Dashboard·프로브 진입점
클라우드 / 로컬 / 하이브리드
1설치 완료 ≠ 모델 호출 가능
OpenClaw가 실제로 쓰이려면 npm install -g openclaw 성공보다 모델 경로 연결, 키 안전 보관, 기본 모델이 작업에 맞는지가 훨씬 중요합니다. 게이트웨이가 뜨고 18789 프로브가 통해도 「껍데기만 실행 중」일 수 있습니다. 실작업에는 유효한 provider/model 참조와 인증이 필요합니다. 아래에서는 완전 설치 흐름 안에서 그 체인을 순서대로 짚습니다.
openclaw models status 또는 최소 Agent 호출로 로그에 상류 HTTP·토큰 소비가 있는지 확인하세요.
2설치 전: 모델·키 준비
시작 전에: ① 사용 중인 OpenClaw 버전이 지원하는 provider 목록(공식 문서 기준); ② 클라우드 API Key와 올바른 환경 변수명; ③ 로컬 추론 시 호환 HTTP 엔드포인트 대기·메모리 여유; ④ provider API 또는 localhost 포트 도달성. 하이브리드는 게이트웨이 호스트와 추론 호스트를 명확히 구분하세요.
3공식 설치와 onboard
Node 24와 CLI 설치 후 openclaw onboard(필요 시 --install-daemon)로 기본 모델·게이트웨이를 설정합니다. node -v와 launchd가 환경 변수를 상속하는지 확인하세요. 재시작 후 키가 사라지는 흔한 원인입니다. Node 24·18789 상세는
콜드 스타트 가이드를 참고하세요.
4클라우드 모델과 API Key
내장 provider는 대개 인증만으로 충분합니다: openclaw onboard --auth-choice openai-api-key(플래그는 마법사 기준), 또는 export OPENAI_API_KEY="sk-your-placeholder" 후 openclaw models set provider/model. 커스텀 프록시는 models.providers에 정의하고 키는 ${ENV} 플레이스홀더로 참조하세요. 확인: openclaw models status.
5로컬 모델 연결
로컬 추론은 프라이버시·비용 관리에 유리하나 속도는 하드웨어에 따릅니다. models.providers에 로컬 baseUrl(예: http://127.0.0.1:PORT/v1)와 모델 id를 지정합니다. 먼저 curl로 엔드포인트를 확인한 뒤 OpenClaw를 기동하세요.
6Dashboard로 모델 상태 수용 검증
| 확인 항목 | 클라우드 모델 | 로컬 모델 | 하이브리드 |
|---|---|---|---|
| 인증 | models status에 provider 인증됨 |
키 불필요 또는 내부 토큰만 | 양쪽 설정이 status에 표시 |
| 연결 | provider API 외부 도달 | 로컬 baseUrl을 curl |
경로별 개별 프로브(분리 순서 혼합 금지) |
| Dashboard | 18789 정상 + 세션에 상류 요청 | 로그에 로컬 HTTP 호출 | 주 모델 클라우드, 민감 처리 로컬흔함 |
| 비용·프라이버시 | 호출 과금, 데이터 외부 전송 | 전력·하드웨어, 데이터 단말 내 | 작업별 경로 정의 필요 |
Dashboard는 기본 127.0.0.1:18789에서 게이트웨이 상태·로그를 봅니다. 페이지만 열리고 응답이 없으면 표를 위에서 순서대로 확인하세요.
7첫 실전: 스모크 테스트
openclaw agent --local --session-id smoke-test --message "Reply only: model OK" --timeout 90 — JSON에 예상 provider/model이 있고 로그에 외부 요청이 보이면 모델 체인은 통과입니다. 파일 쓰기·권한 오류는 별도 레이어에서 분리하세요.
8모델 장애와 설치 장애 구분
openclaw models list로 provider/model 철자 확인. 커스텀 provider는 models.providers.*.models[].id 대조.lsof -iTCP:18789와 launchd 확인. 모델 API 문제가 아니므로 먼저 키를 교체하지 마세요.9운영·유지보수
키는 정기 로테이션, 카탈로그 변경은 models list로 추적, 과금은 대시보드로 모니터링하세요. provider 추가 후 openclaw models set으로 기본 primary 모델을 갱신하고 권한은 단계적으로 넓히세요.
- 1설치 전 키·네트워크·(선택) 로컬 엔드포인트 준비
- 2수용 4단계:
onboard→models status→ Dashboard → 최소 Agent - 3분리 순서: 키 → provider → 모델명 → 네트워크/로컬 서비스 → 로그
- 4비밀은 커밋 금지. 모델 문제와 포트/권한 문제를 혼동하지 말 것
Mac mini에서 모델 체인이 더 단순합니다
macOS에서는 게이트웨이와 로컬 추론이 한 흐름으로 이어집니다. Node 24, launchd, 환경 변수 상속이 맞춰져 재시작 후에도 키가 남기 쉽습니다. Mac mini M4 통합 메모리는 중간 규모 로컬 모델 시험에 적합하고, 대기 전력은 대략 4W로 24시간 게이트웨이에 맞습니다. Gatekeeper·FileVault는 키 노출 면을 줄입니다. onboard와 Dashboard 검증을 안정화하려면 Mac mini M4가 현실적인 출발점입니다. 지금 하드웨어를 맞춰 두면 이후 모델 업데이트·키 로테이션도 수월합니다.