내 PC/서버에 직접 설치해 텔레그램·디스코드로 제어하는 셀프호스팅 AI 에이전트 플랫폼입니다.
외부 서버 없이 로컬 환경에서 Claude, GPT 등 LLM을 연결해 나만의 AI 직원을 구성할 수 있습니다.
시즌 1의 openclaw 설치부터 시작하여 채널 연결, 에이전트 심화, 보안 강화, 클라우드 배포, n8n 자동화, 트레이딩 봇 구축까지. 지난 29편의 여정을 함께 달려오신 여러분은 이제 당당한 셀프호스팅 AI 서버의 주인입니다.
서버를 운영하다 보면 터미널 창에서 명령어를 입력해야 할 일이 자주 생깁니다. 100개가 넘는 openclaw cli 명령어를 전부 외우는 건 불가능하죠. 대망의 마지막 30편에서는 일상적인 운영부터 장애 대응, 보안 점검, 스킬 관리까지 반드시 알아야 할 핵심 명령어만 카테고리별로 정리한 치트시트(Cheat Sheet)를 제공합니다. 이 글 하나만 북마크하면 어떤 상황에서도 막히지 않습니다.
지난 편(이전: 트레이딩 봇 알림 자동화 — OKX 시그널 → Telegram 채널 연동)에서는 TradingView 시그널을 AI가 분석하여 텔레그램으로 자동 브리핑을 전송하는 실전 자동화 파이프라인을 완성했습니다.
진단 및 복구 — 시스템의 만병통치약 doctor 명령어
서버에 문제가 생겼거나 설정 파일을 수정한 뒤 가장 먼저 찾아야 할 명령어입니다. openclaw doctor는 전체 CLI 명령어 중 가장 중요하고 유용한 단일 명령어입니다. 특히 agents.defaults에 들어가야 할 설정이 개별 에이전트 블록에 잘못 들어갔을 때 시스템은 에러 없이 조용히 무시해 버리는데, doctor --fix가 이런 문제를 정확히 찾아내어 자동으로 고쳐줍니다.
# 시스템 상태, 설정 파일 오류, 종속성 누락 등을 종합적으로 진단합니다.
openclaw doctor
# 잘못된 위치의 설정 키를 찾아 자동으로 수정해 줍니다.
# config 편집 후 또는 업그레이드 후 반드시 실행하는 필수 명령어입니다.
openclaw doctor --fix| 명령어 | 역할 | 사용 시점 |
|---|---|---|
| openclaw doctor | 전체 시스템 헬스 체크 | 문제 발생 즉시, 정기 점검 시 |
| openclaw doctor --fix | 설정 오류 자동 교정 | config 편집 후, 업그레이드 직후 |
openclaw doctor부터 실행하세요. 그래도 안 되면 openclaw doctor --fix. 이 두 명령어가 문제의 90%를 해결합니다.게이트웨이 및 프로필 관리 — gateway & profile 명령어
시스템을 켜고 끄거나, 설정 변경을 반영하거나, 여러 개의 독립적인 AI 인스턴스를 동시에 구동할 때 사용하는 명령어들입니다. --profile 플래그를 활용하면 회사용 비서와 개인용 비서를 완전히 분리하여 동일한 서버에서 운영할 수 있습니다.
# 기본 포트(18789)로 게이트웨이를 실행합니다.
openclaw gateway run
# 포트, 바인드, 플러그인 등 핫 리로드가 안 되는 설정 변경 사항을 반영합니다.
openclaw gateway restart
# 상세한 디버그 로그와 함께 게이트웨이를 시작합니다. (오류 추적 시 필수)
openclaw gateway --verbose
# 'work'라는 별도 프로필로 18790 포트에서 완전히 분리된 인스턴스를 실행합니다.
# 상태, 설정, 세션이 모두 독립적으로 분리됩니다.
openclaw --profile work gateway run --port 18790| 명령어 | 역할 | 사용 시점 |
|---|---|---|
| openclaw gateway run | 게이트웨이 시작 | 서버 부팅 후, 최초 실행 시 |
| openclaw gateway restart | 게이트웨이 재시작 | 포트·바인드·플러그인 변경 후 |
| openclaw gateway --verbose | 상세 로그 모드 실행 | 장애 원인 추적 시 |
| openclaw --profile [이름] gateway run --port [포트] | 다중 독립 인스턴스 실행 | 회사·개인 AI 동시 운영 시 |
보안 및 설정 조회 — security & config 명령어
AI 에이전트 운영에서 보안은 생명입니다. 주기적인 보안 감사와 설정 확인은 필수입니다. security audit --deep는 숨겨진 취약점을 심층적으로 발굴하며, config get은 설정 파일 수정 후 실제로 반영되었는지 확인하는 가장 확실한 방법입니다.
# 토큰 강도, 포트 노출(0.0.0.0 바인딩), 고위험 스킬 활성화 여부 등
# 보안 취약점을 심층적으로 검사합니다.
openclaw security audit --deep
# 실행 중인 게이트웨이 메모리에서 특정 설정 키의 현재 값을 직접 읽어옵니다.
# 설정이 제대로 반영되었는지 확인할 때 가장 확실한 방법입니다.
openclaw config get <key>
# 예: 현재 인증 토큰 설정 확인
openclaw config get auth.token| 명령어 | 역할 | 사용 시점 |
|---|---|---|
| openclaw security audit --deep | 보안 심층 취약점 검사 | 정기 점검, 외부 노출 환경 구성 후 |
| openclaw config get <key> | 실시간 설정값 조회 | 설정 변경 적용 여부 확인 시 |
Error: listen EADDRINUSE :::18789 오류가 뜨면 이전 게이트웨이 프로세스가 포트를 점유 중인 것입니다. Linux/macOS에서는 lsof -i :18789로 PID를 찾아 kill -9 [PID]로 강제 종료하거나, openclaw.json에서 "port" 값을 다른 번호로 변경하세요.스킬 모듈 관리 — skill 명령어 총정리
AI의 손발이 되어주는 스킬(Skill) 패키지들을 설치하고 점검하는 명령어입니다. skill list로 현재 AI가 얼마나 많은 컨텍스트를 스킬에 소비하고 있는지 확인하고 불필요한 스킬을 제거하면 AI 응답 품질을 높일 수 있습니다.
# 새로운 스킬을 설치합니다.
openclaw skill install google-calendar
# 특정 스킬의 의존성(바이너리, 환경 변수 등)이 갖춰졌는지 검사합니다.
openclaw skill check google-calendar
# 현재 활성화된 스킬 목록과 시스템 프롬프트(Context) 점유율을 확인합니다.
openclaw skill list
# 스킬을 제거합니다.
openclaw skill remove google-calendar| 명령어 | 역할 | 사용 시점 |
|---|---|---|
| openclaw skill install <이름> | 스킬 패키지 설치 | 새 기능 추가 시 |
| openclaw skill check <이름> | 스킬 의존성 검사 | 스킬이 동작 안 할 때 |
| openclaw skill list | 활성 스킬 목록 및 컨텍스트 점유율 확인 | AI 응답이 느려졌을 때, 정기 점검 시 |
| openclaw skill remove <이름> | 스킬 제거 | 불필요한 스킬 정리 시 |
📎 OpenClaw 공식 문서 CLI Reference →
openclaw gateway restart — 설정 변경 후 재시작②
openclaw doctor — 뭔가 이상하다 싶을 때 진단이 두 가지만 기억하면 일상 운영의 90%가 해결됩니다. 나머지는 이 글을 북마크하고 필요할 때 찾아보세요.
실전 팁과 주의사항
- 업그레이드 후 반드시 doctor --fix 실행: OpenClaw 버전을 업그레이드하면 설정 파일 스키마가 변경되어 기존 키 위치가 잘못된 것으로 판정될 수 있습니다. 업그레이드 직후에는 항상
openclaw doctor --fix를 실행하여 설정 호환성을 확보하세요. - --verbose 모드는 운영 환경에서 조심:
--verbose모드는 인증 토큰, API 키 등 민감한 정보가 로그에 포함될 수 있습니다. 문제 해결 후에는 반드시 일반 모드로 재시작하고, 로그 파일은 즉시 삭제하세요. - 프로필 분리로 실험적 설정 안전하게 테스트: 새로운 스킬이나 설정을 적용하기 전에
--profile test처럼 별도 프로필로 먼저 테스트하세요. 운영 중인 메인 인스턴스에 영향을 주지 않고 안전하게 실험할 수 있습니다. - skill list로 정기적인 컨텍스트 다이어트: 스킬이 많아질수록 시스템 프롬프트가 길어져 AI의 집중력(응답 품질)이 떨어질 수 있습니다. 주기적으로
openclaw skill list를 실행하여 사용하지 않는 스킬을 과감히 제거하세요.
자주 묻는 질문 (FAQ)
- 설정 파일(openclaw.json)을 바꿨는데 적용이 안 될 때 어떤 명령어를 써야 하나요?
- 두 가지를 기억하세요. 첫째, 포트 번호(
port)나 바인딩(bind)처럼 네트워크 소켓을 새로 열어야 하는 설정은 반드시openclaw gateway restart로 재시작해야 합니다. 둘째, 오타나 잘못된 키 위치가 의심된다면openclaw doctor --fix를 실행하여 문법적 오류를 자동으로 바로잡으세요. - 에러가 발생했을 때 상세한 로그를 보려면 어떻게 하나요?
openclaw gateway --verbose명령어로 게이트웨이를 구동하세요. 스킬 로딩 과정부터 메신저 인증 단계까지 아주 상세한 로그가 출력되어 어느 지점에서 문제가 발생했는지 즉각 파악할 수 있습니다. 단, 운영 환경에서는 민감 정보 노출에 주의하세요.- 초보자가 이 많은 명령어를 전부 외워야 하나요?
- 절대 아닙니다! 일상 운영에서는
openclaw gateway restart와openclaw doctor두 가지만 기억해도 AI 에이전트 만들기와 운영의 90%가 해결됩니다. 나머지 명령어들은 이 글을 즐겨찾기 해두셨다가 필요할 때 복사해서 사용하시면 됩니다. - "Error: listen EADDRINUSE :::18789" 포트 사용 중 에러가 뜨면 어떻게 해결하나요?
- 이전에 실행해 둔 게이트웨이 프로세스가 정상 종료되지 않고 포트를 점유하고 있는 상태입니다. Linux/macOS에서는
lsof -i :18789로 프로세스 ID를 찾아kill -9 [PID]로 강제 종료하거나,openclaw.json에서"port": 19000등 다른 번호로 변경하면 해결됩니다.
처음 까만 터미널 창을 열며 두려워했던 순간부터, 나만의 셀프호스팅 AI가 텔레그램으로 아침 브리핑을 보내고 n8n과 연동해 수백 개의 앱을 조종하는 자동화 마스터가 되기까지 — 정말 놀라운 여정이었습니다.
인공지능은 더 이상 빅테크 기업이나 전문 개발자들만의 전유물이 아닙니다. 나만의 프라이버시를 지키면서 세상에 단 하나뿐인 전속 AI 비서를 직접 만들어낸 여러분의 새로운 디지털 라이프를 진심으로 응원합니다. OpenClaw의 대규모 업데이트가 있을 때 특별 편으로 다시 찾아뵙겠습니다. 그동안 사랑해 주셔서 감사합니다! 🙏
긴 여정을 함께 해주신 모든 분께 감사드립니다! 🙌
도움이 됐다면 댓글 한 마디, 공유 한 번이 다음 시리즈의 큰 동력이 됩니다.
📬 다음 시리즈 소식 받기 → AI 활용 가이드 구독
댓글