안녕하세요, KHG Lab입니다.
AI를 쓰는 방식이 조금씩 바뀌고 있습니다. 예전에는 웹사이트에 접속해 질문하고 답을 받는 것이 전부였다면, 요즘은 내 컴퓨터에서 도구를 직접 실행해 두고 필요할 때마다 일을 맡기는 사례가 늘고 있습니다.
저도 직접 해보고 싶어서 맥북에 OpenClaw를 설치해 봤습니다. 그런데 막상 해보니 설치 자체보다 “이게 지금 제대로 된 건가?”를 판단하는 쪽이 더 헷갈렸습니다. 같은 지점에서 멈추는 분이 있을 것 같아 순서대로 정리해 두려고 합니다.
지난 글에서는 OpenClaw가 어떤 역할을 하는지 살펴봤습니다. 짧게 다시 말하면, 채팅 앱과 AI 모델, 그리고 파일을 읽고 쓰는 도구들 사이에서 요청을 전달해 주는 중간 창구입니다. 이 창구 역할을 맡는 프로그램을 Gateway라고 부릅니다.
이 글을 읽으면 맥북에 OpenClaw를 설치하는 순서와, 설치가 제대로 끝났는지 확인하는 방법을 알 수 있습니다.
설치 전에 준비할 세 가지
첫째, Node.js입니다. OpenClaw는 Node.js 위에서 동작합니다. 자바스크립트로 만든 프로그램을 컴퓨터에서 실행해 주는 기반 소프트웨어라고 보면 됩니다.
Node가 설치돼 있지 않아도 괜찮습니다. 아래에서 소개할 설치 스크립트가 필요할 때 Node를 함께 설치합니다. 이미 Node를 쓰고 있다면 터미널에서 node --version으로 버전을 확인한 뒤, 공식 설치 문서에서 요구 버전을 맞춰 주세요.
둘째, 모델 제공자의 API 키입니다. OpenClaw는 AI 모델을 직접 제공하지 않고 연결하는 역할을 합니다. Anthropic, OpenAI, Google처럼 사용할 제공자를 정하고 계정과 키를 미리 준비해 두면 설치 과정이 끊기지 않습니다.
셋째, 터미널입니다. 맥의 기본 터미널 앱이면 충분합니다. 명령어를 외울 필요는 없고, 이 글의 명령을 복사해서 붙여 넣는 정도면 됩니다.
설치는 명령 한 줄로 시작한다
공식 문서가 권장하는 방법은 설치 스크립트입니다.
curl -fsSL https://openclaw.ai/install.sh | bash이 스크립트는 운영체제를 확인하고, 필요하면 Node를 설치하고, OpenClaw를 설치한 뒤 설정 과정을 자동으로 이어서 시작합니다.
Node를 직접 관리하고 있다면 npm으로 설치할 수도 있습니다.
npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon--allow-scripts=openclaw은 공식 문서에 안내된 npm 설치 옵션입니다.
터미널보다 앱이 익숙하다면 macOS 메뉴바 앱을 쓰는 방법도 있습니다. 다만 처음이라면 설치 스크립트 쪽이 단순합니다.
온보딩: 모델을 실제로 한 번 호출해 본다
설치가 끝나면 온보딩이 이어집니다. 온보딩은 프로그램을 처음 쓸 때 필요한 값을 순서대로 물어보고 설정해 주는 과정입니다. 직접 실행하려면 openclaw onboard를 입력합니다.
온보딩은 보안 안내를 확인한 뒤, 이 컴퓨터에서 이미 사용할 수 있는 AI 접근 경로가 있는지 찾아봅니다. 그리고 찾은 경로로 실제 응답을 한 번 받아 보고, 성공한 경우에만 그 설정을 저장합니다. 자동으로 찾지 못하면 OpenAI, Anthropic, xAI, Google, OpenRouter 중에서 직접 고를 수 있고, 이때도 같은 방식으로 검증합니다.
설정 파일에 값만 적어 두고 나중에 실패하는 대신, 실제로 한 번 통과시킨 설정만 남기는 방식입니다.
이후 워크스페이스와 Gateway, 채널 설정이 이어집니다. 지금 정하기 어려운 항목은 건너뛰어도 됩니다. 나중에 openclaw configure로 다시 설정할 수 있습니다.
설치가 끝났는지 확인하는 네 가지 명령
여기까지 왔다면 확인 단계입니다. 순서대로 실행해 보면 됩니다.
openclaw --version # 프로그램이 설치됐는지 확인
openclaw doctor # 설정에 문제가 없는지 점검
openclaw gateway status # Gateway가 실행 중인지 확인
openclaw dashboard # 브라우저에서 관리 화면 열기openclaw gateway status가 정상이면 Gateway가 대기 중이라는 표시와 함께 포트 번호 18789가 나옵니다. 포트는 프로그램이 통신에 사용하는 번호로, 이 숫자가 보이면 Gateway가 실행돼 있다는 뜻입니다. 이어서 openclaw dashboard를 실행해 브라우저에 관리 화면이 뜨고, 그 화면의 채팅창에 메시지를 입력했을 때 답이 돌아오면 설치는 완료된 것입니다.
이 마지막 확인을 건너뛰지 않는 편이 좋습니다. 설치 명령이 오류 없이 끝났더라도 모델 연결이나 Gateway 실행에서 막혀 있을 수 있기 때문입니다.
맥을 껐다 켜도 유지되게 하려면
컴퓨터를 재시작한 뒤에도 Gateway가 자동으로 켜지게 하려면 맥의 자동 실행 목록에 등록하면 됩니다. macOS에서는 이 목록을 LaunchAgent라고 부릅니다.
openclaw gateway install온보딩 단계에서 openclaw onboard --install-daemon으로 함께 등록할 수도 있습니다.
잘 안 될 때 확인할 것
가장 자주 만나는 문제는 설치가 끝났는데도 openclaw 명령을 찾지 못하는 경우입니다. 대부분 프로그램이 설치된 폴더가 터미널이 찾는 경로 목록에 없어서 생깁니다. 아래 명령으로 현재 상태를 확인할 수 있습니다.
node -v
npm prefix -g
echo "$PATH"원인이 짐작되지 않는다면 openclaw triage를 실행해 보세요. 설정을 바꾸지 않고 현재 상태만 점검한 뒤, 무엇이 문제인지 정리해 줍니다. 점검 결과를 직접 읽고 싶다면 openclaw doctor를 사용하면 됩니다.
설치 직후에 정해둘 것
설치가 끝나면 바로 여러 기능을 연결하고 싶어집니다. 그전에 한 가지를 먼저 정하는 편이 좋습니다.
AI 에이전트가 어떤 작업을 스스로 실행할 수 있고, 어떤 작업에서 사용자 승인을 받을지에 대한 기준입니다. 이 기준을 정하지 않은 채 기능을 늘리면, 나중에 어떤 작업이 어떤 권한으로 실행되고 있는지 파악하기 어려워집니다.
지난 글에서 정리한 세 가지 원칙(작업 범위 제한, 중요한 작업 사전 승인, 인증정보 분리 보관)이 이 판단의 출발점이 됩니다.
마무리
맥북에서 OpenClaw를 설치하는 과정은 준비물 확인, 설치 명령 실행, 온보딩, 작동 확인 네 단계로 정리할 수 있습니다.
한 줄로 정리하면, 설치 명령이 끝난 시점이 아니라 관리 화면에서 첫 응답을 받은 시점이 설치 완료입니다.
다음 글에서는 AI 에이전트의 권한 설정을 다루겠습니다. 모든 작업을 맡기는 방식과 실행 전에 승인을 받는 방식이 각각 어떤 상황에 맞는지 비교해 보겠습니다.