OpenClaw를 처음 설치한다면 설치 명령부터 복사하기보다 실행 컴퓨터와 모델 인증을 정하고, 게이트웨이와 채널을 차례로 확인하세요. 이 글은 2026년 3월 5일 직접 설치한 기록을 바탕으로 준비 항목, 첫 연결의 완료 기준, 막혔을 때 돌아갈 지점을 안내합니다.
설치 명령, 지원 운영체제, 필요한 Node.js 버전과 온보딩 화면은 바뀔 수 있습니다. 실행 전 공식 설치 문서와 Getting Started에서 현재 요구 사항을 확인하세요.
OpenClaw를 설치하면 달라지는 것
OpenClaw는 모델과 대화하는 화면에 더해 파일, 브라우저, 메시지 채널과 같은 도구를 연결할 수 있는 에이전트 실행 환경입니다. 연결한 권한에 따라 외부 서비스에 메시지를 보내거나 로컬 파일을 바꿀 수도 있으므로 일반 챗봇보다 설치와 권한 검토가 중요합니다.
| 구성 요소 | 역할 | 설치 전 결정 |
|---|---|---|
| 실행 컴퓨터 | 게이트웨이와 작업 실행 | 항상 켤지, 개인 PC와 분리할지 |
| 모델 제공자 | 요청 처리 | 구독·API·로컬 중 데이터와 비용 기준 |
| 메시지 채널 | 요청과 결과 전달 | 허용 사용자와 대화 범위 |
| 워크스페이스 | 지침·기억·작업 파일 보관 | 백업, 접근권한, 개인정보 범위 |
설치 전 준비
- 지원되는 운영체제와 현재 버전 확인
- 관리자 권한이 필요한 단계와 설치 위치 확인
- Node.js 등 런타임의 요구 버전 확인
- 모델 제공자의 현재 요금·자동화 허용 범위 확인
- 별도 테스트용 메시지 채널과 봇 준비
- 토큰을 저장할 비밀 관리 방법 준비
기존 서버나 업무용 PC에 바로 설치하기보다, 되돌릴 수 있는 테스트 환경에서 먼저 확인하는 편이 안전합니다. 공개 서버에 게이트웨이 포트를 열기 전에 로컬 접근만으로 시험하세요.
설치 파일은 출처와 내용을 확인합니다
원격 스크립트를 내려받아 바로 셸이나 PowerShell로 실행하는 방식은 편리하지만, 다운로드한 내용이 그대로 실행됩니다. 공식 도메인인지 확인하고 가능하면 스크립트를 먼저 저장해 내용을 검토한 뒤 공식 문서의 현재 절차를 따릅니다.
설치 전후의 런타임과 프로그램 버전은 다음처럼 확인할 수 있습니다. 요구 버전 숫자는 공식 문서를 기준으로 판단하세요.
node --version
npm --version
openclaw --version
openclaw --helpopenclaw --version이 출력된다는 것은 실행 파일을 찾았다는 뜻입니다. 모델 연결, 게이트웨이, 채널까지 정상이라는 증거는 아닙니다.
첫 연결에서는 하나만 바꾸고 결과를 남깁니다
처음부터 기존 업무 채널까지 연결하지 말고, 아래 순서로 확인 범위를 늘리는 것을 권합니다. 단계마다 실행한 환경, 성공 여부, 비밀값을 제외한 오류 문구를 적으면 재설치 없이도 어디서 막혔는지 설명할 수 있습니다.
- 명령 확인: 버전과 도움말이 나오지 않으면 모델 키를 바꾸지 말고 실행 경로와 런타임을 확인합니다.
- 로컬 연결 확인: 게이트웨이 상태를 먼저 확인합니다. 이 단계가 실패하면 채널 설정을 추가하지 않습니다.
- 모델 확인: 개인정보 없는 짧은 질문으로 응답 여부를 봅니다. 실패 시 제공자 인증과 계정 사용 한도를 나눠 확인합니다.
- 채널 확인: 모델 응답이 확인된 뒤 테스트 대화 한 곳을 연결합니다. 수신과 답변 위치까지 맞아야 다음 채널을 추가합니다.
제공자를 아직 못 골랐다면 작업별 모델 선택 기준을 먼저 정하고, 첫 연결은 됐지만 응답 경로가 어긋나면 수신·처리·발신을 나누는 장애 점검 순서로 이어가세요.
온보딩은 최소 권한으로 시작합니다
2026년 3월 기록에서는 온보딩 명령과 데몬 설치 옵션을 사용했습니다. 현재 버전에 같은 명령이 있는지는 openclaw onboard --help로 먼저 확인하세요.
openclaw onboard --help처음에는 한 모델, 로컬 게이트웨이, 테스트 채널 하나만 연결하는 편이 좋습니다. 여러 제공자와 스킬을 한 번에 추가하면 실패 원인을 구분하기 어렵습니다.
모델 제공자 선택
- 현재 계정에서 실제 사용할 수 있는 인증 방식인지
- 구독과 API 과금이 별개인지
- 입력한 자료가 어디로 전송되고 보관되는지
- 사용량 한도와 초과 시 동작이 무엇인지
인증 URL, API 키, 리다이렉트 코드와 토큰은 캡처하거나 공유 문서에 붙이지 않습니다. 비밀값이 노출되었다면 해당 제공자에서 폐기하고 다시 발급합니다.
메시지 채널 연결
텔레그램 같은 채널을 연결할 때는 공식 봇 관리 계정인지 확인하고, 새 봇 토큰을 비밀값으로 취급합니다. 봇의 사용자명과 토큰은 서로 다른 정보이며 토큰은 공개해서는 안 됩니다.
- 허용된 사용자만 요청할 수 있는지
- 그룹에 추가했을 때 메시지 범위가 달라지는지
- 응답이 원래 대화로 돌아오는지
- 실패한 요청을 중복 실행하지 않는지
백그라운드 실행은 시험 뒤에 켭니다
데몬이나 시스템 서비스로 등록하면 로그인 후에도 계속 실행될 수 있습니다. 먼저 수동 실행에서 정상 종료와 로그 위치를 확인한 뒤 자동 시작을 켭니다. 운영체제마다 서비스 관리 방식이 다르므로 현재 설치 문서를 따릅니다.
로컬 대시보드를 외부 네트워크에 직접 공개하지 않습니다. 바인드 주소, 인증, 방화벽과 프록시 설정을 이해하지 못한 상태라면 로컬 접속으로 제한합니다.
설치 완료는 네 단계로 확인합니다
- 프로그램: 버전과 도움말이 오류 없이 출력됨
- 게이트웨이: 현재 버전의 상태 명령에서 실행 상태 확인
- 모델: 민감하지 않은 테스트 질문 1건에 응답
- 채널: 허용된 사용자 메시지 1건이 올바른 대화로 돌아옴
당시 기록에서 사용한 상태 명령은 아래와 같습니다. 현재 도움말에서 지원 여부를 확인한 뒤 실행하세요.
openclaw gateway status
openclaw status
설치 직후 보안 점검
| 항목 | 확인 내용 |
|---|---|
| 토큰 | 설정 파일 권한과 비밀 저장 위치 |
| 네트워크 | 불필요한 외부 포트가 열리지 않았는지 |
| 도구 | 파일·셸·브라우저 권한이 필요한 범위인지 |
| 채널 | 허용 사용자가 제한되어 있는지 |
| 로그 | 비밀값과 대화 전문이 남지 않는지 |
| 복구 | 설정 백업과 서비스 중지 방법을 확인했는지 |
문제가 생기면 한 단계씩 분리합니다
명령을 찾지 못하면 PATH와 런타임부터, 게이트웨이가 시작되지 않으면 설정 문법과 로그부터 확인합니다. 모델만 실패하면 제공자 인증과 사용량을, 채널만 실패하면 봇 상태와 허용 사용자·바인딩을 확인합니다. 전체 재설치 전에 어느 단계까지 정상인지 기록하세요.
설치 완료의 기준은 축하 화면이 아니라 최소 권한으로 시작한 서비스가 예상한 경로에서 한 번 정상 동작하고, 중지와 복구 방법까지 확인된 상태입니다.
사례 기준일: 2026-03-05. 기존 설치 기록을 2026-09-03에 재구성했습니다. 이 글을 위해 최신 버전의 설치 스크립트, 지원 운영체제, 런타임 요구 버전과 온보딩 옵션 전체를 다시 실행 검증하지 않았습니다. 최신 절차는 OpenClaw 공식 문서를 우선하세요.
편집 보완: 2026-09-10. 기존 사례와 작성·재편집 날짜를 유지하며 판단 절차와 관련 글을 보강했습니다. 이 날짜는 새 설치·성능 시험 또는 현재 운영 상태 확인을 뜻하지 않습니다.