openclaw로 로컬 코딩 에이전트 붙이기, 최소 설정은

openclaw 로컬 에이전트를 최소로 붙이려면, 공식 문서 기준으로 (1) OpenClaw 설정·워크스페이스를 ~/.openclaw 아래에 두고 Gateway를 띄운 뒤, (2) 로컬 모델이 필요하면 Ollama를 네이티브 엔드포인트로 연결하고, (3) 번들 coding-agent 스킬을 opt-in으로 켠 다음 claude / codex / opencode 중 하나를 설치·인증합니다.

이 글은 제품 UI·버전 번호를 가정하지 않은 최소 경로만 적습니다. 가격·후기는 다루지 않으며, 세부 플래그는 공식 docs.openclaw.ai를 따릅니다.

무엇을 설치하나?

한 줄 답: OpenClaw(앱 또는 CLI)와 Gateway 실행에 필요한 런타임, 로컬 추론을 쓸 경우 Ollama, 코딩 위임 시 Claude Code·Codex·OpenCode 중 하나 이상입니다.

공식 Setup 문서는 맞춤 설정을 레포 밖이 아니라 다음 경로에 두라고 안내합니다.

  • 설정: ~/.openclaw/openclaw.json
  • 워크스페이스: ~/.openclaw/workspace (스킬·프롬프트·메모리)

부트스트랩만 필요하면:

openclaw setup --baseline

(전역 설치가 없으면 소스 체크아웃에서 pnpm openclaw setup --baseline.)

안정 경로는 macOS 앱이 번들 Gateway를 관리하는 흐름이고, 개발 경로는 pnpm gateway:watch로 Gateway를 직접 띄운 뒤 앱을 Local 모드로 붙입니다. Linux에서는 systemd user 서비스와 linger 설정이 Gateway가 로그아웃 시 죽지 않게 하는 데 중요합니다.

로컬 모델 경로를 쓸 때는 Ollama를 별도로 두고, 도구 사용이 가능한 모델을 준비합니다. 코딩 작업을 터미널 에이전트에 맡기려면 번들 스킬 coding-agent가 claude, codex, opencode(또는 문서에 적힌 지원 CLI) 중 하나를 PATH에서 요구합니다.

상태·인증 위치(디버깅용)는 문서에 대략 다음과 같이 나뉩니다.

  • 채널/프로바이더: ~/.openclaw/credentials/
  • 모델 인증·세션: 상태 디렉터리의 SQLite 스토어
  • 로그: /tmp/openclaw/ (문서에 명시된 기본 경로)

모델 엔드포인트는 어떻게 넣나?

한 줄 답: Ollama는 OpenAI 호환 /v1이 아니라 네이티브 호스트(기본 http://127.0.0.1:11434)를 쓰고, openclaw 온보딩·models 명령으로 프로바이더와 모델을 고릅니다.

공식 Ollama 프로바이더 문서는 OpenClaw가 Ollama의 native /api/chat 경로를 사용한다고 설명합니다. 온보딩에서 Ollama를 고른 뒤 Cloud + Local, Cloud only, Local only 중 모드를 선택합니다. Local only / Cloud + Local은 Ollama base URL을 묻고 설치된 모델을 검사합니다.

일반적인 확인·선택 흐름입니다.

openclaw models list --provider ollama
openclaw models set ollama/<model>

자동 디스커버리는 메모리에 로드된(/api/ps), 도구 지원·충분한 컨텍스트가 확인된 모델을 후보로 삼습니다. 디스크에만 있고 로드되지 않은 모델은 자동 후보가 아니며, Desktop Model Setup에서 Local only로 명시 연결할 수 있습니다. Cloud only는 OLLAMA_API_KEY와 호스팅 기본값을 사용합니다.

Gateway WebSocket 기본 포트는 문서 기준 ws://127.0.0.1:18789이므로 앱·CLI가 같은 포트를 보도록 맞춥니다. 헤드리스 한 턴은 openclaw agent exec(임베디드) 또는 Gateway에 붙는 openclaw agent 경로를 문서의 CLI 가이드대로 사용합니다.

Cursor/Claude와 역할은?

한 줄 답: OpenClaw는 Gateway·스킬·세션을 오케스트레이션하고, Cursor IDE나 Claude Code·Codex·OpenCode는 코딩 실행 쪽(특히 coding-agent 스킬의 워커)으로 둡니다.

공식 Skills 문서에서 coding-agent는 opt-in입니다. ~/.openclaw/openclaw.json에 예를 들어 다음을 넣습니다.

{
  skills: {
    entries: {
      "coding-agent": { enabled: true }
    }
  }
}

스킬 메타데이터는 claude / codex / opencode 중 하나 이상이 있을 것을 요구하며, 큰 리팩터·PR·이슈-to-PR 루프처럼 코딩 위임에 쓰고, 단순 수정·읽기 전용 조회에는 쓰지 말라고 안내합니다. Cursor 에디터 자체는 OpenClaw 설치 목록의 필수 바이너리가 아니며, IDE에서 편집하는 흐름과 Gateway가 워커 CLI를 띄우는 흐름을 역할로 나누면 됩니다.

정리하면 최소 경로는 OpenClaw setup + Gateway → (선택) Ollama 네이티브 연결 → coding-agent 활성화 + 워커 CLI 인증입니다. 버전·패키지 매니저 핀은 설치 시점의 공식 Getting Started / Setup 페이지를 확인하시기 바랍니다.

출처