AI 학습 라이브러리

실무에서 쓰는 AI 도구,
한 장씩 넘기며 익히세요

한 페이지에 한 개념씩. 스크롤 없이 책장 넘기듯 학습합니다. 실무자가 직접 검증한 내용으로 구성됩니다.

macmini ~ agents
Mac mini 에이전트 실전 가이드
MAC·MINI
Mac mini 에이전트 실전 가이드
Mac mini M4/M5에서 NanoClaw·HermesClaw로 24시간 AI 에이전트를 운영하는 법. 하드웨어 선택·설치·자동 실행·보안·실전 사례까지, 한 장씩 넘기며 따라 합니다.
NanoClaw·HermesClaw · 19편 학습 시작
claude ~ code
CLAUDE
Claude Code 가이드
Anthropic 공식 CLI. Hooks, MCP, 에이전트 오케스트레이션.
준비 중Coming Soon
codex ~ cli
CODEX
Codex CLI 가이드
OpenAI 터미널 에이전트. AGENTS.md, 샌드박스.
준비 중Coming Soon
midjourney ~ v7
MIDJOURNEY
Midjourney V7 가이드
V7 프롬프트, 레퍼런스 이미지, 스타일 일관성.
준비 중Coming Soon
Mac mini 에이전트 실전 가이드
섹션 01 / 19

Mac mini 에이전트 실전 가이드

Mac mini M4/M5에서 NanoClaw·HermesClaw로 24시간 AI 에이전트를 운영하는 실전 가이드 — 전 19편. 하드웨어 선택·설치·인증부터 자동 실행·보안·문제 해결·실전 사례까지.

1. 이 가이드에서 할 수 있는 것

01왜 Mac mini에 개인 AI 에이전트 환경을 만들까?

요즘 AI를 쓰는 방법은 크게 두 가지다.

첫 번째는 웹사이트나 앱에 들어가서 필요할 때마다 AI에게 질문하는 방식이다. ChatGPT, Claude, Gemini 같은 서비스를 브라우저에서 열고, 사람이 직접 질문을 입력하고, 답변을 복사해서 다른 곳에 붙여 넣는다.

두 번째는 AI가 내가 자주 쓰는 메시징 앱 안으로 들어오고, 내 컴퓨터에서 계속 실행되며, 필요한 일을 대신 처리하도록 만드는 방식이다.

내 책상 위 Mac mini가 꺼지지 않는 개인 AI 작업실이 되고, 나는 평소 쓰는 메신저로 그 작업실에 일을 맡긴다.

사용자는 Telegram, Discord, Slack, WhatsApp, WeChat 같은 메시징 앱에서 말을 걸고, Mac mini 안에서 실행 중인 에이전트가 메시지를 받아 처리한 뒤 다시 답장을 보낸다.

02NanoClaw와 HermesClaw 이해하기

NanoClaw는 내 컴퓨터에서 실행되는 개인 AI 에이전트 환경이다. 사용자가 메시징 앱에서 말을 걸면, NanoClaw가 그 메시지를 받아 AI 모델에 전달하고, 필요한 작업을 실행한 뒤 답장을 보낸다. 공식 설명 기준으로 WhatsApp, Telegram, Slack, Discord, Microsoft Teams 같은 여러 메시징 앱과 연결할 수 있으며, 각 에이전트 그룹은 Docker 컨테이너 안에서 격리 실행된다.

HermesClaw는 조금 더 특수한 목적을 가진다. Hermes Agent와 OpenClaw를 같은 WeChat 계정에서 함께 쓰고 싶을 때 의미가 있다. HermesClaw는 하나의 iLink 연결을 잡고, Hermes와 OpenClaw 쪽에는 로컬 프록시를 제공하는 방식으로 연결 충돌을 피하도록 설계된 커뮤니티 프로젝트다.

초보자 입장에서는 이름보다 역할을 이해하는 것이 중요하다:

그리고 Mac mini는 이 둘을 24시간 켜두기 좋은 작은 개인 서버 역할을 한다.

03Mac mini를 선택한 이유

Mac mini는 크기가 작고, 소음이 적고, 전력 소모가 비교적 낮으며, 책상 위나 공유기 옆에 계속 켜두기 쉽다.

노트북처럼 들고 다니는 장비가 아니라 한자리에 두고 운영하기 좋아서, 개인 자동화 서버, 메시징 봇 서버, 홈서버, 개발 테스트 장비로 쓰기에 적합하다.

특히 M4 Mac mini는 Apple Silicon 기반이라 성능 대비 전력 효율이 좋고, Docker, Node.js, pnpm 같은 개발 도구를 설치해 개인 AI 에이전트 환경을 구성하기에 충분한 출발점이 된다.

다만 M5 Mac mini처럼 공식 발표 전이거나 사양이 확정되지 않은 제품은 성능을 단정하지 않고, 공식 발표 후 CPU, GPU, 메모리, 저장장치, Docker 호환성, 발열, 전력 소모를 다시 확인해야 한다.

04이 환경으로 할 수 있는 일

이 환경을 배우면 아래와 같은 실전 자동화를 만들 수 있다:

중요한 차이는 이것이다. 일반 AI 채팅은 사람이 매번 브라우저를 열고 질문해야 하지만, 개인 AI 에이전트 서버는 내가 자주 쓰는 메시징 앱 안에서 계속 대기하며, 반복되는 일을 맡길 수 있다.

05초보자의 학습 순서

처음부터 거창한 자동화를 만들 필요는 없다. 초보자의 목표는 아주 작아야 한다.

첫 단계: 내 Mac mini에서 에이전트가 켜지고, 메시징 앱에서 말을 걸면 답장이 온다.

두 번째: 재부팅해도 다시 실행된다.

세 번째: API 키와 설정 파일을 안전하게 관리한다.

네 번째: 개인 비서, 업무 요약, 알림, 매매일지 보조 같은 실전 자동화를 하나씩 붙인다.

이 순서가 중요하다. 처음부터 완벽한 AI 비서를 만들려고 하면 대부분 설치, 인증, Docker, API 키, 로그 확인 단계에서 막힌다. 반대로 작은 성공을 먼저 만들면 전체 구조가 보인다.

06이 가이드의 목표

이 가이드는 Mac mini M4/M5를 개인 AI 에이전트 서버처럼 사용하는 방법을 다룬다.

구체적인 목표는:

이 글의 핵심은 "AI에게 질문하는 법"이 아니라 "AI가 대기하고 있는 개인 작업 환경을 만드는 법"이다.

07이 글을 보면 할 수 있게 되는 것

기본 설치

기본 운영

08실전 활용과 설명 방식

실전 활용

초보자 입장에서 막히는 부분

이 가이드는 개발자 문서 번역처럼 쓰지 않는다. 초보자가 실제로 막히는 지점 — 무슨 프로그램을 먼저 설치할지, 터미널 명령어, 설치 후 실행 실패, API 키 위치, Docker의 개념, 메시징 앱 연결, 재부팅 후 실행, 에러 로그 해석 — 을 중심으로 설명한다.

09세 가지 기준으로 정보 분류

확정 정보

공식 문서, 공식 저장소, 공식 사양 페이지에서 확인된 내용이다. 예를 들어 Mac mini M4 공식 사양은 Apple 공식 사양 페이지 기준으로 작성한다. 현재 Apple의 Mac mini 사양 페이지에는 M4와 M4 Pro 구성이 표시되어 있으며, M4는 10코어 CPU와 10코어 GPU, M4 Pro는 기본 12코어 CPU와 16코어 GPU 구성을 제공한다.

출시 전 정보

M5 Mac mini처럼 공식 발표 전이거나 발표 직전인 정보는 예상, 출시 전 기준, 공식 발표 후 확인 필요라고 표시한다.

실전 팁

공식 문서에는 짧게 지나가지만 실제 운영에서 중요한 부분이다. 처음부터 모든 메시징 앱을 연결하지 않기, 테스트 계정 분리, API 키 보안, 자동 실행 순서 등이 포함된다.

10Mac mini 사용 목적별 추천

처음 설치 연습
기본형 Mac mini로 충분
Telegram/Discord 개인봇
M4 기본형 또는 메모리 업그레이드
여러 메시징 앱 동시 운영
메모리 여유 있는 구성
Hermes / OpenClaw / 여러 에이전트 병행
M4 Pro 또는 M5급 고려
로컬 LLM 실험
메모리 큰 구성 우선
24시간 안정 운영
최고 사양보다 안정성, 백업, 로그 관리 우선

Mac mini M4는 Apple 공식 기준으로 16GB 통합 메모리부터 시작하며, 일부 구성은 24GB로 업그레이드할 수 있다. M4 Pro 구성은 24GB 통합 메모리부터 시작하고 48GB까지 구성할 수 있다.

M5 Mac mini는 공식 발표 후 CPU, GPU, 메모리 옵션, 저장장치, 포트 구성, Docker 호환성, 발열, 전력 소모를 다시 확인해야 한다.

11초보자가 지켜야 할 다섯 가지 원칙

원칙 1. 한 번에 하나씩 연결한다 — 처음부터 Telegram, Discord, Slack, WhatsApp, WeChat을 전부 연결하지 않는다. 처음에는 로컬 CLI 테스트 → Telegram 또는 Discord 같은 테스트용 채널 → 실제 사용할 메시징 앱 → 자동 실행 → 보안 강화 → 실전 자동화 추가 순서로 진행한다.

원칙 2. 실사용 계정부터 연결하지 않는다 — 처음 설치할 때는 테스트용 계정을 쓰는 것이 좋다. 메시징 앱 연동은 생각보다 민감하기 때문이다.

원칙 3. API 키는 절대 공개하지 않는다 — API 키는 비밀번호와 같다. 블로그에 올리거나, GitHub에 올리거나, 메신저로 보내거나, 테스트 키와 섞어 쓰지 않는다.

원칙 4. 자동 실행은 마지막에 한다 — 수동 실행도 안 되는데 자동 실행부터 설정하는 것은 흔한 실수다. 직접 실행 → 테스트 메시지 → 로그 확인 → 반복 실행 확인 → 재부팅 후 재실행 → 자동 실행 설정 순서를 지킨다.

원칙 5. 업데이트 전에는 백업한다 — 에이전트류 도구는 업데이트 후 설정 방식이 바뀔 수 있다. 설정 파일, .env 파일, 메모리 파일, 스킬 파일, 로그, Docker compose 파일을 백업한다.

12이 가이드의 최종 결과물

최소 완성 상태

실사용 가능 상태

안정 운영 상태

섹션 1 · 핵심 정리

첫 단원의 핵심

이 가이드는 Mac mini에 NanoClaw 또는 HermesClaw를 설치하는 단순 설치 글이 아니다. 초보자가 직접 운영 가능한 개인 AI 에이전트 환경을 만드는 것이 목표다.

핵심은 세 가지다:

내 Mac mini에서 에이전트가 켜지고, 메시지를 받고, 답장을 보내고, 다시 켜도 복구된다.

이 상태를 만든 뒤에 개인 비서, 업무 자동화, 트레이딩 보조 알림으로 확장하면 된다.

다음 단원

2. 준비물 확인하고 설치하기

2. 먼저 전체 그림 이해하기

01NanoClaw와 HermesClaw는 무엇을 해주는가?

NanoClaw와 HermesClaw는 둘 다 메시징 앱에서 AI 에이전트를 사용할 수 있게 도와주는 도구다.

쉽게 말하면 구조는 이렇다.

사용자 → Telegram / Discord / WhatsApp / WeChat 같은 메시징 앱 → Mac mini에서 실행 중인 에이전트 → AI 모델 호출 → 답장 생성 → 다시 메시징 앱으로 전달

즉, Mac mini는 단순한 컴퓨터가 아니라 항상 켜져 있는 개인 AI 중계 서버 역할을 한다.

02NanoClaw: 여러 메신저에 붙을 수 있는 개인 AI 직원

NanoClaw는 WhatsApp, Telegram, Discord, Slack, Microsoft Teams, iMessage, Matrix, Google Chat, Webex, Linear, GitHub, WeChat, email 같은 여러 채널을 지원한다. 각 에이전트 그룹은 Docker 컨테이너 안에서 격리 실행되며, 채널별로 독립 에이전트를 쓰거나 여러 채널을 하나의 세션으로 묶는 구조도 지원한다.

구조는 이렇다:

Telegram으로 질문 → NanoClaw가 받음 → Claude / 다른 AI 모델에게 물어봄 → 답장 생성 → Telegram으로 다시 보내줌

NanoClaw는 처음 시작하는 사람이 이해하기 좋다. 이유는 구조가 비교적 단순하고, 공식 문서에서도 "이해하고 커스터마이즈하기 쉬운 코드베이스"를 장점으로 내세운다.

03HermesClaw: WeChat 안에서 여러 에이전트를 나눠 쓰는 교통정리 도구

HermesClaw는 목적이 조금 다르다. Hermes Agent, OpenClaw, OpenCode를 같은 WeChat 계정에서 함께 사용하기 위한 브리지다. Hermes Agent와 OpenClaw를 같은 WeChat 계정에서 동시에 돌리면 iLink 연결 충돌이 생길 수 있는데, HermesClaw는 자신이 단일 iLink poller가 되고 Hermes와 OpenClaw 쪽에는 로컬 프록시를 제공하는 방식으로 문제를 해결한다.

구조는 이렇다:

WeChat 메시지 입력 → HermesClaw가 먼저 받음 → /hermes 명령이면 Hermes로 전달 → /openclaw 명령이면 OpenClaw로 전달 → /both 명령이면 둘 다 사용 → 결과를 다시 WeChat으로 전달

HermesClaw는 /hermes, /openclaw, /opencode, /both, /three 같은 명령으로 에이전트를 전환할 수 있다.

04Mac mini가 왜 이런 용도에 잘 맞는가?

Mac mini는 이 가이드에서 작고 조용한 상시 실행 장비로 본다.

AI 에이전트 운영에서 중요한 것은 최고 성능만이 아니다. 더 중요한 것은 아래 네 가지다.

1. 오래 켜둘 수 있는가? 2. 소음과 발열이 적은가? 3. 전력 소모가 부담스럽지 않은가? 4. 재부팅 후 자동 복구가 쉬운가?

Mac mini M4는 Apple 공식 사양 기준으로 5.0 x 5.0 x 2.0인치 크기이며, M4 모델 무게는 0.67kg, M4 Pro 모델 무게는 0.73kg이다. 또한 기가비트 이더넷을 기본 제공하고 10Gb 이더넷으로 구성할 수 있다.

이더넷 포트가 중요하다. 메시징 에이전트를 24시간 운영할 때는 Wi-Fi보다 유선 LAN이 안정적이다. 갑자기 메시지가 늦게 오거나 연결이 끊기는 문제를 줄이고 싶다면 가능하면 유선 연결을 우선한다.

05전체 작동 구조: NanoClaw 기준

NanoClaw 기준으로 보면 구조는 이렇게 이해하면 된다:

[메시징 앱] Telegram / Discord / Slack / WhatsApp 등 ↓ [라우터] 어떤 채널에서 온 메시지인지 확인 ↓ [에이전트 컨테이너] 각 에이전트가 Docker 안에서 실행 ↓ [AI 모델] Claude / OpenAI / 기타 모델 호출 ↓ [응답 전달] 다시 원래 메시징 앱으로 답장

NanoClaw 공식 문서는 단일 Node host가 세션별 에이전트 컨테이너를 오케스트레이션하고, 각 세션은 별도 SQLite 파일 구조를 사용한다고 설명한다. 또한 각 에이전트 그룹은 자기만의 CLAUDE.md, 메모리, 컨테이너, 허용된 마운트 범위를 갖는다고 설명한다.

초보자는 여기서 한 가지만 이해하면 된다.

"에이전트가 내 Mac 전체를 마음대로 쓰는 것이 아니라, 정해진 공간 안에서 실행되게 만드는 것이 핵심이다."

이것이 Docker나 컨테이너를 쓰는 이유다. Docker는 애플리케이션을 컨테이너 단위로 빌드, 공유, 실행하게 해주는 플랫폼이며, Docker 공식 페이지도 컨테이너 기반 실행과 격리를 핵심 개념으로 설명한다.

06M4 Mac mini로 가능한 작업

M4 Mac mini는 메시징 기반 AI 에이전트 운영에는 충분히 실전적인 장비다.

Apple 공식 사양 기준으로 Mac mini M4는 10코어 CPU, 10코어 GPU, 16코어 Neural Engine, 120GB/s 메모리 대역폭을 갖는다. M4 Pro는 12코어 CPU, 16코어 GPU, 273GB/s 메모리 대역폭을 갖고, 14코어 CPU와 20코어 GPU 구성으로도 선택할 수 있다.

M4 Mac mini에서 현실적으로 할 수 있는 작업은 다음과 같다:

- Telegram 개인 비서 봇 - Discord 작업 보조 봇 - Slack 업무 요약 봇 - 정해진 시간에 알림 보내기 - 메시지 요약 - 간단한 파일 정리 자동화 - 매매일지 작성 보조 - 뉴스 요약 후 메시지로 전달 - API 기반 가격 알림

M4 기본형도 메시징 에이전트 1~2개를 운영하는 용도로는 충분히 시작할 수 있다. 다만 여러 채널을 동시에 연결하거나, Docker 컨테이너를 여러 개 띄우거나, 로컬 LLM까지 같이 돌릴 계획이면 메모리 여유가 중요하다.

Apple 공식 사양 기준으로 Mac mini M4는 16GB 통합 메모리에서 시작하고 24GB 또는 32GB로 구성할 수 있으며, M4 Pro는 24GB 통합 메모리에서 시작하고 48GB 또는 64GB로 구성할 수 있다.

07M5 Mac mini에서 기대할 수 있는 점

M5 칩 자체는 Apple이 공식 발표했다. Apple은 M5가 3세대 3나노미터 공정 기반이며, 10코어 GPU 구조에 각 GPU 코어마다 Neural Accelerator를 탑재했고, M4 대비 AI용 GPU 피크 컴퓨트 성능이 4배 이상이라고 설명했다. 또한 M5의 통합 메모리 대역폭은 153GB/s로, M4보다 약 30% 높다고 밝혔다.

다만 이 가이드에서 중요한 기준은 하나다.

"M5 칩 정보"와 "M5 Mac mini 제품 사양"은 구분해야 한다.

M5 칩이 공식 발표되었다고 해서 M5 Mac mini의 포트 구성, 메모리 옵션, 저장장치 옵션, 발열, 가격, 출시일이 모두 확정되는 것은 아니다. Mac mini에 적용된 공식 사양은 Apple의 Mac mini 사양 페이지나 Apple Support 문서가 갱신된 뒤 확인하는 것이 안전하다.

M5 Mac mini가 공식 출시되면 이 가이드에서 특히 확인해야 할 항목은 아래와 같다:

- 기본 메모리 용량 - 최대 메모리 옵션 - 기본 SSD 용량 - Thunderbolt 4 / Thunderbolt 5 구성 - 10Gb 이더넷 옵션 유지 여부 - Docker Desktop 호환성 - 장시간 실행 시 발열 - 재부팅 후 자동 실행 안정성 - 기존 NanoClaw / HermesClaw 설치법 호환 여부

M5의 장점은 특히 AI 처리와 메모리 대역폭 쪽에서 기대할 수 있다. 하지만 NanoClaw나 HermesClaw를 단순 메시징 에이전트로 쓴다면 CPU/GPU 성능보다 네트워크 안정성, 메모리 여유, 자동 복구 설정, 로그 관리가 더 중요할 수 있다.

08"AI 모델"과 "에이전트"는 다르다

AI 모델은 답변을 만드는 두뇌다.

예를 들면 다음과 같다:

Claude OpenAI 모델 로컬 LLM 기타 API 기반 모델

에이전트는 그 두뇌를 실제 작업에 연결하는 실행 담당자다.

메시지 받기 파일 읽기 명령어 실행하기 일정 확인하기 API 호출하기 답장 보내기

초보자는 이 둘을 자주 섞어서 생각한다. 정리하면 이렇다:

AI 모델 = 생각하는 두뇌 에이전트 = 일을 처리하는 직원 NanoClaw / Hermes / OpenClaw = 직원을 움직이게 해주는 시스템 Mac mini = 직원이 일하는 사무실 Docker = 직원이 일하는 분리된 작업방

09"Docker"는 선택이 아니라 안전장치에 가깝다

Docker를 어렵게 생각할 필요는 없다.

초보자식으로 말하면 Docker는 프로그램을 내 Mac 전체가 아니라 정해진 방 안에서 실행하게 만드는 도구다.

에이전트에게 파일 접근, 네트워크 접근, 명령어 실행 권한을 줄 때는 항상 조심해야 한다. 컨테이너를 쓰면 에이전트가 접근할 수 있는 범위를 줄이는 데 도움이 된다.

NanoClaw도 공식 문서에서 macOS, Linux, WSL2 환경의 Docker 샌드박스를 기본 격리 방식으로 설명하고, 추가 격리를 위해 Docker Sandboxes micro-VM이나 macOS의 Apple Container 전환을 선택지로 언급한다.

10"채널"은 메시지가 들어오는 입구다

채널은 Telegram, Discord, Slack, WhatsApp, WeChat 같은 메시징 앱을 말한다.

Telegram = 채널 Discord = 채널 Slack = 채널 WeChat = 채널 Email = 채널

처음부터 채널을 여러 개 연결하지 않는 것이 좋다. 초보자 추천 순서는 아래와 같다:

1. 하나의 테스트 채널만 연결 2. 메시지 수신 확인 3. 답장 전송 확인 4. 로그 확인 5. 재시작 후 복구 확인 6. 그다음 두 번째 채널 추가

한 번에 여러 채널을 붙이면 문제가 생겼을 때 원인을 찾기 어렵다.

11"메모리"는 RAM과 에이전트 기억 두 가지 의미가 있다

여기서 헷갈리기 쉽다.

Mac mini의 메모리는 RAM이다.

16GB 24GB 32GB 48GB 64GB

에이전트의 메모리는 사용자의 대화, 설정, 취향, 작업 방식 같은 것을 저장하는 기록이다.

사용자 프로필 대화 기록 작업 규칙 자주 쓰는 명령 스킬 설정

둘은 완전히 다르다. 정리하면 이렇다:

Mac 메모리
컴퓨터가 동시에 처리할 수 있는 작업 공간
예시
16GB, 24GB, 32GB
에이전트 메모리
에이전트가 기억하는 사용자 정보
예시
선호 설정, 작업 규칙, 대화 기록

12NanoClaw와 HermesClaw를 선택하는 기준

초보자는 아래 기준으로 선택하면 된다:

처음 시작한다
NanoClaw부터 검토
여러 메시징 앱을 붙이고 싶다
NanoClaw
Telegram, Discord, Slack 중심이다
NanoClaw
WeChat에서 Hermes와 OpenClaw를 같이 쓰고 싶다
HermesClaw
이미 Hermes Agent를 쓰고 있다
HermesClaw 검토
이미 OpenClaw를 쓰고 있다
HermesClaw 검토
구조를 단순하게 유지하고 싶다
NanoClaw
WeChat 멀티 에이전트 라우팅이 필요하다
HermesClaw

Hermes Agent 공식 GitHub README도 HermesClaw를 커뮤니티 WeChat 브리지로 소개하며, 같은 WeChat 계정에서 Hermes Agent와 OpenClaw를 실행하는 용도라고 설명한다.

13가장 단순한 NanoClaw 구조

예시 1: 입문자에게 가장 좋은 구조

Mac mini M4 └── Docker └── NanoClaw └── Telegram 개인 비서 봇

할 수 있는 일:

- 간단한 질문 답변 - 오늘 할 일 정리 - 메모 저장 - 일정 알림 - 뉴스 요약

장점:

- 구조가 단순하다 - 문제 발생 시 원인을 찾기 쉽다 - 비용과 리소스 부담이 적다

14여러 채널을 쓰는 NanoClaw 구조

예시 2: 채널을 늘리는 구조

Mac mini M4 / M4 Pro └── Docker └── NanoClaw ├── Telegram 에이전트 ├── Discord 에이전트 └── Slack 에이전트

할 수 있는 일:

- 개인 메시지는 Telegram으로 받기 - 팀 대화는 Slack에서 요약하기 - 커뮤니티 알림은 Discord로 받기

주의할 점:

- 채널이 늘어나면 로그도 늘어난다 - API 사용량이 늘어난다 - 권한 관리가 중요해진다 - 각 채널별 테스트가 필요하다

15HermesClaw 기반 WeChat 구조

예시 3: HermesClaw 기반 구조

Mac mini └── HermesClaw ├── Hermes Agent ├── OpenClaw └── OpenCode

HermesClaw 공식 구조에 따르면 HermesClaw가 iLink API와 연결되는 단일 poller 역할을 하고, OpenClaw와 Hermes에는 각각 로컬 프록시를 제공하며, OpenCode에는 ACP bridge를 제공한다.

이 구조는 처음 시작하는 사람보다는 아래 조건에 맞는 사람에게 더 적합하다:

- WeChat을 반드시 써야 한다 - Hermes Agent를 이미 사용 중이다 - OpenClaw도 같이 쓰고 싶다 - 하나의 WeChat 계정에서 여러 에이전트를 전환하고 싶다

16초보자용 추천 시작 순서

처음부터 완성형 구조를 만들려고 하면 막히기 쉽다. 추천 순서는 아래와 같다:

1. Mac mini 기본 설정 2. Homebrew / Git / Docker 준비 3. NanoClaw 또는 HermesClaw 중 하나만 선택 4. 테스트용 메시징 계정 연결 5. 간단한 메시지 송수신 확인 6. 로그 확인 방법 익히기 7. Mac 재부팅 후 다시 실행 확인 8. 자동 실행 설정 9. 보안 설정 10. 실전 자동화 하나 추가

처음 목표는 "멋진 봇 만들기"가 아니다. 처음 목표는 이것이다:

내 Mac mini에서 에이전트가 켜진다. 메시지를 받는다. 답장을 보낸다. 에러 로그를 확인할 수 있다. 재부팅 후에도 다시 살릴 수 있다.

이 상태가 되면 그다음부터는 기능을 하나씩 붙이면 된다.

17꿀팁 1: 처음에는 한 채널만 붙인다

여러 채널을 동시에 붙이면 문제가 생겼을 때 원인을 찾기 어렵다. 처음에는 아래처럼 단순하게 간다:

Mac mini → NanoClaw → Telegram 테스트 봇

이 구조가 안정되면 그다음 Slack, Discord, WhatsApp, WeChat 같은 채널을 추가한다.

18꿀팁 2: 에이전트 이름을 용도별로 나눈다

처음부터 "만능봇"을 만들면 관리가 어려워진다. 예를 들면 이렇게 나누는 편이 좋다:

personal-assistant trading-alert work-summary test-bot

이렇게 나누면 로그를 볼 때도 쉽고, 문제가 생겼을 때 어떤 에이전트가 문제인지 바로 찾을 수 있다.

19꿀팁 3: 실사용 계정과 테스트 계정을 분리한다

초보자는 반드시 테스트 계정부터 써야 한다.

테스트용 Telegram 봇 테스트용 Discord 서버 테스트용 WeChat 계정 테스트용 API 키

테스트가 끝난 뒤 실사용 계정으로 옮기는 것이 안전하다.

20꿀팁 4: "답장이 온다"와 "안전하게 운영된다"는 다르다

초보자는 답장만 오면 성공했다고 생각하기 쉽다. 하지만 실전에서는 아래까지 확인해야 한다:

- 로그가 정상적으로 남는가? - 에러가 반복되지 않는가? - API 키가 노출되지 않았는가? - 재부팅 후 다시 실행되는가? - 외부 포트가 불필요하게 열려 있지 않은가? - 예상하지 못한 명령을 실행하지 않는가?

21꿀팁 5: M5를 기다리더라도 설치 구조는 먼저 익혀도 된다

M5 Mac mini를 기다리는 경우에도 설치 구조 자체는 M4 기준으로 먼저 익혀둘 수 있다.

NanoClaw와 HermesClaw 운영에서 중요한 기본 흐름은 칩이 바뀌어도 크게 달라지지 않는다:

터미널 사용 Git 사용 Docker 실행 환경 변수 설정 API 키 관리 로그 확인 자동 실행 보안 설정

M5가 공식 출시되면 바뀔 수 있는 것은 주로 성능, 메모리 옵션, 포트 구성, 가격, 발열, 전력 효율 같은 하드웨어 조건이다. 설치 흐름 자체는 공식 저장소가 변경되지 않는 한 대부분 비슷하게 유지될 가능성이 높다.

섹션 2 · 핵심 정리

이 단원의 핵심 정리

NanoClaw
여러 메시징 앱에 연결하기 좋은 개인 AI 에이전트 환경
HermesClaw
WeChat에서 Hermes / OpenClaw / OpenCode를 함께 쓰기 위한 브리지
Mac mini
24시간 켜둘 수 있는 개인 AI 서버 역할
Docker
에이전트를 분리된 공간에서 실행하는 안전장치
채널
Telegram, Discord, Slack, WeChat 같은 메시지 입구
AI 모델
답변을 만드는 두뇌
에이전트
메시지를 받고 작업을 처리하는 실행 담당자

초보자가 기억해야 할 가장 중요한 문장은 이것이다:

처음에는 하나의 Mac mini, 하나의 도구, 하나의 메시징 채널만 연결한다. 그다음 정상 작동, 로그, 재부팅 복구, 보안까지 확인한 뒤 기능을 늘린다.

3. Mac mini 선택 가이드

01클라우드 중심과 로컬 LLM의 갈림길

Mac mini를 AI 에이전트 서버로 쓸 때 가장 먼저 구분해야 할 것이 있습니다.

바로 클라우드 AI provider 운영과 로컬 LLM 운영이라는 근본적인 차이입니다. 이 둘은 필요한 사양이 완전히 다릅니다.

NanoClaw나 HermesClaw를 설치해서 Telegram, Discord, WhatsApp, WeChat과 연결하고, 실제 추론은 Claude, Gemini, OpenAI, OpenRouter 같은 외부 provider에 맡기는 구조라면, Mac mini가 거대한 AI 모델을 직접 돌리는 것은 아닙니다.

02클라우드 중심일 때 Mac mini의 역할

클라우드 provider를 중심으로 쓸 때 Mac mini가 주로 하는 일은 다음과 같습니다:

이 정도라면 CPU나 GPU보다 중요한 것은 "적당한 메모리", "충분한 저장공간", "안정적인 네트워크"입니다.

03로컬 LLM을 돌릴 때의 사양 변화

반대로 Mac mini 안에 Gemma, Qwen, Llama, Mistral 같은 로컬 LLM을 직접 설치하고, Ollama, LM Studio, llama.cpp, MLX 같은 런타임으로 모델을 계속 돌릴 생각이라면 이야기가 달라집니다.

이때부터는 메모리와 메모리 대역폭이 훨씬 중요해집니다.

핵심 원칙

사양 판단의 가장 큰 기준은 "로컬 LLM을 돌릴 것인가"입니다.

04메모리 판단 가이드 요약

당신의 사용 패턴에 따라 필요한 메모리가 결정됩니다:

NanoClaw/HermesClaw + 외부 provider
16GB도 가능, 24GB면 실사용 안정적
여러 에이전트 + Docker + IDE
24GB부터 현실적, 32GB가 더 편함
로컬 LLM 직접 실행
32GB부터 시작, 48GB 이상 권장
로컬 LLM 상시 운영
48GB 또는 64GB 이상 권장

05가격이 사양 선택을 좌우한다

Mac mini 선택에서 가격은 매우 중요합니다. 그 이유는 단순합니다: Mac mini는 구매 후 메모리를 쉽게 업그레이드할 수 없고, Apple의 업그레이드 비용이 가파르기 때문입니다.

16GB에서 24GB, 24GB에서 32GB, M4에서 M4 Pro, SSD 512GB에서 1TB 비용이 모두 누적됩니다.

가격 판단의 핵심: 사양표가 아니라 추가 비용 대비 체감 이득으로 봐야 합니다.

06가격 판단 5가지 원칙

원칙 1
NanoClaw/HermesClaw만 쓸 거라면 Pro 칩보다 메모리와 SSD가 먼저
원칙 2
16GB→24GB 비용은 실사용 안정성 비용으로 봄
원칙 3
24GB→32GB 비용은 장기 사용 비용으로 봄
원칙 4
Pro로 넘어가는 비용은 로컬 LLM, 고속 외장 SSD, 다중 Docker가 있을 때만 의미 있음
원칙 5
내부 SSD 대용량보다 1TB 내부 + 외장 SSD 조합이 더 현실적

07가격 판단 카테고리 5가지

가성비
필요한 작업을 무리 없이 하는 가장 싼 구성
실사용 안정성
2년 이상 쓰면서 swap과 저장공간 부족을 덜 겪는 구성
장기 운영
여러 에이전트, Docker, 로컬 LLM 실험까지 버티는 구성
과소비
실제 사용량은 가벼운데 Pro 칩과 대용량 메모리를 먼저 사는 경우
부족한 구성
처음에는 싸지만 6개월 뒤 메모리나 SSD 때문에 다시 사고 싶어지는 경우

08NanoClaw/HermesClaw 부담도 현실적으로 보기

중요한 점은 NanoClaw와 HermesClaw 자체가 거대한 로컬 LLM은 아니라는 것입니다. 이들은 메시징 앱과 연결되고, 에이전트를 컨테이너 안에서 실행하며, 외부 AI provider를 호출하는 구조에 가깝습니다.

따라서 NanoClaw/HermesClaw만 기준으로 보면 Mac mini의 부담은 대체로 가벼운 쪽에 가깝습니다:

09NanoClaw 기준 메모리 판단

단순히 "NanoClaw를 쓴다"는 이유만으로 48GB나 64GB를 고를 필요는 없습니다. 초보자 기준으로는 이렇게 판단하면 됩니다:

NanoClaw 하나 + Telegram/Discord 하나
16GB 가능
NanoClaw 실사용 + Docker + CLI 도구
24GB 권장
NanoClaw + HermesClaw + 자동화
32GB 권장
여러 에이전트 + 로컬 LLM 실험
48GB 이상 권장
로컬 LLM 상시 운영
64GB 이상 고려

10로컬 LLM을 돌릴 생각이 있는지 먼저 결정

Mac mini 사양을 고를 때 가장 큰 분기점은 이것입니다:

나는 AI 모델을 클라우드 provider로만 쓸 것인가? 아니면 Mac mini 안에 로컬 LLM을 직접 설치해 돌릴 것인가?

클라우드 provider 중심이라면 Mac mini는 "AI 실행기"라기보다 "에이전트 운영 장비"입니다. 이 경우 16GB 또는 24GB로도 충분히 시작할 수 있습니다.

하지만 로컬 LLM을 직접 설치하면 Mac mini가 모델 가중치, 런타임, KV cache, 프롬프트 컨텍스트, Docker, 에이전트 프로세스를 모두 감당해야 합니다. 이때부터 메모리 판단이 달라집니다.

11로컬 LLM에서 메모리를 먹는 5가지 요소

모델 크기
12B, 26B, 31B처럼 파라미터가 커질수록 메모리 사용량 증가
양자화
BF16보다 8-bit, 4-bit 모델이 훨씬 적은 메모리 사용
컨텍스트 길이
긴 문서나 대화를 넣을수록 KV cache 증가
동시 실행
로컬 LLM 하나만 돌리는지, NanoClaw/Docker/IDE와 함께 돌리는지에 따라 여유 메모리 변화
런타임
Ollama, LM Studio, llama.cpp, MLX 등 어떤 환경을 쓰는지에 따라 메모리 사용량 변화

로컬 LLM은 "모델 파일이 7GB니까 8GB 메모리면 되겠지"라고 계산하면 안 됩니다. 실제로는 런타임, 컨텍스트, 시스템 메모리, 다른 앱이 모두 같이 올라갑니다.

12Gemma 4 기준 메모리 판단 (1/2)

Gemma 4는 Mac mini 선택 가이드에서 좋은 기준점입니다. 비교적 최신이고 작은 모델부터 중간급까지 선택지가 있기 때문입니다.

초보자 입장에서 이렇게 이해하면 됩니다:

Gemma 4 E2B / E4B
작고 가벼운 모델. 16GB Mac에서도 실험 가능
Gemma 4 12B
중간급 모델. 4-bit 양자화 기준으로 16GB에서도 가능하지만, 실사용은 24GB 이상 편함
Gemma 4 26B A4B
MoE 모델. 전체 모델을 메모리에 올려야 하므로 32GB 이상부터 현실적
Gemma 4 31B
Dense 모델. 4-bit 기준으로도 여유 있게 쓰려면 48GB 이상이 안전

13Gemma 4 기준 메모리 판단 (2/2) — 메모리별 호환성 표

이 표는 "모델 하나만 실행할 때"가 아니라 NanoClaw/HermesClaw, Docker, 브라우저, 터미널, 로그, 자동화 서버를 함께 쓰는 상황을 기준으로 보수적으로 잡은 것입니다.

Gemma 4 E2B
16GB: 가능 | 24GB: 여유 | 32GB+: 여유
Gemma 4 E4B
16GB: 가능 | 24GB: 여유 | 32GB+: 여유
Gemma 4 12B Q4
16GB: 빠듯 | 24GB: 현실적 | 32GB+: 여유
Gemma 4 26B A4B Q4
16GB: 비추천 | 24GB: 빠듯 | 32GB: 가능 | 48GB: 권장
Gemma 4 31B Q4
16GB: 비추천 | 24GB: 비추천 | 32GB: 빠듯 | 48GB: 권장
70B급 Q4
16~32GB: 비추천 | 48GB: 실험 가능 | 64GB: 권장

14로컬 LLM 메모리 판단 최종 기준

로컬 LLM을 생각한다면 결론은 이렇게 됩니다:

가벼운 로컬 LLM 실험
24GB도 가능
Gemma 4 12B급을 편하게 사용
32GB 권장
26B~31B급 모델을 자주 사용
48GB 권장
로컬 LLM을 상시 운영
64GB 이상 고려

1516GB 메모리: 가장 싼 시작 (1/3)

장점:

단점:

16GB는 나쁜 선택이 아닙니다. 다만 "싸게 시작하는 선택"이지 "오래 버티는 선택"은 아닙니다.

1624GB 메모리: 가장 현실적인 선택 (2/3)

장점:

단점:

24GB는 초보자에게 가장 현실적인 기준선입니다. 16GB 대비 추가 비용이 감당 가능하다면 가장 먼저 올릴 옵션입니다.

1732GB 메모리: 후회 방지 (3/3)

장점:

단점:

32GB는 "가성비"보다 "후회 방지"에 가깝습니다. 2년 이상 쓸 장비라면 24GB보다 32GB가 후회가 적습니다.

1848GB와 64GB 이상: 본격 운영형

48GB의 장점: 여러 에이전트, Docker, 개발 자동화, 로컬 LLM 실험에 적합 | Gemma 4 26B A4B 또는 31B Q4급을 훨씬 현실적으로 처리 | 장시간 운영에서 swap 부담 감소

48GB의 단점: NanoClaw/HermesClaw만 쓸 사람에게는 과함 | 로컬 LLM을 안 할 거면 비용 대비 체감이 작을 수 있음

64GB 이상: 로컬 LLM 상시 운영, 31B급 이상 모델, 긴 컨텍스트, 벡터 DB, 여러 에이전트를 함께 다루기 좋음 | 하지만 초보자 단일 에이전트 용도에는 명백히 과함

64GB 이상은 초보자 추천이 아니라 로컬 AI 서버 추천입니다.

19M4/M5 기본형이 맞는 경우

추천 사용자:

추천 구성:

최저 예산
16GB / 512GB
실사용 추천
24GB / 1TB
장기 사용
32GB / 1TB

이 사용자에게는 Pro 칩보다 메모리와 저장공간이 먼저입니다.

20M4 Pro / M5 Pro가 맞는 경우

추천 사용자:

추천 구성:

Pro 입문
24GB / 512GB 또는 1TB
본격 운영
48GB / 1TB
로컬 LLM 중심
64GB 이상 / 2TB

주의: Pro 24GB는 CPU/GPU와 포트가 좋아지는 선택이지, 메모리 여유가 크게 늘어나는 선택은 아닙니다. 순수하게 NanoClaw/HermesClaw와 Docker 중심이라면, Pro 24GB보다 기본 칩 32GB가 더 실용적일 수 있습니다.

21사용 목적별 최종 판단표

당신의 사용 목적을 찾아 권장 구성을 확인하세요:

설치 연습
16GB / 512GB | 가장 싼 구성으로 충분
NanoClaw 단일 봇
16~24GB / 512GB | 24GB 추가금이 부담 없으면 24GB
개인 비서형 에이전트
24GB / 1TB | 가장 균형 좋음
Claude Code + Codex + Gemini CLI
24~32GB / 1TB | 장기 사용이면 32GB
NanoClaw + HermesClaw 병행
32GB / 1TB | Pro보다 메모리 우선
개발 자동화 + Docker 다수
32~48GB / 1TB | Docker 수가 많으면 48GB
Gemma 4 12B급 로컬 LLM
24GB 가능, 32GB 권장 | 편하게 쓰려면 32GB
Gemma 4 26B/31B급 실험
48GB 권장 | 여기부터 Pro 고려
로컬 LLM 상시 운영
64GB 이상 | Mac Studio/클라우드 GPU와 비교 필요

22초보자 4가지 현실적인 추천 (1/2)

가장 싸게 시작하고 싶은 사람:

구성

16GB / 512GB

조건: NanoClaw 하나만 테스트, 메시징 앱 하나만 연결, 로컬 LLM 거의 안 함, Docker도 가볍게. 주의: 장기 운영용으로는 부족할 수 있음

대부분의 초보자:

구성

24GB / 1TB

이유: NanoClaw/HermesClaw 실사용에 충분, Docker와 CLI 도구 병행 가능, 저장공간 부족 가능성 감소, 로컬 LLM도 작은 모델이나 12B급 정도는 실험 가능. 결론: 가장 무난한 실사용 구성

23초보자 4가지 현실적인 추천 (2/2)

오래 쓸 사람:

구성

32GB / 1TB

이유: 24GB보다 장기 안정성 좋음, 브라우저/IDE/Docker/에이전트 동시 사용 유리, Gemma 4 12B급 로컬 모델 더 편하게 처리, 2년 이상이면 후회 적음

로컬 LLM까지 진지하게 할 사람:

구성

48GB 이상 / 1TB 또는 2TB

이유: 26B~31B급 모델 실험 가능, 벡터 DB와 로컬 검색 병행 가능, 여러 에이전트와 Docker 동시 운영 가능. 결론: 이때부터 Pro 모델을 진지하게 검토

로컬 AI 서버를 만들 사람:

구성

64GB 이상 / 2TB 이상

주의: 이 가격대부터는 Mac mini만 보지 말고 Mac Studio, 클라우드 GPU, 별도 Linux 서버와 비교해야 함

24M5 출시 전후 구매 판단

M5 Mac mini가 공식 출시되기 전이라면 단정해서 쓰면 안 되지만, 출시가 매우 임박하다면 이렇게 판단합니다:

출시 전
M5 공식 발표 후 가격, 메모리 옵션, SSD 옵션, 포트 구성을 확인 후 최종 판단
출시 직후
M4 할인폭과 M5 기본 가격 비교가 핵심

구체적 판단:

M4 할인이 크다
M4 / 24GB 또는 32GB도 충분히 좋은 선택
가격 차이가 작다
M5 / 24GB 또는 32GB 우선 검토
로컬 LLM을 생각한다
M5 Pro / 48GB 이상 검토
NanoClaw/HermesClaw만 쓴다
M5 Pro까지 갈 필요 없음
장기 로컬 AI 서버
M5 Pro / 64GB 이상 또는 Mac Studio 비교

25칩 선택 최종 가이드

M5가 나왔다고 해서 모든 사람이 M5 Pro를 사야 하는 것은 아닙니다. 중요한 것은 칩 이름이 아니라 내가 돌릴 작업입니다:

메시징 에이전트 중심
기본 M4/M5 + 24GB 또는 32GB
로컬 LLM 실험
기본 M4/M5 32GB 또는 Pro 48GB
로컬 LLM 상시 운영
Pro 64GB 이상

26이 단원의 핵심 정리

Mac mini 선택에서 가장 큰 실수는 두 가지입니다:

최종 결론:

NanoClaw/HermesClaw만
16GB 가능, 24GB 권장
초보자 실사용
24GB / 1TB
오래 쓸 개인 AI 에이전트 서버
32GB / 1TB
로컬 LLM 실험
48GB 이상
로컬 LLM 상시 운영
64GB 이상

27가격으로 보는 최종 판단

가격까지 넣으면 결론은 더 명확합니다:

가장 싼 선택
16GB
가장 현실적인 선택
24GB
가장 후회가 적은 기본형
32GB
본격 AI 서버
48GB
로컬 LLM 장기 운영
64GB 이상
NanoClaw/HermesClaw는 생각보다 무겁지 않다. 비싼 메모리가 필요한 순간은 로컬 LLM, 여러 Docker, 벡터 DB, 개발 자동화가 함께 올라갈 때다.

4. 설치 전 준비물

01이 단원에서 하는 일

설치 전에 아래 네 가지를 먼저 정리합니다.

1
Mac mini 기본 상태 확인
2
필수 프로그램 확인
3
Claude / Codex / Gemini 계정 준비
4
API 키와 백업 폴더 준비

초보자는 설치 명령어부터 치기 쉽습니다. 하지만 준비 없이 설치하면 대부분 아래에서 막힙니다.

Docker가 안 켜짐 · Git이 없음 · Node 버전이 낮음 · pnpm이 없음 · Claude / Codex / Gemini 로그인이 꼬임 · API 키가 어디 들어갔는지 모름 · .env 파일을 덮어씀 · 설치 실패 후 원래 상태로 못 돌림

이 단원에서는 실제 설치 전에 내 Mac mini가 설치 가능한 상태인지 확인합니다.

02전체 준비물 요약

필수 준비물

장비

기본 프로그램

AI 도구

계정

보안 준비

NanoClaw는 공식 README에서 nanoclaw.sh가 Node, pnpm, Docker가 없으면 설치하고, Anthropic credential 등록과 첫 채널 페어링까지 안내한다고 설명합니다. 그래도 초보자는 자동 설치에만 맡기지 말고 설치 전 상태를 직접 확인하는 편이 안전합니다.

03Mac mini 기본 상태 확인

터미널을 열고 아래 명령어를 입력합니다.

sw_vers

확인할 것: ProductName · ProductVersion · BuildVersion

Apple Silicon 여부 확인:

uname -m

결과가 아래처럼 나오면 Apple Silicon입니다.

arm64

디스크 여유 공간 확인:

df -h

메모리 확인:

system_profiler SPHardwareDataType | grep "Memory"

칩 확인:

system_profiler SPHardwareDataType | grep "Chip"

실전 기준

디스크 여유 공간
최소 50GB 이상 권장
메모리
16GB 가능 · 24GB 이상 권장 · 32GB 이상이면 여유로움
네트워크
Wi-Fi보다 유선 LAN 권장

Docker Desktop은 macOS의 현재 버전과 이전 두 개 주요 버전을 지원하고, 최소 4GB RAM을 요구합니다. Apple Silicon Mac에서는 일부 선택적 명령줄 도구 때문에 Rosetta 2 설치가 권장될 수 있습니다.

04작업 폴더 만들기

AI 에이전트 관련 파일은 한 곳에 모아두는 것이 좋습니다.

추천 구조:

$ mkdir -p ~/ai-agents $ mkdir -p ~/ai-agents/backups $ mkdir -p ~/ai-agents/logs $ mkdir -p ~/ai-agents/projects $ mkdir -p ~/ai-agents/secrets

이동:

$ cd ~/ai-agents

폴더 구조:

~/ai-agents ├── backups ├── logs ├── projects └── secrets

각 폴더 용도

backups
설정 파일 백업
logs
에러 로그, 실행 로그
projects
NanoClaw, HermesClaw, 테스트 프로젝트
secrets
API 키 메모, .env 샘플, 인증 관련 기록

실전 팁

05터미널 기본 사용법

초보자가 반드시 알아야 하는 명령어만 정리합니다.

현재 위치 확인

pwd

폴더 안 파일 보기

ls

자세히 보기:

ls -la

폴더 이동

cd ~/ai-agents

상위 폴더로 이동

cd ..

파일 내용 보기

cat 파일명

파일 편집

nano 파일명

nano 저장 방법

저장
Control + O
확인
Enter
나가기
Control + X

실행 중인 명령 중단

Control + C

이전 명령 다시 보기

방향키 ↑

06Homebrew 설치 확인

Homebrew는 macOS에서 터미널 프로그램을 설치할 때 자주 쓰는 패키지 관리자입니다. 공식 설명 기준으로 Homebrew는 Apple이 기본 제공하지 않는 필요한 소프트웨어를 설치하는 도구이며, Apple Silicon Mac에서는 /opt/homebrew 아래에 설치됩니다.

확인:

brew --version

설치되어 있으면 이런 식으로 나옵니다:

Homebrew 5.x.x

설치 위치 확인:

which brew

Apple Silicon Mac에서는 보통 이렇게 나옵니다:

/opt/homebrew/bin/brew

설치되어 있지 않다면 Homebrew 공식 페이지의 최신 설치 명령어를 확인해서 설치합니다.

설치 후 업데이트:

brew update

진단:

brew doctor

실전 팁

07Git 설치 확인

Git은 GitHub 저장소를 내려받고, 설정 변경 내역을 관리하는 도구입니다. Git 공식 사이트는 Git을 작은 프로젝트부터 큰 프로젝트까지 빠르고 효율적으로 다루는 무료 오픈소스 분산 버전 관리 시스템이라고 설명합니다.

확인:

git --version

설치되어 있지 않으면 Homebrew로 설치합니다:

brew install git

설치 후 다시 확인:

git --version

Git 사용자 이름 설정:

git config --global user.name "YOUR_NAME"

Git 이메일 설정:

git config --global user.email "[email protected]"

설정 확인:

git config --global --list

실전 팁

08Node.js / npm 확인

NanoClaw, Claude Code, Codex CLI, Gemini CLI는 Node.js 또는 npm 기반 설치를 사용하는 경우가 많습니다. Node.js는 서버, 웹 앱, 명령줄 도구, 스크립트를 만들 수 있는 무료 오픈소스 크로스플랫폼 JavaScript 런타임입니다.

확인:

node -v npm -v

설치되어 있지 않으면 Homebrew로 설치합니다:

brew install node

설치 후 확인:

node -v npm -v

Claude Code의 npm 설치 방식은 Node.js 18 이상을 요구하며, 공식 문서는 sudo npm install -g를 권장하지 않습니다. 권한 문제와 보안 위험이 생길 수 있기 때문입니다.

실전 팁

09pnpm 확인

NanoClaw 쪽 설치나 개발 환경에서 pnpm이 필요할 수 있습니다. NanoClaw 공식 README는 nanoclaw.sh가 pnpm이 없으면 설치한다고 설명하지만, 설치 전 직접 확인하는 편이 좋습니다.

확인:

pnpm -v

없으면 설치:

npm install -g pnpm

다시 확인:

pnpm -v

실전 팁

10Docker Desktop 설치 확인

NanoClaw는 컨테이너 격리를 중요한 구조로 사용합니다. 공식 사이트는 NanoClaw 에이전트가 Docker 샌드박스에서 실행되고, 각 agent group이 자기 컨테이너와 메모리, 마운트 범위를 가진다고 설명합니다.

Docker 확인:

docker --version

Docker Compose 확인:

docker compose version

Docker 실행 상태 확인:

docker info

정상이라면 Docker 서버 정보가 나옵니다. 아래처럼 나오면 Docker Desktop이 켜져 있지 않은 것입니다:

Cannot connect to the Docker daemon

이 경우:

  1. Applications 폴더에서 Docker 실행
  2. 상단 메뉴바에 Docker 아이콘 확인
  3. Docker Desktop이 완전히 켜진 뒤 다시 docker info 실행

Docker Desktop 공식 문서는 Mac에서 Docker Desktop을 설치한 뒤 /Applications/Docker.app을 실행하라고 안내합니다.

실전 팁

11Python 3 / pip3 확인

HermesClaw는 Python 기반 파일을 포함하고, 공식 설치 과정에서 requests, python-dotenv 같은 Python 의존성을 설치한다고 설명합니다.

확인:

python3 --version pip3 --version

설치되어 있지 않으면 Homebrew로 설치합니다:

brew install python

다시 확인:

python3 --version pip3 --version

실전 팁

12Claude Code 준비

Claude Code는 터미널에서 Claude를 사용하는 도구입니다. 공식 문서 기준으로 npm 설치 방식은 아래 명령어를 사용합니다.

npm install -g @anthropic-ai/claude-code

설치 확인:

claude --version

실행:

claude

Claude 계정 로그인 후 확인할 것:

환경 변수 확인:

env | grep ANTHROPIC

ANTHROPIC_API_KEY가 잡혀 있으면 구독 로그인 대신 API 키 방식으로 동작할 수 있으므로, 구독 기반 운영을 원한다면 반드시 확인합니다.

현재 터미널에서만 제거:

unset ANTHROPIC_API_KEY

13OpenAI Codex CLI 준비

Codex CLI는 OpenAI의 로컬 터미널용 코딩 에이전트입니다. 공식 GitHub README는 Mac 또는 Linux에서 설치 스크립트를 사용할 수 있고, npm 또는 Homebrew로도 설치할 수 있다고 안내합니다. 또한 codex를 실행해 ChatGPT 계정으로 로그인하면 Plus, Pro, Business, Edu, Enterprise 플랜 범위에서 사용할 수 있다고 설명합니다.

설치 방식 예시:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

npm 방식:

npm install -g @openai/codex

Homebrew 방식:

brew install --cask codex

설치 확인:

codex --version

실행:

codex

로그인 시 확인할 것:

보안 주의

최근 Codex나 Gemini CLI를 사칭하는 비공식 패키지·도구 사례가 보고되었습니다. Codex는 공식 OpenAI GitHub 또는 공식 문서에 있는 설치 경로만 사용하고, Gemini CLI도 공식 google-gemini/gemini-cli 저장소나 공식 문서에 있는 패키명만 사용합니다.

14Gemini CLI 준비

Gemini CLI는 Gemini를 터미널에서 사용하는 오픈소스 AI 에이전트입니다. 공식 GitHub README는 npx @google/gemini-cli, npm install -g @google/gemini-cli, brew install gemini-cli 설치 방식을 안내합니다.

즉시 실행:

npx @google/gemini-cli

npm 전역 설치:

npm install -g @google/gemini-cli

Homebrew 설치:

brew install gemini-cli

실행:

gemini

인증 방식은 크게 세 가지입니다.

  1. Google 계정 로그인
  2. Gemini API Key
  3. Vertex AI

공식 README는 Google 계정 로그인 방식이 개인 개발자나 Gemini Code Assist 라이선스 사용자에게 적합하고, API Key 방식은 특정 모델 제어나 유료 티어 접근이 필요한 개발자에게 적합하다고 설명합니다.

Gemini CLI 사용량은 Gemini Code Assist agent mode와 합산됩니다. Google 공식 quota 문서는 개인용 1,000 requests/user/day, Google AI Pro 1,500 requests/user/day, Google AI Ultra 2,000 requests/user/day를 표시하고 있습니다. 또한 개인용·Google AI Pro·Google AI Ultra 사용자는 2026년 6월 18일부터 Gemini CLI가 Gemini Code Assist 요청 처리를 중단할 예정이라고 안내합니다.

실전 팁

15NanoClaw 준비

NanoClaw는 개인 AI 에이전트를 컨테이너 안에서 실행하는 구조입니다. 공식 사이트는 WhatsApp, Telegram, Discord, Slack, Microsoft Teams, iMessage, Matrix, Google Chat, Webex, Linear, GitHub, WeChat, email 같은 여러 채널을 지원하며, 채널과 provider를 필요할 때 추가하는 방식이라고 설명합니다.

NanoClaw 설치 전 확인할 것:

공식 Quick Start는 아래 흐름입니다. 실제 설치는 6단원에서 다룹니다.

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2 cd nanoclaw-v2 bash nanoclaw.sh

NanoClaw 공식 README는 nanoclaw.sh가 fresh machine에서 named agent와 첫 메시징 채널까지 안내한다고 설명합니다.

설치 전 에이전트에게 줄 문장

NanoClaw 설치 전 내 Mac 상태를 점검해줘.

확인할 항목:

정확히 확인할 수 없는 항목은 UNKNOWN으로 표시하고, 설치 전에 해결해야 할 문제만 따로 정리해줘.

16HermesClaw 준비

HermesClaw는 Hermes Agent, OpenClaw, OpenCode를 같은 WeChat 계정에서 함께 쓰기 위한 브리지입니다. 공식 README는 /hermes, /openclaw, /opencode, /both, /three 명령으로 에이전트를 전환할 수 있다고 설명합니다.

설치 전 필수 조건:

아래 중 최소 하나가 필요합니다.

  1. OpenClaw + clawbot(openclaw-weixin)
  2. Hermes Agent + WeChat gateway

공식 README도 HermesClaw 설치 전 OpenClaw clawbot 또는 Hermes WeChat gateway 중 하나가 설치·설정되어 있어야 한다고 설명합니다.

중요한 주의점:

HermesClaw 공식 설치 설명은 systemd service 설정을 포함합니다. Mac mini의 macOS 자동 실행은 later 단원에서 launchd 기준으로 따로 다룹니다. 따라서 Mac mini에서는 설치 스크립트를 무작정 실행하기 전에 README와 install.sh를 먼저 읽어야 합니다.

공식 설치 스크립트는 gateway 감지, iLink token 추출, OpenClaw와 Hermes의 base URL 패치, Python dependency 설치, systemd service 설정을 수행한다고 설명되어 있습니다.

설치 전 에이전트에게 줄 문장

HermesClaw 설치 전 상태를 점검해줘.

확인할 항목:

정확히 확인되지 않는 내용은 추측하지 말고 UNKNOWN으로 표시해줘.

17메시징 계정 준비

처음부터 실사용 계정을 붙이지 않습니다.

추천 순서:

  1. 테스트용 Telegram 봇
  2. 테스트용 Discord 서버
  3. 테스트용 Slack 워크스페이스
  4. 실사용 메시징 앱
  5. WeChat / WhatsApp 같은 민감한 계정

처음 연결할 채널은 하나만 고릅니다.

추천:

Telegram 또는 Discord

이유:

피해야 할 것:

18API 키와 구독 로그인 준비

이 가이드에서는 세 가지 사용 방식을 구분합니다.

1
구독 로그인 방식
2
API 키 방식
3
구독 + API fallback 방식

구독 로그인 방식

Claude Code
Claude 계정 로그인
Codex
ChatGPT 계정 로그인
Gemini CLI
Google 계정 로그인

API 키 방식

Claude
ANTHROPIC_API_KEY
OpenAI
OPENAI_API_KEY
Gemini
GEMINI_API_KEY 또는 GOOGLE_API_KEY

환경 변수 확인:

env | grep -E "ANTHROPIC|OPENAI|GEMINI|GOOGLE"

.env 파일 샘플:

cd ~/ai-agents/secrets nano .env.example

예시:

# Claude ANTHROPIC_API_KEY= # OpenAI OPENAI_API_KEY= # Gemini GEMINI_API_KEY= # Google Cloud / Vertex AI GOOGLE_API_KEY= GOOGLE_CLOUD_PROJECT= GOOGLE_GENAI_USE_VERTEXAI=

실전 팁

19.gitignore 먼저 만들기

설치 전에 민감한 파일이 Git에 올라가지 않도록 .gitignore를 먼저 만듭니다.

cd ~/ai-agents nano .gitignore

내용:

# Secrets .env .env.* *.key *.pem *.token secrets/ credentials/ auth/ # Logs logs/ *.log # macOS .DS_Store # Node node_modules/ # Python .venv/ __pycache__/ *.pyc # Docker *.pid # Backups backups/

실전 팁

20백업 준비

설치 전 백업 폴더를 만듭니다.

mkdir -p ~/ai-agents/backups/pre-install

현재 환경 기록:

{ echo "DATE: $(date)" echo "macOS:" sw_vers echo "" echo "ARCH:" uname -m echo "" echo "BREW:" brew --version 2>/dev/null || echo "brew not installed" echo "" echo "GIT:" git --version 2>/dev/null || echo "git not installed" echo "" echo "NODE:" node -v 2>/dev/null || echo "node not installed" echo "" echo "NPM:" npm -v 2>/dev/null || echo "npm not installed" echo "" echo "PNPM:" pnpm -v 2>/dev/null || echo "pnpm not installed" echo "" echo "DOCKER:" docker --version 2>/dev/null || echo "docker not installed" echo "" echo "PYTHON:" python3 --version 2>/dev/null || echo "python3 not installed" echo "" echo "CLAUDE:" claude --version 2>/dev/null || echo "claude not installed" echo "" echo "CODEX:" codex --version 2>/dev/null || echo "codex not installed" echo "" echo "GEMINI:" gemini --version 2>/dev/null || echo "gemini not installed" } > ~/ai-agents/backups/pre-install/environment.txt

확인:

cat ~/ai-agents/backups/pre-install/environment.txt

실전 팁

21설치 전 전체 점검 명령어

아래 명령어를 한 번에 실행하면 기본 상태를 빠르게 확인할 수 있습니다.

echo "=== macOS ===" sw_vers echo "\n=== Architecture ===" uname -m echo "\n=== Disk ===" df -h / echo "\n=== Homebrew ===" brew --version 2>/dev/null || echo "Homebrew not installed" echo "\n=== Git ===" git --version 2>/dev/null || echo "Git not installed" echo "\n=== Node ===" node -v 2>/dev/null || echo "Node not installed" echo "\n=== npm ===" npm -v 2>/dev/null || echo "npm not installed" echo "\n=== pnpm ===" pnpm -v 2>/dev/null || echo "pnpm not installed" echo "\n=== Docker ===" docker --version 2>/dev/null || echo "Docker not installed" docker compose version 2>/dev/null || echo "Docker Compose not available" echo "\n=== Python ===" python3 --version 2>/dev/null || echo "Python3 not installed" pip3 --version 2>/dev/null || echo "pip3 not installed" echo "\n=== AI CLIs ===" claude --version 2>/dev/null || echo "Claude Code not installed" codex --version 2>/dev/null || echo "Codex CLI not installed" gemini --version 2>/dev/null || echo "Gemini CLI not installed" echo "\n=== AI ENV KEYS ===" env | grep -E "ANTHROPIC|OPENAI|GEMINI|GOOGLE" || echo "No AI env vars found"

22설치 전 에이전트에게 시킬 최종 점검 프롬프트

아래 문장을 Claude Code, Codex, Gemini CLI 중 하나에 넣어도 됩니다.

나는 Mac mini에서 NanoClaw 또는 HermesClaw를 설치하려고 한다.

설치 전 준비 상태를 점검해줘.

아래 항목을 기준으로 확인한다:

  1. macOS 버전
  2. Apple Silicon 여부
  3. 디스크 여유 공간
  4. Homebrew 설치 여부
  5. Git 설치 여부
  6. Node.js / npm 설치 여부
  7. pnpm 설치 여부
  8. Docker Desktop 설치 및 실행 여부
  9. Python3 / pip3 설치 여부
  10. Claude Code 설치 여부
  11. Codex CLI 설치 여부
  12. Gemini CLI 설치 여부
  13. ANTHROPIC / OPENAI / GEMINI / GOOGLE 환경 변수 존재 여부
  14. ~/ai-agents 폴더 구조 존재 여부
  15. 백업 폴더 존재 여부
  16. .gitignore 존재 여부

정확히 확인할 수 없는 항목은 UNKNOWN으로 표시해라. 추측하지 마라.

출력 형식:

## 설치 전 점검 결과

### 통과
-

### 확인 필요
-

### 설치 전 반드시 해결
-

### 추천 다음 단계
-

23초보자가 자주 하는 실수 (1/5)

실수 1. Docker를 설치만 하고 실행하지 않음

docker --version은 나오는데 docker info는 실패하는 경우가 있습니다. 이건 Docker가 설치는 되었지만 실행 중이 아닐 가능성이 높습니다.

확인:

docker info

실수 2. API 키와 구독 로그인을 섞음

확인:

env | grep -E "ANTHROPIC|OPENAI|GEMINI|GOOGLE"

24초보자가 자주 하는 실수 (2/5)

실수 3. 설치 명령어를 아무 블로그에서 복사함

AI CLI 도구는 계정 토큰과 API 키를 다룬다. 비공식 설치 스크립트를 무심코 실행하면 인증 정보가 노출될 수 있습니다. Codex 관련 악성 npm 패키지와 Gemini CLI 사칭 도구가 보고된 만큼, 설치는 반드시 공식 저장소와 공식 문서 기준으로 진행합니다.

실수 4. 실사용 계정부터 연결함

처음에는 테스트 계정부터 씁니다.

실수 5. 백업 없이 설치함

설치 전 최소한 이것은 남깁니다:

25설치 전 체크리스트

Mac 상태

기본 도구

AI CLI

NanoClaw / HermesClaw

보안

백업

26이 단원의 핵심 정리

설치 전 준비는 설치보다 중요합니다.

초보자가 막히는 대부분의 문제는 Docker, Node, 인증, API 키, 백업에서 나옵니다.

최소 준비 상태는 아래와 같습니다.

실전 기준으로는 이 문장을 기억하면 됩니다.

설치 명령어를 치기 전, 내 Mac이 어떤 상태인지 기록하고, 어떤 계정과 어떤 provider를 쓸지 먼저 정합니다.

5. NanoClaw와 HermesClaw 중 무엇을 선택할까?

01먼저 결론부터

처음 시작하는 초보자라면 NanoClaw부터 시작하는 것이 좋다.

이미 Hermes Agent, OpenClaw, WeChat 연동을 쓰고 있거나, 하나의 WeChat 계정에서 Hermes / OpenClaw / OpenCode를 함께 쓰고 싶다면 HermesClaw를 검토한다.

처음 설치한다
NanoClaw
여러 메시징 앱을 붙이고 싶다
NanoClaw
구조를 쉽게 이해하고 싶다
NanoClaw
WeChat에서 Hermes와 OpenClaw를 같이 쓰고 싶다
HermesClaw
이미 Hermes Agent를 쓰고 있다
HermesClaw 검토
이미 OpenClaw를 쓰고 있다
HermesClaw 검토
Claude / Codex / Gemini 3사 라우팅까지 붙이고 싶다
NanoClaw 또는 Hermes 기반 구조 위에 Provider Router 설계

NanoClaw 공식 사이트는 NanoClaw를 컨테이너 안에서 안전하게 실행되는 개인 AI 에이전트로 설명하고, WhatsApp, Telegram, Discord, Slack, Microsoft Teams, iMessage, Matrix, Google Chat, Webex, Linear, GitHub, WeChat, email 같은 여러 채널을 지원한다고 안내한다.

HermesClaw는 Hermes Agent와 OpenClaw를 같은 WeChat 계정에서 함께 쓰기 위해 만들어진 브리지다. 공식 README는 HermesClaw가 단일 iLink poller가 되고, Hermes와 OpenClaw에는 로컬 프록시 서버를 제공하며, OpenCode에는 ACP bridge를 제공한다고 설명한다.

02NanoClaw는 어떤 도구인가?

NanoClaw는 초보자 기준으로 보면 내 Mac mini 안에서 돌아가는 개인 AI 비서 실행기다.

1사용자 Telegram / Discord / Slack / WhatsApp 등으로 메시지 전송
2NanoClaw가 메시지 수신
3Claude Code 또는 연결된 provider로 작업 처리
4결과를 다시 메시징 앱으로 답장

NanoClaw 공식 GitHub 설명은 NanoClaw를 각 에이전트를 자기 컨테이너 안에서 안전하게 실행하는 AI assistant라고 설명한다. 또한 가볍고, 이해하기 쉽고, 사용자가 필요에 맞게 커스터마이즈하기 쉽게 만들어졌다고 소개한다.

초보자에게 좋은 이유는 아래와 같다.

03HermesClaw는 어떤 도구인가?

HermesClaw는 NanoClaw처럼 처음부터 쓰는 개인 AI 비서라기보다, WeChat 안에서 Hermes Agent와 OpenClaw를 함께 쓰기 위한 연결 도구에 가깝다.

1WeChat 메시지
2HermesClaw가 먼저 받음
3/hermes 명령이면 Hermes Agent로 전달
4/openclaw 명령이면 OpenClaw로 전달
5/opencode 명령이면 OpenCode로 전달
6결과를 다시 WeChat으로 전달

HermesClaw 공식 README는 /hermes, /openclaw, /opencode, /both, /three 같은 명령으로 어떤 에이전트에 메시지를 보낼지 선택할 수 있다고 설명한다.

HermesClaw가 필요한 상황은 비교적 명확하다.

즉, 초보자가 무조건 HermesClaw부터 시작할 필요는 없다. HermesClaw는 기존 Hermes / OpenClaw / WeChat 사용자가 겪는 연결 충돌 문제를 해결하는 쪽에 더 가깝다.

04둘의 차이를 한눈에 보기

구분
초보자 추천도
NanoClaw: 높음 / HermesClaw: 상황에 따라 추천
핵심 목적
NanoClaw: 개인 AI 에이전트 운영 / HermesClaw: Hermes / OpenClaw / OpenCode WeChat 브리지
주 사용 채널
NanoClaw: Telegram, Discord, Slack, WhatsApp 등 여러 채널 / HermesClaw: 주로 WeChat
구조
NanoClaw: 컨테이너 기반 개인 에이전트 / HermesClaw: 단일 iLink poller + 로컬 프록시
시작 난이도
NanoClaw: 비교적 낮음 / HermesClaw: 기존 Hermes/OpenClaw 이해 필요
적합한 사용자
NanoClaw: 처음 설치하는 사용자 / HermesClaw: Hermes/OpenClaw 기존 사용자
Mac mini 활용
NanoClaw: 개인 AI 서버 / HermesClaw: WeChat 기반 멀티 에이전트 브리지
Claude/Codex/Gemini 라우팅
NanoClaw: Provider Router를 붙이기 쉬움 / HermesClaw: Hermes 구조와 함께 설계 가능

실전 기준으로는 이렇게 보면 된다.

NanoClaw
여러 메시징 앱에서 개인 AI 에이전트를 쓰고 싶을 때
HermesClaw
WeChat에서 Hermes, OpenClaw, OpenCode를 같이 쓰고 싶을 때

05처음 시작하는 사람에게 추천하는 순서

처음부터 둘 다 설치하지 않는다. 초보자 추천 순서는 아래와 같다.

  1. NanoClaw부터 설치
  2. Telegram 또는 Discord 하나만 연결
  3. 메시지 송수신 테스트
  4. Claude / Codex / Gemini provider 라우팅 정책 추가
  5. 자동 실행과 로그 관리 설정
  6. 안정화 후 HermesClaw 필요 여부 판단

WeChat, Hermes Agent, OpenClaw를 이미 쓰고 있다면 순서가 달라진다.

  1. 현재 Hermes / OpenClaw 상태 백업
  2. WeChat gateway 상태 확인
  3. HermesClaw가 필요한 이유 확인
  4. 테스트 계정 또는 테스트 환경에서 먼저 실험
  5. 성공 후 실사용 계정에 적용

06선택 기준 질문표

아래 질문에 답하면 선택이 쉽다.

  1. 나는 처음 설치하는가? → 예: NanoClaw 우선
  2. Telegram, Discord, Slack 같은 채널을 쓰고 싶은가? → 예: NanoClaw 우선
  3. WeChat을 반드시 써야 하는가? → 예: HermesClaw 검토
  4. Hermes Agent를 이미 쓰고 있는가? → 예: HermesClaw 검토
  5. OpenClaw를 이미 쓰고 있는가? → 예: HermesClaw 검토
  6. 구조를 쉽게 이해하고 싶고 직접 수정하고 싶은가? → 예: NanoClaw 우선
  7. 하나의 WeChat 계정으로 Hermes / OpenClaw / OpenCode를 모두 쓰고 싶은가? → 예: HermesClaw
  8. Claude / Codex / Gemini 3사 라우팅을 붙이고 싶은가? → NanoClaw부터 시작하고 Provider Router를 설계

07완전 초보자 예시

상황

Mac mini를 처음 샀다. AI 에이전트 설치 경험이 없다. Telegram으로 개인 비서를 만들고 싶다. Claude Code, Codex, Gemini CLI를 같이 쓰고 싶다.

추천

NanoClaw부터 시작

이유: 구조가 더 단순하다 • 여러 메시징 앱 연결에 적합하다 • 처음에는 Telegram 하나만 붙여 테스트하기 좋다 • 나중에 Provider Router를 붙이기 쉽다

08트레이딩 보조 알림봇 예시

상황

가격 알림 • 뉴스 요약 • 매매일지 정리 • 리스크 체크리스트 • Telegram 또는 Discord 알림

추천

NanoClaw 우선

이유: 메시징 채널 중심 운영에 적합하다 • 하나의 알림봇부터 작게 시작할 수 있다 • Claude / Codex / Gemini를 역할별로 분산하기 쉽다

초보자 단계에서는 자동매매보다 아래 기능부터 시작한다.

09WeChat을 꼭 써야 하는 예시

상황

WeChat을 주 메시징 앱으로 쓴다. Hermes Agent를 이미 쓰고 있다. OpenClaw도 함께 쓰고 싶다. 하나의 WeChat 계정에서 명령어로 에이전트를 나누고 싶다.

추천

HermesClaw 검토

이유: HermesClaw의 핵심 목적이 이 상황에 맞다 • /hermes, /openclaw, /opencode 같은 명령으로 라우팅할 수 있다 • 단일 iLink poller 구조로 충돌 문제를 줄이는 것을 목표로 한다

10개발 자동화 중심 예시

상황

Claude Code로 설계 검토 • Codex로 코드 수정 • Gemini CLI로 반복 작업 • Mac mini에서 여러 프로젝트 자동화 • 메시징 앱에서 작업 지시

추천

NanoClaw + Provider Router

이유: NanoClaw는 개인 에이전트 입구로 사용 • Claude / Codex / Gemini는 provider로 사용 • 작업 유형에 따라 라우팅 정책을 붙이면 좋다

11기존 OpenClaw 사용자 예시

상황

OpenClaw 설정이 이미 있다. Hermes Agent로 이전하거나 병행하고 싶다. WeChat 연동이 중요하다.

추천

Hermes Agent 마이그레이션 문서와 HermesClaw 검토

이유: Hermes Agent 공식 문서는 OpenClaw / Clawdbot setup을 Hermes로 가져오는 hermes claw migrate 가이드를 제공한다 • 기존 설정, 메모리, 스킬, API 키 매핑을 확인하고 이전할 수 있다

Hermes Agent의 마이그레이션 문서는 OpenClaw 또는 legacy Clawdbot/Moldbot setup을 Hermes로 가져오는 절차와 config key mapping, 이전 후 확인 항목을 다룬다.

12NanoClaw를 선택해야 하는 경우

아래에 많이 해당하면 NanoClaw가 맞다.

NanoClaw 선택 시 추천 구조:

1Mac mini
2Docker
3NanoClaw
4Telegram 테스트 봇
5Claude Code
6이후 Codex / Gemini 추가

처음 목표:

  1. NanoClaw 실행
  2. 테스트 메시지 수신
  3. 답장 전송
  4. 로그 확인
  5. 재부팅 후 복구
  6. provider routing 추가

13HermesClaw를 선택해야 하는 경우

아래에 많이 해당하면 HermesClaw를 검토한다.

HermesClaw 선택 시 추천 구조:

1Mac mini
2HermesClaw
3Hermes Agent
4OpenClaw
5OpenCode
6WeChat 명령어 라우팅

주의할 점:

14둘 다 설치해도 되는가?

가능은 하지만 초보자에게 처음부터 추천하지 않는다. 처음부터 둘 다 설치하면 문제가 생겼을 때 원인을 찾기 어렵다.

문제 발생 시 헷갈리는 부분:

추천 순서:

초보자
NanoClaw 하나만 설치
WeChat 사용자
HermesClaw 테스트 환경에서 먼저 설치
둘 다 필요한 사용자
1. NanoClaw 안정화 / 2. 로그와 자동 실행 정리 / 3. HermesClaw 별도 폴더에 설치 / 4. 포트 충돌 확인 / 5. provider routing 분리

15Claude / Codex / Gemini 라우팅까지 고려

이 가이드의 핵심은 단순히 NanoClaw냐 HermesClaw냐가 아니다. 최종 목표는 아래 구조다.

1Mac mini
2NanoClaw 또는 HermesClaw
3Provider Router
4Claude Code / OpenAI Codex / Gemini CLI
5메시징 앱으로 결과 반환

초보자 기준으로는 NanoClaw가 Provider Router 입구로 쓰기 쉽다.

NanoClaw
메시징 앱 입구 역할
Provider Router
Claude / Codex / Gemini 중 작업 배정
Claude Code
깊은 분석
Codex
코드 수정과 테스트
Gemini CLI
빠른 반복 작업

HermesClaw는 WeChat 쪽 라우팅이 필요한 경우에 붙인다.

HermesClaw
WeChat에서 Hermes / OpenClaw / OpenCode 라우팅
Provider Router
필요하면 Hermes 쪽 작업 정책에 Claude / Codex / Gemini 선택 규칙 추가

16선택 실수 방지 (1/4)

실수 1. 이름이 비슷해서 같은 도구라고 생각함

NanoClaw와 HermesClaw는 같은 목적의 도구가 아니다.

NanoClaw
개인 AI 에이전트 환경
HermesClaw
Hermes / OpenClaw / OpenCode를 WeChat에서 함께 쓰기 위한 브리지

실수 2. 처음부터 둘 다 설치함

처음부터 둘 다 설치하면 원인 분석이 어려워진다. 초보자는 하나만 설치한다. 첫 번째 도구가 안정화된 뒤 두 번째를 검토한다.

실수 3. HermesClaw를 WeChat 없이 설치하려고 함

HermesClaw는 WeChat 기반 Hermes / OpenClaw / OpenCode 라우팅 목적이 강하다. WeChat이 필요 없고 Hermes/OpenClaw 기존 환경도 없다면 먼저 NanoClaw부터 검토하는 것이 자연스럽다.

17선택 실수 방지 (2/4)

실수 4. provider routing과 메시징 gateway를 섞어서 생각함

NanoClaw / HermesClaw
메시징 앱과 에이전트를 연결하는 입구
Claude / Codex / Gemini
작업을 처리하는 provider
Provider Router
어떤 provider를 쓸지 고르는 관리자

정리하면 이렇게 된다.

메시징 입구
NanoClaw 또는 HermesClaw
작업 처리
Claude Code / Codex / Gemini CLI
선택 정책
Provider Router

18선택 후 첫 목표

NanoClaw를 선택했다면 첫 목표는 이것이다.

1NanoClaw 실행
2테스트 채널 하나 연결
3메시지 수신
4답장 전송
5로그 확인
6재부팅 후 복구

HermesClaw를 선택했다면 첫 목표는 이것이다.

1기존 Hermes / OpenClaw 백업
2WeChat gateway 상태 확인
3HermesClaw 테스트 환경 구성
4/hermes 명령 테스트
5/openclaw 명령 테스트
6로그 확인

절대 처음부터 최종 자동화까지 한 번에 가지 않는다.

  1. 메시지 송수신 성공
  2. provider 연결
  3. 로그 확인
  4. 자동 실행
  5. 보안 설정
  6. 실전 자동화

19선택 체크리스트

NanoClaw가 맞는 경우

HermesClaw가 맞는 경우

둘 다 아직 하면 안 되는 경우

20이 단원의 핵심 정리

초보자는 NanoClaw부터 시작한다. WeChat에서 Hermes / OpenClaw / OpenCode를 함께 써야 하는 사람은 HermesClaw를 검토한다.

최종 판단은 이렇게 하면 된다.

Telegram / Discord / Slack 중심
NanoClaw
개인 AI 비서 입문
NanoClaw
트레이딩 보조 알림봇
NanoClaw
Claude / Codex / Gemini 라우팅
NanoClaw + Provider Router
WeChat 필수
HermesClaw 검토
Hermes Agent 기존 사용자
HermesClaw 검토
OpenClaw 기존 사용자
HermesClaw 또는 Hermes migration 검토

초보자가 기억할 문장은 하나다.

처음에는 NanoClaw로 하나의 메시징 채널만 연결하고, WeChat과 Hermes/OpenClaw가 실제로 필요해졌을 때 HermesClaw를 검토한다.

6. NanoClaw 설치하기

01이 단원에서 하는 일

이 단원에서는 Mac mini에 NanoClaw를 설치한다.

NanoClaw 공식 Quick Start는 아래 3줄로 설치를 시작한다. 공식 README에 따르면 nanoclaw.sh는 새 환경에서 named agent 생성, Node / pnpm / Docker 확인 또는 설치, Anthropic credential 등록, agent container 빌드, 첫 채널 페어링까지 안내한다. 첫 채널은 Telegram, Discord, WhatsApp 또는 local CLI 중 선택할 수 있다.

초보자 확인 항목
Homebrew 설치, Git 설치, Node.js / npm 설치, pnpm 설치, Docker Desktop 설치 및 실행, Claude Code 로그인 상태 확인, 테스트용 메시징 계정 준비, ~/ai-agents 폴더 준비, 백업 폴더 준비

02설치 전 최종 확인

터미널에서 아래 명령어를 실행한다.

$ echo "=== Git ===" $ git --version $ echo "\n=== Node ===" $ node -v $ echo "\n=== npm ===" $ npm -v $ echo "\n=== pnpm ===" $ pnpm -v $ echo "\n=== Docker ===" $ docker --version $ docker compose version $ docker info $ echo "\n=== Claude Code ===" $ claude --version

정상 상태 예시: 모든 도구가 버전을 표시해야 한다. Docker는 docker info가 정상 출력되어야 하고, Claude Code는 claude 명령어를 인식해야 한다.

03Docker daemon 오류 처리

만약 아래처럼 나오면 Docker Desktop이 켜져 있지 않은 것이다:

Cannot connect to the Docker daemon

이 경우:

  1. Applications 폴더에서 Docker 실행
  2. 상단 메뉴바 Docker 아이콘 확인
  3. Docker Desktop이 완전히 켜질 때까지 대기
  4. 다시 docker info 실행

04설치 위치 정하기

이 가이드에서는 모든 AI 에이전트를 아래 폴더에 모은다.

$ mkdir -p ~/ai-agents/projects $ cd ~/ai-agents/projects

현재 위치 확인:

$ pwd

정상이라면 아래와 비슷하게 나온다:

/Users/사용자이름/ai-agents/projects

NanoClaw 설치 폴더는 nanoclaw-v2로 만든다.

$ git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2 $ cd nanoclaw-v2

설치 폴더 확인:

$ ls -la

05설치 스크립트 실행

NanoClaw 공식 설치 명령은 아래와 같다.

$ bash nanoclaw.sh

설치 중에는 보통 아래 흐름을 거친다:

  1. 필요한 프로그램 확인
  2. Node / pnpm / Docker 상태 확인
  3. Claude 또는 Anthropic credential 등록
  4. agent container 빌드
  5. 첫 agent 이름 설정
  6. 첫 메시징 채널 선택
  7. 테스트 메시지 연결

공식 README는 실패 시 Claude Code가 자동으로 진단하고 중단 지점부터 이어서 진행하도록 호출된다고 설명한다.

06설치 중 에이전트 이름 정하기

설치 과정에서 agent 이름을 물어보면 처음에는 단순하게 정한다.

추천 이름: personal-assistant, test-bot, trading-alert, work-helper

처음부터 멋진 이름을 만들 필요는 없다. 실전에서는 이름이 짧고 용도가 명확해야 로그를 볼 때 편하다.

피해야 할 이름: my-super-ultra-agent-final-v3, main-real-live-production-bot, everything-bot

07첫 채널 선택

NanoClaw 공식 README 기준으로 첫 채널은 Telegram, Discord, WhatsApp 또는 local CLI 중 선택할 수 있다.

초보자 추천 순서:

  1. local CLI — 메시징 앱 인증 불필요, 설치 자체 정상 확인 빠름, 오류 원인 파악 쉬움
  2. Telegram — 테스트용 봇 만들기 쉬움, 실사용 계정과 분리 가능, 개인 알림봇/트레이딩 보조봇에 적합
  3. Discord
  4. WhatsApp — 개인 실사용 계정과 연결될 가능성 높음, 인증 문제 시 복구 귀찮음

08설치 중 Claude / Anthropic 인증

NanoClaw 설치 스크립트는 Anthropic credential 등록 과정을 포함한다. 초보자는 여기서 두 가지를 구분해야 한다.

1. Claude 구독 로그인 방식

Claude Pro / Max 등 구독 계정으로 Claude Code에 로그인해서 사용하는 방식이다.

$ claude (Claude Code 안에서) /status /usage

2. API 키 방식

Anthropic API 키를 직접 등록하는 방식이다.

$ env | grep ANTHROPIC

만약 아래처럼 나오면 API 키가 잡혀 있는 상태다:

ANTHROPIC_API_KEY=sk-ant-...

구독 로그인만 쓰고 싶다면 현재 터미널에서:

$ unset ANTHROPIC_API_KEY

09인증 방식 선택 팁

Claude 구독으로 쓸 것인지 API 키로 쓸 것인지 먼저 정한다.

둘을 섞으면 예상치 못한 과금이나 인증 혼동이 생길 수 있다.

처음에는 구독 로그인 방식으로 테스트하고, API fallback은 나중에 추가하는 편이 안전하다.

10설치 중 막혔을 때 바로 쓰는 프롬프트

설치 중 오류가 나오면 에러 메시지를 복사해서 Claude Code, Codex, Gemini 중 하나에 아래처럼 넣는다.

NanoClaw 설치 중 오류가 발생했다.

내 환경: Mac mini Apple Silicon, macOS 버전: [여기에 입력], 설치 위치: ~/ai-agents/projects/nanoclaw-v2, 실행 명령어: bash nanoclaw.sh

요청:

  1. 에러 원인을 추측하지 말고 로그 기준으로 분석해줘
  2. Docker 문제인지, Node/pnpm 문제인지, Claude 인증 문제인지 구분해줘
  3. 내가 바로 실행할 확인 명령어를 알려줘
  4. 복구 명령어를 제시하되, 삭제 명령은 먼저 확인을 요청해줘
  5. 이미 생성된 설정 파일이나 인증 정보가 지워지지 않게 주의해줘

11설치 완료 후 확인할 것

설치가 끝났다고 바로 실사용하지 않는다. 먼저 아래를 확인한다.

$ pwd $ ls -la

Docker 컨테이너 확인:

$ docker ps $ docker ps -a $ docker images

로그 확인이 가능한지 본다:

$ ls -la $ find . -maxdepth 3 -type f -name "*.log"

12정상 설치 판단 기준

13첫 테스트 메시지 보내기

처음 테스트는 짧게 한다.

테스트 메시지: "안녕. 지금 정상 작동 중이면 'NanoClaw 테스트 성공'이라고 답해줘."

정상 응답: "NanoClaw 테스트 성공"

그다음 조금 더 실전적인 테스트를 한다.

정상 응답 기준: 메시지를 받는다, 답장을 보낸다, 응답이 너무 오래 걸리지 않는다, 같은 오류가 반복되지 않는다, 로그에 치명적 에러가 없다

14설치 직후 에이전트 기본 프롬프트

NanoClaw가 메시지를 받을 수 있게 되면 바로 아래 프롬프트를 넣는다.

너는 Mac mini에서 실행되는 NanoClaw 기반 개인 AI 에이전트다. 현재 목표는 실사용이 아니라 안정성 테스트다.

규칙: 파일을 수정하기 전에 먼저 설명한다, 명령어를 실행하기 전에 목적을 설명한다, API 키, 토큰, 비밀번호를 절대 출력하지 않는다, 확인되지 않은 정보는 추측하지 않고 UNKNOWN으로 표시한다, 긴 작업은 바로 실행하지 말고 먼저 확인을 요청한다, Docker, 인증, 메시징 연결 오류가 생기면 원인을 구분해서 보고한다, Claude / Codex / Gemini provider 선택이 필요하면 먼저 어떤 provider를 쓸지 판단한다

응답 형식: 현재 판단, 실행할 작업, 주의할 점, 다음 단계

이 프롬프트는 설치 직후 테스트 에이전트가 제멋대로 길고 복잡한 작업을 시작하지 않게 막는 용도다.

15Provider Router 연결은 설치 후에 한다

NanoClaw 기본 설치가 끝나자마자 Claude / Codex / Gemini 3사 라우팅을 붙이려고 하지 않는다.

설치 순서:

  1. NanoClaw 설치
  2. local CLI 또는 Telegram 테스트
  3. 메시지 송수신 확인
  4. 로그 확인
  5. 재실행 확인
  6. Claude 인증 확인
  7. Codex CLI 확인
  8. Gemini CLI 확인
  9. Provider Router 정책 추가

설치 직후에는 아래 지시문만 넣는다: "아직 Claude / Codex / Gemini 자동 라우팅은 시작하지 마라. 먼저 NanoClaw 자체가 안정적으로 작동하는지 확인한다."

16설치 후 상태 점검 프롬프트

설치가 끝난 뒤 에이전트에게 아래 문장을 보낸다.

NanoClaw 설치 후 상태를 점검해줘. 확인할 항목:

  1. 현재 실행 중인지
  2. 메시지를 받을 수 있는지
  3. 답장을 보낼 수 있는지
  4. Docker 컨테이너가 정상인지
  5. 로그에 반복 에러가 있는지
  6. Claude 인증이 정상인지
  7. 설정 파일이 어디에 있는지
  8. 백업해야 할 파일이 무엇인지
  9. 다음 단계로 넘어가도 되는지

정확히 확인할 수 없는 항목은 UNKNOWN으로 표시하라.

17설치 후 백업하기

설치가 성공했다면 바로 백업한다.

$ mkdir -p ~/ai-agents/backups/nanoclaw-after-install

설치 폴더의 파일 목록 저장:

$ cd ~/ai-agents/projects/nanoclaw-v2 $ find . -maxdepth 3 -type f > ~/ai-agents/backups/nanoclaw-after-install/file-list.txt

현재 Docker 상태 저장:

$ docker ps -a > ~/ai-agents/backups/nanoclaw-after-install/docker-ps-a.txt $ docker images > ~/ai-agents/backups/nanoclaw-after-install/docker-images.txt

환경 정보 저장:

$ ({ echo "DATE: $(date)" echo "PWD: $(pwd)" echo "" echo "Git:" git rev-parse --short HEAD 2>/dev/null || echo "No git commit" echo "" echo "Node:" node -v echo "" echo "npm:" npm -v echo "" echo "pnpm:" pnpm -v echo "" echo "Docker:" docker --version echo "" echo "Claude:" claude --version 2>/dev/null || echo "claude not found" } > ~/ai-agents/backups/nanoclaw-after-install/environment.txt

확인:

$ ls -la ~/ai-agents/backups/nanoclaw-after-install

설치 성공 직후 백업은 매우 중요하다. 이 시점의 상태가 나중에 가장 좋은 복구 기준점이 된다.

18재실행 테스트

설치 직후에는 반드시 종료 후 다시 실행되는지 확인한다.

현재 실행 중인 프로세스나 컨테이너 확인:

$ docker ps

터미널을 닫았다가 다시 연다. 설치 폴더로 이동:

$ cd ~/ai-agents/projects/nanoclaw-v2

Docker 상태 확인:

$ docker ps -a

NanoClaw 실행 방식은 설치 과정에서 안내된 명령을 따른다. 기록용 파일 만들기:

$ nano ~/ai-agents/projects/nanoclaw-v2/RUNBOOK.md

19자주 발생하는 문제와 해결

문제 1. git clone 실패

증상: command not found: git

해결:

$ brew install git $ git --version

문제 2. pnpm 없음

증상: command not found: pnpm

해결:

$ npm install -g pnpm $ pnpm -v

문제 3. 권한 오류

증상: permission denied. 먼저 현재 위치와 파일 권한을 확인한다:

$ pwd $ ls -la

초보자는 바로 sudo를 붙이지 않는다. 에이전트에게 물어본다.

20Claude 인증 오류 대응

확인할 것:

$ claude --version $ claude $ env | grep ANTHROPIC

에이전트에게 물어볼 문장:

NanoClaw 설치 중 Claude 또는 Anthropic 인증 오류가 발생했다. 구독 로그인 방식과 API 키 방식이 섞였는지 확인해줘. 추측하지 말고 확인 가능한 항목과 UNKNOWN 항목을 나눠줘.

21초보자가 하지 말아야 할 것

특히 설치 실패 후 아래 명령을 바로 치지 않는다:

$ rm -rf nanoclaw-v2

삭제가 필요할 때는 먼저 백업한다:

$ mv nanoclaw-v2 nanoclaw-v2-broken-$(date +%Y%m%d-%H%M%S)

22NanoClaw 설치용 실전 프롬프트

설치 전 Claude Code에 아래 문장을 넣어도 된다.

나는 Mac mini에서 NanoClaw를 설치하려고 한다. 설치 위치: ~/ai-agents/projects/nanoclaw-v2. 공식 설치 명령: git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2, cd nanoclaw-v2, bash nanoclaw.sh

너의 역할: 내가 설치 명령을 실행하기 전에 환경을 점검한다, 설치 중 오류가 나면 로그 기준으로 원인을 분석한다, Docker / Node / pnpm / Claude 인증 문제를 구분한다, 삭제 명령은 먼저 내 확인을 받는다, API 키나 토큰은 절대 출력하지 않는다, 확인되지 않은 내용은 UNKNOWN으로 표시한다

23NanoClaw 설치 후 운영 프롬프트

설치가 끝난 뒤에는 아래 문장을 넣는다.

NanoClaw 설치가 끝났다. 이제 실사용 전 안정성 점검을 해줘.

확인할 것: 메시지 수신 가능 여부, 답장 전송 가능 여부, Docker 컨테이너 상태, 로그 위치, 반복 에러 여부, Claude 인증 상태, 백업해야 할 파일, 다음 단계로 넘어가도 되는지

아직 하지 말 것: provider 자동 라우팅, 실사용 계정 연결, 자동 실행 설정, 외부 접속 개방, API fallback 활성화

24설치 완료 기준

아래 항목을 모두 통과하면 6단원 완료다.

설치: 공식 저장소에서 clone했다, nanoclaw-v2 폴더가 생성되었다, bash nanoclaw.sh를 실행했다, 설치 스크립트가 마지막 단계까지 진행되었다

실행: Docker Desktop이 실행 중이다, docker ps로 관련 컨테이너 상태를 확인했다, 첫 채널 또는 local CLI 테스트를 진행했다, 테스트 메시지에 응답했다

인증: Claude Code 또는 Anthropic credential 상태를 확인했다, 구독 로그인 방식과 API 키 방식을 구분했다, ANTHROPIC_API_KEY가 의도치 않게 잡혀 있지 않은지 확인했다

보안: API 키를 노출하지 않았다, .env 파일을 공개하지 않았다, 실사용 계정 대신 테스트 계정부터 사용했다

백업: 설치 후 file-list.txt를 저장했다, docker-ps-a.txt를 저장했다, docker-images.txt를 저장했다, environment.txt를 저장했다, RUNBOOK.md를 만들었다

25이 단원의 핵심 정리

NanoClaw 설치는 공식 기준으로 3줄이면 시작할 수 있다.

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2 cd nanoclaw-v2 bash nanoclaw.sh

하지만 실전에서는 3줄보다 아래가 더 중요하다:

설치 첫날의 목표는 완성형 AI 비서가 아니라, NanoClaw가 메시지를 받고 답장하고 로그를 남기는 상태를 만드는 것이다.

7. HermesClaw 설치하기

01이 단원에서 하는 일

이 단원에서는 Mac mini에서 HermesClaw를 설치하기 전에 구조를 이해하고, Hermes Agent 또는 OpenClaw와 함께 사용할 수 있는지 확인합니다.

먼저 중요한 점이 있습니다. HermesClaw는 NanoClaw처럼 독립형 초보자 설치 패키지로 단정하면 안 됩니다. 현재 확인 가능한 HermesClaw는 Hermes Agent와 OpenClaw를 같은 WeChat 계정 또는 iLink 계정 흐름에서 함께 쓰기 위한 가벼운 프록시 성격이 강합니다.

HermesClaw 자체가 모든 AI 기능을 처리하는 것이 아니라, 메시지를 받아서 Hermes Agent gateway 또는 OpenClaw gateway 쪽으로 넘기는 중간 연결부에 가깝습니다.

이 단원의 목표:

초보자는 이 단원을 "무조건 설치하는 장"이 아니라 "설치해도 되는 상태인지 판단하는 장"으로 읽는 것이 좋습니다.

02HermesClaw 구조 이해하기

HermesClaw는 보통 아래 구조로 이해하면 쉽습니다:

1메시징 계정
2iLink 또는 gateway 계층
3HermesClaw 프록시
4Hermes Agent gateway 또는 OpenClaw gateway
5AI agent 실행
6답장 전송

핵심은 HermesClaw가 "AI 두뇌"가 아니라는 점입니다.

03HermesClaw가 하는 일과 하지 않는 일

HermesClaw가 주로 하는 일:

HermesClaw가 직접 하지 않는 일:

초보자가 가장 자주 헷갈리는 지점: "HermesClaw 설치 = AI 에이전트 설치 완료"라고 생각하면 안 됩니다. 더 정확한 표현은 "HermesClaw 설치 = Hermes Agent 또는 OpenClaw gateway를 메시징 계정과 연결하기 위한 프록시 계층 추가"입니다.

04Hermes Agent와의 관계 이해하기

Hermes Agent는 실제 AI agent 쪽에 가깝습니다.

Hermes Agent에서 다루는 주요 기능:

Hermes Agent 설치 후 기본 확인 명령:

$ hermes

$ hermes model

$ hermes tools

$ hermes setup

$ hermes doctor

메시징 gateway 확인 흐름:

$ hermes gateway

$ hermes gateway setup

$ hermes gateway start

$ hermes status

hermes 명령어가 인식되지 않으면 HermesClaw부터 설치하지 않습니다. 먼저 Hermes Agent 설치와 shell path 문제를 해결해야 합니다.

05OpenClaw와의 관계 이해하기

OpenClaw는 개인 AI 비서형 gateway / agent 환경으로 볼 수 있습니다. OpenClaw 공식 README 기준으로 지원 채널은 WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, Matrix, WeChat 등 다양합니다.

OpenClaw가 이미 설치되어 있다면 HermesClaw를 설치하기 전에 반드시 아래를 확인합니다:

$ openclaw --version

$ openclaw gateway status

$ ls -la ~/.openclaw

$ find ~/.openclaw -maxdepth 3 -type f

06OpenClaw 설정 백업하기

OpenClaw 설정이 있다면 바로 migration을 실행하지 않습니다. 먼저 백업합니다:

$ mkdir -p ~/ai-agents/backups/openclaw-before-hermes

$ cp -R ~/.openclaw ~/ai-agents/backups/openclaw-before-hermes/openclaw-backup

파일 목록도 따로 남깁니다:

$ find ~/.openclaw -maxdepth 4 -type f > ~/ai-agents/backups/openclaw-before-hermes/file-list.txt

실전 팁

OpenClaw를 이미 실사용 중이면 HermesClaw 설치는 "새 설치"가 아니라 "운영 중인 메시징 agent 구조 변경"입니다. 이 경우 설치보다 백업과 롤백 계획이 더 중요합니다.

07설치 전 최종 확인 (1/2)

터미널에서 아래 명령어를 실행합니다:

$ echo "=== macOS ===" $ sw_vers $ echo "\n=== CPU ===" $ uname -m $ echo "\n=== Shell ===" $ echo $SHELL $ echo "\n=== Git ===" $ git --version $ echo "\n=== Python ===" $ python3 --version $ echo "\n=== pip ===" $ python3 -m pip --version

08설치 전 최종 확인 (2/2)

$ echo "\n=== Node ===" $ node -v $ echo "\n=== npm ===" $ npm -v $ echo "\n=== Docker ===" $ docker --version $ docker compose version $ docker info $ echo "\n=== Hermes ===" $ hermes --version 2>/dev/null || echo "hermes not found" $ echo "\n=== OpenClaw ===" $ openclaw --version 2>/dev/null || echo "openclaw not found"

정상 상태 예시:

docker info에서 오류가 나오면:

Cannot connect to the Docker daemon
— Docker Desktop이 켜져 있지 않은 것입니다.

09M4 / M5 Mac mini에서 확인할 점

M4 Mac mini에서는 Apple Silicon 기준으로 아래 항목을 확인합니다:

$ uname -m

정상이라면 보통 다음과 같이 나옵니다:

arm64

M4 기준으로 확인할 것:

M5 Mac mini 공식 출시 후 확인할 항목:

M5라는 이름만 보고 설치 명령어를 바꾸지 않습니다. 공식 문서가 M5 Mac mini에서 별도 명령을 요구하지 않는 한, Apple Silicon macOS 기준으로 검증합니다.

10Hermes Agent 먼저 설치하기

HermesClaw를 설치하기 전에 Hermes Agent 자체가 정상 작동하는지 확인합니다.

공식 README 기준으로 macOS / Linux / WSL2에서는 아래 명령으로 설치를 시작할 수 있습니다:

$ curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

설치 후 shell 설정을 다시 불러옵니다:

$ source ~/.zshrc

bash를 쓰고 있다면:

$ source ~/.bashrc

Hermes 실행 확인:

$ hermes

설치 직후에는 바로 메시징 계정을 연결하지 않습니다. 먼저 기본 진단을 실행합니다:

$ hermes doctor

설정 마법사 실행:

$ hermes setup

모델 provider 확인:

$ hermes model

도구 설정 확인:

$ hermes tools

실전 팁

HermesClaw는 Hermes Agent가 정상 작동할 때 의미가 있습니다. hermes 명령어도 안 되는 상태에서 HermesClaw를 설치하면 오류 원인이 두 배로 늘어납니다.

11Hermes Agent 첫 실행 테스트

Hermes Agent가 설치되면 터미널에서 짧은 테스트를 합니다:

$ hermes

Hermes 대화창 또는 CLI에서 아래 문장을 입력합니다:

안녕. 지금 정상 작동 중이면 "Hermes Agent 테스트 성공"이라고 답해줘.

정상 응답 예시: Hermes Agent 테스트 성공

그다음 조금 더 실전적인 테스트를 합니다:

내가 Mac mini에서 Hermes Agent 설치 상태를 확인하고 있다. 아직 메시징 계정은 연결하지 않았다. 이 상황을 한 줄로 요약해줘.

정상 기준:

12Hermes gateway 설정하기

Hermes Agent가 CLI에서 정상 작동하면 그다음 messaging gateway를 설정합니다:

$ hermes gateway setup

설정 후 gateway를 시작합니다:

$ hermes gateway start

상태 확인:

$ hermes status

또는 설치된 버전에 따라:

$ hermes gateway status

로그 확인:

$ ls -la ~/.hermes

$ find ~/.hermes -maxdepth 4 -type f

환경 변수 파일 확인:

$ ls -la ~/.hermes/.env

단, .env 파일 내용은 그대로 화면 공유하지 않습니다.

실전 팁

메시징 gateway가 안 켜질 때는 코드보다 인증 상태를 먼저 확인합니다. 특히 토큰, 계정 연결, allowed user, home directory 설정이 자주 문제를 만듭니다.

13OpenClaw에서 Hermes로 넘어오기

OpenClaw를 이미 쓰고 있다면 Hermes Agent의 migration 기능을 검토할 수 있습니다. 공식 README 기준으로 Hermes는 첫 hermes setup 과정에서 ~/.openclaw를 감지해 migration을 제안할 수 있습니다.

초보자는 바로 실행하지 말고 dry-run부터 합니다:

$ hermes claw migrate --dry-run

민감 정보를 제외하고 사용자 데이터만 옮기고 싶다면:

$ hermes claw migrate --preset user-data

충돌을 덮어쓰는 옵션은 처음부터 쓰지 않습니다:

$ hermes claw migrate --overwrite

이 옵션은 충분히 이해한 뒤에만 사용합니다.

14migration 전 백업

$ mkdir -p ~/ai-agents/backups/hermes-migration-before

$ cp -R ~/.openclaw ~/ai-agents/backups/hermes-migration-before/openclaw

$ cp -R ~/.hermes ~/ai-agents/backups/hermes-migration-before/hermes 2>/dev/null || true

현재 상태 저장:

{ echo "DATE: $(date)" echo "PWD: $(pwd)" echo "" echo "Hermes:" hermes --version 2>/dev/null || echo "hermes not found" echo "" echo "OpenClaw:" openclaw --version 2>/dev/null || echo "openclaw not found" echo "" echo "Hermes status:" hermes status 2>/dev/null || echo "hermes status failed" } > ~/ai-agents/backups/hermes-migration-before/environment.txt

주의: OpenClaw에서 Hermes로 넘어오는 과정은 단순 설치가 아닙니다. persona, memory, skills, command allowlist, messaging settings, API keys 같은 항목이 이동 대상이 될 수 있습니다. 따라서 dry-run 결과를 먼저 읽고, 어떤 파일이 바뀌는지 확인해야 합니다.

15HermesClaw 설치 전 판단하기

Hermes Agent가 정상이고, OpenClaw 또는 WeChat gateway 구조가 준비된 경우에만 HermesClaw를 검토합니다.

HermesClaw 설치를 검토해도 되는 경우:

HermesClaw를 아직 설치하지 않는 편이 좋은 경우:

16HermesClaw 설치 폴더 만들기

이 가이드에서는 HermesClaw 관련 파일을 아래 폴더에 둡니다:

$ mkdir -p ~/ai-agents/projects $ cd ~/ai-agents/projects

설치 폴더는 hermesclaw로 잡습니다:

$ mkdir -p ~/ai-agents/projects/hermesclaw $ cd ~/ai-agents/projects/hermesclaw

현재 위치 확인:

$ pwd

정상 예시: /Users/사용자이름/ai-agents/projects/hermesclaw

설치 전에 현재 상태를 기록합니다:

{ echo "DATE: $(date)" echo "PWD: $(pwd)" echo "" echo "Python:" python3 --version echo "" echo "pip:" python3 -m pip --version echo "" echo "Hermes:" hermes --version 2>/dev/null || echo "hermes not found" echo "" echo "OpenClaw:" openclaw --version 2>/dev/null || echo "openclaw not found" echo "" echo "Docker:" docker --version 2>/dev/null || echo "docker not found" } > PREINSTALL-CHECK.txt

확인:

$ cat PREINSTALL-CHECK.txt

17HermesClaw 설치하기

현재 확인 가능한 HermesClaw README의 Quick Install은 아래 명령을 안내합니다:

$ curl -fsSL https://raw.githubusercontent.com/AaronWong1999/hermesclaw/main/install.sh | bash

단, 초보자는 외부 스크립트를 바로 실행하기 전에 먼저 내용을 내려받아 확인하는 방식을 권장합니다:

$ curl -fsSL https://raw.githubusercontent.com/AaronWong1999/hermesclaw/main/install.sh -o install.sh

파일 확인:

$ ls -la install.sh

처음 80줄만 확인:

$ sed -n '1,80p' install.sh

실행 권한 부여:

$ chmod +x install.sh

실행:

$ bash install.sh

비대화형 설치 옵션도 존재하지만, 초보자는 처음부터 자동 yes 모드를 쓰지 않습니다.

실전 팁

curl | bash는 빠르지만, 초보자에게는 위험할 수 있습니다. 처음 한 번은 install.sh를 파일로 저장하고, 어떤 파일과 설정을 바꾸는지 확인한 뒤 실행하는 편이 안전합니다.

18설치 중 확인해야 할 것

HermesClaw 설치 과정에서는 보통 아래 항목이 중요합니다:

Mac mini에서는 Linux의 systemd와 macOS의 launchd가 다릅니다. 따라서 설치 로그에서 systemd 관련 메시지가 나오면 그대로 성공으로 단정하지 않습니다. macOS에서는 서비스 자동 실행을 별도로 launchd로 구성해야 할 수 있습니다.

포트 확인:

$ lsof -i :19999

$ lsof -i :19998

둘 중 하나라도 이미 사용 중이면 바로 설치를 계속하지 않습니다:

$ lsof -nP -iTCP -sTCP:LISTEN | grep -E '19999|19998|hermes|openclaw'

19첫 실행 확인하기

설치가 끝나면 먼저 프로세스 상태를 확인합니다:

$ ps aux | grep -i hermesclaw | grep -v grep

Hermes 상태 확인:

$ hermes status

gateway 확인:

$ hermes gateway status 2>/dev/null || hermes status

OpenClaw가 있다면 상태 확인:

$ openclaw gateway status 2>/dev/null || echo "openclaw gateway status unavailable"

포트 확인:

$ lsof -nP -iTCP -sTCP:LISTEN | grep -E '19999|19998'

파일 확인:

$ find ~/ai-agents/projects/hermesclaw -maxdepth 3 -type f

로그 후보 찾기:

$ find ~/ai-agents/projects/hermesclaw ~/.hermes ~/.openclaw -maxdepth 4 -type f \( -name "*.log" -o -name "*.out" -o -name "*.err" \) 2>/dev/null

정상 판단 기준:

20테스트 메시지 보내기

HermesClaw README 기준으로 설치 후 gateway를 재시작하고 WeChat에서 /whoami를 보내는 흐름이 안내됩니다.

테스트 메시지는 짧게 시작합니다: /whoami

그다음 Hermes Agent 쪽 테스트를 합니다:

안녕. 지금 HermesClaw 경유로 메시지를 받았다면 "HermesClaw 테스트 성공"이라고 답해줘.

정상 응답 예시: HermesClaw 테스트 성공

그다음 실제 사용에 가까운 테스트를 합니다:

내가 보낸 메시지를 한 줄로 요약해줘. 메시지: Mac mini에서 Hermes Agent와 HermesClaw 연결 상태를 확인하고 있고, 아직 실사용 자동화는 켜지 않았다.

정상 기준:

21설치 직후 넣을 기본 운영 프롬프트

Hermes Agent 또는 HermesClaw 경유 agent가 메시지를 받을 수 있게 되면 아래 프롬프트를 먼저 넣습니다:

너는 Mac mini에서 실행되는 Hermes Agent 기반 개인 AI 에이전트다. 현재 목표는 실사용이 아니라 HermesClaw 연결 안정성 테스트다.

규칙:

응답 형식:

이 프롬프트는 설치 직후 agent가 과도한 작업을 시작하지 않게 막는 용도입니다.

22설치 후 상태 점검 프롬프트

설치가 끝난 뒤 에이전트에게 아래 문장을 보냅니다:

HermesClaw 설치 후 상태를 점검해줘. 확인할 항목: 1. Hermes Agent가 실행 가능한지, 2. Hermes gateway가 실행 중인지, 3. OpenClaw 설정이 있는지, 4. HermesClaw 프록시가 실행 중인지, 5. 포트 19998 / 19999가 의도대로 열려 있는지, 6. 메시지를 받을 수 있는지, 7. 답장을 보낼 수 있는지, 8. 로그에 반복 에러가 있는지, 9. 인증 파일이나 토큰이 노출되지 않았는지, 10. 백업해야 할 파일이 무엇인지, 11. 다음 단계로 넘어가도 되는지

정확히 확인할 수 없는 항목은 UNKNOWN으로 표시해줘.

출력 형식:

23설치 후 백업하기

설치가 성공했다면 바로 백업합니다:

$ mkdir -p ~/ai-agents/backups/hermesclaw-after-install

설치 폴더 파일 목록 저장:

$ find ~/ai-agents/projects/hermesclaw -maxdepth 4 -type f > ~/ai-agents/backups/hermesclaw-after-install/file-list.txt

Hermes 설정 파일 목록 저장:

$ find ~/.hermes -maxdepth 4 -type f > ~/ai-agents/backups/hermesclaw-after-install/hermes-file-list.txt 2>/dev/null

OpenClaw 설정 파일 목록 저장:

$ find ~/.openclaw -maxdepth 4 -type f > ~/ai-agents/backups/hermesclaw-after-install/openclaw-file-list.txt 2>/dev/null

포트 상태 저장:

$ lsof -nP -iTCP -sTCP:LISTEN > ~/ai-agents/backups/hermesclaw-after-install/listening-ports.txt

환경 정보 저장:

{ echo "DATE: $(date)" echo "PWD: $(pwd)" echo "" echo "macOS:" sw_vers echo "" echo "CPU:" uname -m echo "" echo "Python:" python3 --version echo "" echo "Node:" node -v 2>/dev/null || echo "node not found" echo "" echo "Docker:" docker --version 2>/dev/null || echo "docker not found" echo "" echo "Hermes:" hermes --version 2>/dev/null || echo "hermes not found" echo "" echo "OpenClaw:" openclaw --version 2>/dev/null || echo "openclaw not found" } > ~/ai-agents/backups/hermesclaw-after-install/environment.txt

확인:

$ ls -la ~/ai-agents/backups/hermesclaw-after-install

실전 팁

HermesClaw는 gateway 설정과 토큰 흐름이 얽히기 쉽습니다. 설치 성공 직후의 파일 목록, 포트 상태, 환경 정보를 반드시 남겨둡니다.

24재실행 테스트

설치 직후에는 반드시 종료 후 다시 실행되는지 확인합니다:

현재 상태 확인:

$ ps aux | grep -i hermes | grep -v grep

$ ps aux | grep -i hermesclaw | grep -v grep

$ lsof -nP -iTCP -sTCP:LISTEN | grep -E '19998|19999'

Hermes gateway 재시작:

$ hermes gateway stop

$ hermes gateway start

상태 확인:

$ hermes status

HermesClaw 실행 방식은 설치 스크립트가 안내한 방식을 따릅니다. 설치 로그에 나온 실행 명령어를 반드시 기록합니다:

$ nano ~/ai-agents/projects/hermesclaw/RUNBOOK.md

예시 내용: # HermesClaw Runbook / ## 설치 위치: ~/ai-agents/projects/hermesclaw / ## 관련 구성: Hermes Agent: ~/.hermes, OpenClaw: ~/.openclaw, HermesClaw: ~/ai-agents/projects/hermesclaw / ## 설치 명령: curl -fsSL https://raw.githubusercontent.com/AaronWong1999/hermesclaw/main/install.sh -o install.sh / bash install.sh / ## 상태 확인: hermes status / hermes doctor / ps aux | grep hermes / ps aux | grep hermesclaw / lsof -nP -iTCP -sTCP:LISTEN | grep -E '19998|19999'

25자주 발생하는 문제 (1/5) — hermes 명령어 없음

증상:

command not found: hermes

확인:

$ echo $SHELL

$ echo $PATH

$ ls -la ~/.local/bin

해결 후보:

$ source ~/.zshrc

또는:

$ source ~/.bashrc

그래도 안 되면 Hermes Agent 설치 로그를 다시 확인합니다:

$ find ~ -maxdepth 4 -iname "*hermes*" 2>/dev/null

26자주 발생하는 문제 (2/5) — Python dependency 설치 실패

증상:

ModuleNotFoundError
또는
pip: command not found

확인:

$ python3 --version

$ python3 -m pip --version

해결 후보:

$ python3 -m pip install --upgrade pip

필요한 패키지가 명확히 보일 때만 설치합니다:

$ python3 -m pip install requests python-dotenv

단, 설치 스크립트가 가상환경을 쓰는 구조라면 전역 pip에 설치하지 말고 해당 가상환경 안에서 설치해야 합니다.

27자주 발생하는 문제 (3/5) — 포트가 이미 사용 중

증상:

Address already in use
}

확인:

$ lsof -i :19999

$ lsof -i :19998

전체 확인:

$ lsof -nP -iTCP -sTCP:LISTEN | grep -E '19999|19998'

초보자는 바로 kill하지 않습니다. 에이전트에게 이렇게 물어봅니다:

HermesClaw 설치 중 포트 충돌이 발생했다. 확인 결과: lsof -i :19999 결과: [붙여넣기], lsof -i :19998 결과: [붙여넣기]. 요청: 1) 어떤 프로세스가 포트를 쓰는지 분석, 2) Hermes / OpenClaw / HermesClaw 중 무엇과 관련 있는지 구분, 3) 바로 kill하지 말고 안전한 종료 방법 알려줌, 4) 포트를 바꿔야 하면 어느 파일을 확인해야 하는지 알려줌

28자주 발생하는 문제 (4/5) — WeChat / iLink 인증 문제

증상:

확인:

$ ls -la ~/.hermes

$ ls -la ~/.openclaw

$ find ~/.hermes ~/.openclaw -maxdepth 5 -type f | grep -Ei 'account|token|weixin|wechat|ilink|env|json'

단, 파일 내용을 그대로 공유하지 않습니다. 마스킹해서 확인합니다:

$ sed 's/=.*/=***REDACTED***/' ~/.hermes/.env 2>/dev/null

실전 팁

인증 오류는 코드 수정으로 해결하려고 하지 않습니다. 대부분은 계정 로그인, 토큰 위치, gateway 설정, allowed user 문제입니다.

29자주 발생하는 문제 (5/5) — OpenClaw migration 후 gateway 이상

증상:

먼저 백업 여부를 확인합니다:

$ ls -la ~/ai-agents/backups/hermes-migration-before

OpenClaw 백업 파일 확인:

$ find ~/ai-agents/backups/hermes-migration-before -maxdepth 5 -type f | head -100

Hermes 설정 확인:

$ ls -la ~/.hermes

OpenClaw 설정 확인:

$ ls -la ~/.openclaw

초보자는 바로 덮어쓰지 않습니다. 에이전트에게 물어봅니다: OpenClaw에서 Hermes로 migration 후 gateway 문제가 발생했다. 내 확인 결과: hermes status: [붙여넣기], ~/.hermes 파일 목록: [민감정보 제외하고 붙여넣기], ~/.openclaw 파일 목록: [민감정보 제외하고 붙여넣기], 백업 위치: ~/ai-agents/backups/hermes-migration-before. 요청: 1) 설정 파일 누락인지 인증 토큰 누락인지 구분, 2) OpenClaw 원본 백업에서 어떤 파일을 확인해야 하는지 알려줌, 3) 덮어쓰기 전에 diff 또는 파일 목록 비교 방법 알려줌, 4) 토큰이나 API 키는 절대 출력하지 않게 안내

30초보자가 하지 말아야 할 것

  • hermes 명령어가 안 되는데 HermesClaw부터 설치하지 않는다
  • 실사용 WeChat 계정 하나만으로 바로 테스트하지 않는다
  • curl | bash를 아무 확인 없이 반복 실행하지 않는다
  • .env, token, account json 파일을 그대로 공유하지 않는다
  • 포트 충돌이 났다고 바로 kill -9를 쓰지 않는다
  • OpenClaw 설정을 백업하지 않고 migration하지 않는다
  • migration 실패 후 ~/.openclaw 또는 ~/.hermes를 바로 삭제하지 않는다
  • systemd 안내를 macOS launchd와 같은 것으로 착각하지 않는다
  • HermesClaw를 AI 모델 provider router로 오해하지 않는다

    • 특히 아래 명령을 바로 치지 않습니다:

    $ rm -rf ~/.openclaw

    $ rm -rf ~/.hermes

    $ rm -rf ~/ai-agents/projects/hermesclaw

    삭제가 필요할 때는 먼저 이름을 바꿔 보관합니다:

    $ mv ~/ai-agents/projects/hermesclaw ~/ai-agents/projects/hermesclaw-broken-$(date +%Y%m%d-%H%M%S)

    31HermesClaw 설치용 실전 프롬프트

    설치 전 Claude Code, Codex, Gemini 중 하나에 아래 문장을 넣어도 됩니다:

    나는 Mac mini Apple Silicon에서 HermesClaw 설치 가능 여부를 점검하려고 한다. 현재 목표: Hermes Agent가 정상 작동하는지 확인, OpenClaw 설정이 있다면 백업, HermesClaw 설치 전 필수 조건 확인, 메시징 gateway와 포트 충돌 확인, 실사용 계정이 아니라 테스트 계정 기준으로 진행

    내 환경: macOS 버전: [입력], Mac mini 칩: M4 / M4 Pro / M5 공식 출시 후 확인, 설치 위치: ~/ai-agents/projects/hermesclaw, Hermes Agent 사용 여부: [예/아니오/UNKNOWN], OpenClaw 사용 여부: [예/아니오/UNKNOWN], WeChat 또는 iLink 계정 준비 여부: [예/아니오/UNKNOWN]

    너의 역할: 설치 명령을 실행하기 전에 환경을 점검, Hermes Agent / OpenClaw / HermesClaw 문제를 구분, 포트 19998 / 19999 충돌 여부를 확인, migration이 필요하면 dry-run부터 안내, 삭제 명령은 먼저 확인받기, API 키, 토큰, 쿠키, 세션값은 절대 출력 금지, 확인되지 않은 내용은 UNKNOWN으로 표시

    먼저 내가 실행해야 할 확인 명령어를 순서대로 알려줘.

    32HermesClaw 설치 후 운영 프롬프트

    설치가 끝난 뒤에는 아래 문장을 넣습니다:

    HermesClaw 설치가 끝났다. 이제 실사용 전 안정성 점검을 해줘.

    확인할 것: Hermes Agent 실행 가능 여부, Hermes gateway 상태, OpenClaw 설정 존재 여부, HermesClaw 프록시 실행 여부, 포트 19998 / 19999 상태, 메시지 수신 가능 여부, 답장 전송 가능 여부, 로그 위치, 반복 에러 여부, 인증 파일 노출 위험, 백업해야 할 파일, 다음 단계로 넘어가도 되는지

    아직 하지 말 것: 실사용 계정 연결 확대, provider 자동 라우팅, 자동 실행 설정, 외부 접속 개방, API fallback 활성화, OpenClaw 설정 삭제, migration overwrite

    출력 형식: ## HermesClaw 설치 후 점검 결과 / ### 정상 —, ### 확인 필요 —, ### 위험 —, ### 지금 하면 안 되는 것 —, ### 다음 단계 —

    33설치 완료 기준

    아래 항목을 모두 통과하면 7단원 완료입니다:

    설치 전

    Hermes Agent

    OpenClaw

    HermesClaw

    보안

    백업

    34이 단원의 핵심 정리

    HermesClaw는 AI agent 본체라기보다 Hermes Agent와 OpenClaw gateway 흐름을 연결하는 프록시 계층에 가깝습니다.

    설치 순서는 아래처럼 잡는 것이 안전합니다:

    1. Hermes Agent 설치
    2. hermes CLI 테스트
    3. hermes doctor 실행
    4. hermes gateway 설정
    5. OpenClaw 사용 여부 확인
    6. OpenClaw 설정 백업
    7. HermesClaw 설치 전 포트 확인
    8. HermesClaw 설치
    9. /whoami 또는 테스트 메시지 확인
    10. 로그와 백업 정리

    초보자가 기억할 문장은 하나입니다:

    HermesClaw 설치 첫날의 목표는 완성형 자동화가 아니라, Hermes Agent와 gateway가 메시지를 안전하게 주고받는 상태를 확인하는 것입니다.

    이 단원을 끝냈다고 바로 자동 실행이나 실사용 계정 연결을 확대하지 않습니다. 다음 단계는 8단원에서 "처음 실행 후 반드시 확인할 것"을 기준으로 프로세스, 로그, 메시지 송수신, API 호출, 재부팅 후 실행 여부를 하나씩 검증하는 것입니다.

    8. 처음 실행 후 반드시 확인할 것

    01이 단원에서 하는 일

    이 단원에서는 NanoClaw 또는 HermesClaw를 처음 실행한 뒤 반드시 확인해야 하는 항목을 점검합니다.

    설치 성공은 보통 아래 상태를 뜻합니다:

    하지만 운영 가능 상태는 더 많이 확인해야 합니다:

    초보자는 이 단원을 "문제가 생겼을 때 보는 장"이 아니라 "실사용 전에 반드시 통과해야 하는 점검표"로 보면 됩니다.

    02먼저 어떤 방식으로 실행 중인지 구분하기

    NanoClaw, Hermes Agent, OpenClaw, HermesClaw는 실행 구조가 다를 수 있으므로 먼저 내가 무엇을 실행 중인지 구분해야 합니다.

    가능한 실행 방식은 다음과 같습니다:

    먼저 전체 상태를 한 번에 확인합니다:

    echo "=== 현재 위치 ===" pwd echo "\n=== 실행 중인 Docker 컨테이너 ===" docker ps echo "\n=== 전체 Docker 컨테이너 ===" docker ps -a echo "\n=== Hermes 상태 ===" hermes status 2>/dev/null || echo "hermes status unavailable" echo "\n=== 관련 프로세스 ===" ps aux | grep -Ei 'nanoclaw|hermes|openclaw|claw|gateway' | grep -v grep

    이 명령은 문제를 해결하는 명령이 아니라 현재 상태를 관찰하는 명령입니다.

    실전 팁

    처음 실행 후 가장 위험한 착각은 "명령어가 끝났으니 실행 중이겠지"라고 생각하는 것입니다. 실제로는 설치 명령은 끝났지만 gateway나 컨테이너는 꺼져 있을 수 있습니다.

    03프로세스가 실행 중인지 확인하기 — Docker 기반

    NanoClaw는 컨테이너 기반 구조를 사용할 수 있으므로 먼저 Docker 상태를 확인합니다:

    docker ps

    docker ps는 실행 중인 컨테이너만 보여주고, 중지된 컨테이너까지 보려면 다음을 실행합니다:

    docker ps -a

    정상 예시는 아래와 비슷합니다:

    STATUS
    Up ... | healthy | 일정 시간 이상 유지됨
    주의 상태
    Exited | Restarting | Created에서 멈춤 | 몇 초마다 Up 시간이 초기화됨

    컨테이너가 계속 재시작되는지 확인하려면 반복 모니터링을 합니다:

    watch -n 2 docker ps -a

    macOS에 watch가 없으면 다음처럼 반복 확인합니다:

    while true; do date docker ps -a sleep 2 clear done

    중지하려면 Ctrl + C를 누릅니다.

    04프로세스가 실행 중인지 확인하기 — Docker Compose & gateway

    Docker Compose 기반이면 설치 폴더에서 다음을 확인합니다:

    ls -la | grep -Ei 'compose|docker-compose'

    Compose 상태 확인:

    docker compose ps

    Hermes gateway를 쓰는 경우 상태를 먼저 확인합니다:

    hermes status

    gateway 설정 여부 확인:

    hermes gateway status 2>/dev/null || hermes status

    Hermes gateway를 직접 시작해야 하는 경우:

    hermes gateway start

    OpenClaw를 쓰는 경우 아래 명령을 확인합니다:

    openclaw gateway status

    debug mode로 직접 실행해야 할 때는 기존 gateway를 먼저 멈춥니다:

    openclaw gateway stop

    그다음 foreground debug mode로 실행합니다:

    openclaw gateway --port 18789 --verbose

    이 방식은 문제 분석용이고, 24시간 운영용으로는 daemon 또는 자동 실행 설정을 따로 잡아야 합니다.

    05로그가 정상적으로 쌓이는지 확인하기

    로그는 "문제가 있을 때 보는 것"이 아니라 "정상 작동 기준을 정하는 것"입니다. 처음 실행 직후에는 반드시 로그를 확인합니다.

    Docker 컨테이너 로그 확인:

    실행 중인 컨테이너 이름을 확인한 후 다음처럼 조회합니다. 컨테이너 이름이 nanoclaw-agent라고 가정하면:

    docker logs --tail 100 nanoclaw-agent

    실시간으로 보려면:

    docker logs --tail 100 --follow nanoclaw-agent

    Docker Compose 로그 확인:

    Compose 기반이면 프로젝트 폴더에서 다음을 실행합니다:

    docker compose logs --tail 100

    실시간 확인:

    docker compose logs --tail 100 --follow

    정상 로그 판단 기준:

    정상 신호
    service started | gateway listening | connected | message received | message sent | auth ok | ready | 반복 오류 없음
    주의 신호
    authentication failed | invalid token | missing API key | rate limit | permission denied | address already in use | cannot connect to Docker daemon | module not found | restart loop
    로그 판단 팁

    로그에서 에러 단어 하나를 봤다고 바로 실패로 판단하지 않습니다. 같은 에러가 반복되는지, 메시지 송수신이 실제로 실패하는지, 프로세스가 죽는지를 함께 봐야 합니다.

    06메시지를 받을 수 있는지 확인하기

    메시지 수신 확인은 "agent가 생각을 잘하느냐"보다 먼저입니다. 처음에는 복잡한 요청을 보내지 않습니다.

    local CLI 테스트:

    NanoClaw나 Hermes Agent에서 local CLI를 제공하는 경우 가장 먼저 local CLI로 확인합니다.

    테스트 메시지: "안녕. 이 메시지를 받았다면 '수신 테스트 성공'이라고만 답해줘."

    정상 응답: "수신 테스트 성공"

    이 테스트의 목적은 모델 성능 확인이 아니라 다음을 확인하는 것입니다:

    메시징 앱 테스트:

    메시징 앱에서는 먼저 아주 짧은 메시지를 보냅니다: "ping" 또는 "테스트. 받았으면 'pong'이라고 답해줘."

    응답이 없으면 아래 순서로 확인합니다:

    수신은 되었지만 답이 없는 경우:

    수신 로그는 있는데 답이 없으면 문제 범위가 좁아집니다. 가능한 원인은 모델 provider 호출 실패, API 키 오류, rate limit, agent 내부 오류, outbound delivery 오류 등입니다.

    Docker 기반이면 수신과 발신 로그를 분리해서 봅니다:

    docker logs --since 10m 컨테이너이름 | grep -Ei 'receive|received|inbound|send|sent|outbound|error|fail'

    07메시지를 보낼 수 있는지 확인하기

    메시지 발신은 수신보다 더 많은 문제가 생깁니다. 수신은 되었지만 발신이 안 되는 경우, agent 자체보다 메시징 채널 권한 문제가 원인일 수 있습니다.

    NanoClaw 발신 테스트:

    공통 테스트 문장: "아래 문장을 그대로 답장해줘. NanoClaw 발신 테스트 성공"

    정상 응답: "NanoClaw 발신 테스트 성공"

    정상 판단 기준:

    Hermes Agent 발신 테스트:

    Hermes gateway를 쓰는 경우 먼저 gateway 상태를 확인합니다:

    hermes status

    메시징 앱에서 다음 문장을 보냅니다: "Hermes 발신 테스트야. 받았으면 'Hermes 발신 테스트 성공'이라고 답해줘."

    OpenClaw 발신 테스트:

    OpenClaw는 문서에서 openclaw message send 예시를 제공하며, 실제 target 값은 연결한 채널과 계정 설정에 따라 달라집니다:

    openclaw message send --target 대상 --message "Hello from OpenClaw"

    초보자는 실사용 대상에게 바로 보내지 않고, 테스트용 계정, 테스트용 채팅방, 본인만 있는 DM, 운영 전용 알림방으로 먼저 테스트합니다.

    메시지가 여러 번 발송되는 경우:

    같은 답장이 여러 번 오면 즉시 자동화 테스트를 멈추고 다음을 확인합니다:

    ps aux | grep -Ei 'nanoclaw|hermes|openclaw|gateway' | grep -v grep

    가능한 원인은 gateway를 중복 실행, Docker 컨테이너와 로컬 프로세스 동시 실행, launchd 자동 실행과 수동 실행 겹침, 동일 메시징 계정을 두 agent가 동시에 보기, retry 로직이 실패를 성공으로 인식 등입니다. 이 경우 기능을 추가하지 말고 중복 실행부터 해결합니다.

    08API 호출이 정상인지 확인하기

    API 호출 확인은 "모델이 똑똑한가"를 보는 단계가 아닙니다. 먼저 아래를 구분합니다:

    구독 로그인 방식
    Claude Code, ChatGPT/Codex, Gemini CLI 등 로그인 세션을 통해 사용 | CLI 상태 명령이나 provider별 로그인 상태를 확인해야 함
    API 키 방식
    ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY 등 환경 변수 또는 설정 파일 사용 | 키 존재 여부, 권한, rate limit, billing 상태를 확인해야 함

    환경 변수 확인:

    API 키가 의도치 않게 잡혀 있는지 확인합니다:

    env | grep -Ei 'ANTHROPIC|OPENAI|GEMINI|GOOGLE|API_KEY|TOKEN'

    Claude Code 구독 로그인 확인:

    Claude Code를 쓰는 경우 먼저 CLI가 실행되는지 확인합니다:

    claude --version

    Claude Code 안에서 상태를 확인합니다:

    /status

    Anthropic API 키 방식 확인:

    API 키가 존재하는지만 확인합니다 (값은 출력하지 않음):

    test -n "$ANTHROPIC_API_KEY" && echo "ANTHROPIC_API_KEY is set" || echo "ANTHROPIC_API_KEY is not set"

    API 호출 테스트는 아주 작은 요청으로 합니다. 정상 기준은 HTTP 응답이 오고, 인증 오류가 아니며, rate limit 오류가 아니고, 응답 본문에 모델 출력이 포함되는 것입니다.

    API 정상 판단 기준:

    09재부팅 후 다시 실행되는지 확인하기

    재부팅 후 자동 실행은 실사용 전 반드시 확인해야 합니다. 하지만 이 단원에서는 자동 실행을 새로 설정하지 않고, "현재 설치 상태가 재부팅 후에도 살아나는지"만 확인합니다.

    재부팅 전 상태 저장:

    재부팅 전에 현재 상태를 파일로 저장합니다:

    mkdir -p ~/ai-agents/checks/after-first-run

    Docker 상태 저장:

    docker ps -a > ~/ai-agents/checks/after-first-run/docker-ps-a-before-reboot.txt

    프로세스 상태 저장:

    ps aux | grep -Ei 'nanoclaw|hermes|openclaw|gateway' | grep -v grep > ~/ai-agents/checks/after-first-run/process-before-reboot.txt

    포트 상태 저장:

    lsof -nP -iTCP -sTCP:LISTEN | grep -Ei '18789|19998|19999|nanoclaw|hermes|openclaw' > ~/ai-agents/checks/after-first-run/ports-before-reboot.txt 2>/dev/null

    Mac 재부팅:

    재부팅 전에 설치 중인 작업이 없고, 중요한 편집 파일을 저장했으며, 메시징 테스트 중복 발송이 멈춰 있는지 확인합니다:

    sudo shutdown -r now

    초보자가 불안하면 Apple 메뉴 → 재시동으로 해도 됩니다.

    재부팅 후 상태 확인:

    재부팅 후 터미널을 열고 상태를 다시 확인합니다:

    docker ps -a > ~/ai-agents/checks/after-first-run/docker-ps-a-after-reboot.txt
    ps aux | grep -Ei 'nanoclaw|hermes|openclaw|gateway' | grep -v grep > ~/ai-agents/checks/after-first-run/process-after-reboot.txt

    파일을 비교합니다:

    diff -u ~/ai-agents/checks/after-first-run/docker-ps-a-before-reboot.txt ~/ai-agents/checks/after-first-run/docker-ps-a-after-reboot.txt

    차이가 있다고 무조건 실패는 아닙니다. 중요한 것은 필요한 gateway가 다시 실행되었는지, 필요한 컨테이너가 다시 Up 상태인지, 메시지를 받을 수 있는지, 메시지를 보낼 수 있는지, 재부팅 후 인증이 풀리지 않았는지, 로그에 재시작 실패가 반복되지 않는지입니다.

    Docker 자동 재시작 여부 확인:

    docker inspect --format '{{.Name}} {{.HostConfig.RestartPolicy.Name}}' $(docker ps -aq)

    no로 나오면 Docker가 재시작될 때 자동으로 살아나지 않을 수 있습니다. 이 단원에서는 바로 설정을 바꾸지 않고, 자동 재시작 설정은 10단원에서 다룹니다.

    10처음 실행 후 완료 체크리스트

    아래 항목을 모두 통과하면 8단원 완료입니다:

    프로세스

    로그

    메시지

    API와 재부팅

    11초보자가 하지 말아야 할 것

    특히 아래 명령은 바로 실행하지 않습니다:

    docker rm -f $(docker ps -aq)
    rm -rf ~/.hermes
    rm -rf ~/.openclaw
    rm -rf ~/ai-agents/projects

    삭제가 필요할 때도 먼저 백업하거나 이름을 바꿉니다:

    mv 문제폴더 문제폴더-broken-$(date +%Y%m%d-%H%M%S)

    12이 단원의 핵심 정리

    처음 실행 후 확인할 것은 "설치가 되었는가"가 아니라 "운영 가능한가"입니다.

    가장 중요한 확인 순서는 아래와 같습니다:

    1. 프로세스가 살아 있는가
    2. gateway가 실행 중인가
    3. 로그가 쌓이는가
    4. 메시지를 받을 수 있는가
    5. 메시지를 보낼 수 있는가
    6. API 호출이 정상인가
    7. 재부팅 후 다시 살아나는가
    AI agent 실사용은 첫 답장이 왔을 때 시작하는 것이 아니라, 재부팅 후에도 메시지 수신, 답장, 로그, API 호출이 모두 정상임을 확인한 뒤 시작합니다.

    8단원을 통과하면 다음 단계는 자동 실행 설정이 아닙니다. 먼저 9단원에서 구독, 사용량 한도, 끊김 방지 운영을 이해해야 하고, 자동 실행은 agent가 안정적으로 작동하고, 한도 초과 시 멈추는 방식까지 정한 뒤 10단원에서 설정하는 편이 안전합니다.

    9. GPT · Claude Code · Gemini 역할 분리형 AI 코딩 운영 가이드

    01이 단원의 핵심 목적

    이 단원은 단순히 여러 AI 도구를 번갈아 쓰는 방법이 아니다.

    목적은 다음과 같다:

    GPT / Codex
    코드 전략 분석, 논리 검증, Claude 작업 결과 검토, 수정 지시문 작성
    Claude Code
    코드베이스 분석, 실제 코드 작성, 파일 수정, 테스트 실행, 리팩터링 적용
    Gemini
    UI/UX 디자인 검토, 화면 구성 아이디어, 문서 구조 정리, 디자인 설명문 작성, 시각적 개선안 제안

    중요한 원칙은 7가지다:

    1. Claude에게 바로 코드를 쓰게 하지 않는다
    2. 먼저 코드 구조와 문제를 분석하게 한다
    3. GPT / Codex가 Claude의 분석을 검토한다
    4. GPT / Codex가 더 나은 수정 지시문을 만든다
    5. Claude가 최종 코드 작성과 파일 수정을 맡는다
    6. Gemini는 디자인과 시각 구조 보조에 사용한다
    7. 확인하지 못한 성능, 한도, 내부 동작은 추측하지 않는다

    02기본 역할 분담

    GPT / Codex
    코드 전략 분석, 논리 오류 검토, Claude가 작성한 계획 검증, Claude에게 줄 재지시문 작성, 테스트 전략 설계, 리팩터링 방향 검토
    Claude Code
    코드베이스 직접 탐색, 실제 파일 수정, 버그 수정, 테스트 실행, 리팩터링 적용, 변경 내역 정리
    Gemini
    UI/UX 디자인 아이디어, 화면 구성 검토, 사용자 흐름 개선, 문서 디자인, 마크다운 구조 정리, 시각적 표현 개선

    핵심 제약: Gemini는 중요한 코드 논리 판단의 최종 결정자로 사용하지 않는다. 복잡한 코드 전략과 논리 검증은 GPT / Codex가 맡는다. 실제 코드 작성과 파일 변경은 Claude Code가 맡는다.

    03표준 작업 흐름

    실전에서는 아래 흐름을 기본으로 사용한다:

    1. Claude Code가 코드베이스를 읽고 문제를 분석한다
    2. Claude Code는 바로 수정하지 않고 분석 보고서만 작성한다
    3. GPT / Codex가 Claude의 분석을 검토한다
    4. GPT / Codex가 논리 오류, 누락, 위험 요소를 점검한다
    5. GPT / Codex가 Claude에게 줄 최종 수정 지시문을 작성한다
    6. Claude Code가 그 지시문을 기준으로 실제 코드를 수정한다
    7. Claude Code가 테스트를 실행한다
    8. GPT / Codex가 변경 결과를 다시 검토한다
    9. Gemini가 UI/UX 또는 문서 디자인이 필요한 부분만 보조한다

    이 흐름의 핵심은 이것이다:

    Claude는 손이다. GPT / Codex는 전략가다. Gemini는 디자이너다.

    04에이전트 기본 운영 프롬프트

    아래 문장을 에이전트의 기본 운영 규칙으로 넣는다:

    너는 GPT / Codex, Claude Code, Gemini를 함께 사용하는 AI 개발 라우터다. 너의 목표는 사용자의 작업을 가장 안전하고 효율적인 provider에게 배정하는 것이다. 역할은 다음과 같이 나눈다. GPT / Codex: - 코드 전략 분석 - 논리 검증 - 수정 방향 설계 - Claude 작업 결과 리뷰 - Claude에게 줄 재지시문 작성 Claude Code: - 코드베이스 탐색 - 실제 코드 작성 - 파일 수정 - 테스트 실행 - 리팩터링 적용 - 변경 내역 보고 Gemini: - UI/UX 디자인 검토 - 화면 구조 제안 - 문서 디자인 - 시각적 표현 개선 - 가벼운 초안 작성 작업을 받으면 바로 실행하지 말고 먼저 아래를 판단한다. 1. 이 작업이 코드 전략 작업인지 2. 실제 파일 수정이 필요한지 3. 디자인 판단이 필요한지 4. 논리 검증이 필요한지 5. 어떤 provider를 먼저 사용할지 6. 최종 실행 provider는 누구인지 기본 원칙: - 코드 수정 전에는 먼저 분석한다 - 분석과 실행을 같은 provider에게 바로 맡기지 않는다 - Claude가 분석한 내용은 GPT / Codex가 검토한다 - GPT / Codex가 만든 재지시문을 Claude가 실행한다 - Gemini는 디자인과 시각 구조에만 우선 사용한다 - 확인되지 않은 사용량과 한도는 UNKNOWN으로 표시한다 - 추가 비용이 발생할 수 있는 API fallback은 사용자 승인 후에만 사용한다 - 한도 우회를 목적으로 계정이나 provider를 돌려쓰지 않는다 - 중요한 작업은 실행 전 provider 선택 이유를 한 줄로 말한다

    05코드 작업용 표준 명령문

    사용자가 코드 작업을 시킬 때는 아래처럼 말한다:

    이 작업은 바로 수정하지 말고 3단계로 처리해줘. 작업: [여기에 작업 내용 입력] 진행 방식: 1단계: Claude Code - 코드베이스를 읽고 문제 원인을 분석한다. - 수정하지 않는다. - 관련 파일, 원인 후보, 위험 요소를 정리한다. 2단계: GPT / Codex - Claude의 분석을 검토한다. - 논리 오류와 빠진 가능성을 찾는다. - 더 안전한 수정 전략을 만든다. - Claude에게 줄 최종 수정 지시문을 작성한다. 3단계: Claude Code - GPT / Codex가 만든 지시문을 기준으로 실제 파일을 수정한다. - 수정 후 테스트를 실행한다. - 변경 파일과 테스트 결과를 보고한다. 규칙: - 수정 전에는 반드시 수정 예정 파일을 먼저 보여준다. - 대규모 변경은 내 확인 후 진행한다. - 확인하지 못한 정보는 추측하지 말고 UNKNOWN으로 표시한다.

    06Claude 1차 분석용 명령문

    Claude Code에게 먼저 코드베이스 분석만 시켜줘. 목표: [문제 또는 기능 설명] Claude가 해야 할 일: 1. 관련 파일 찾기 2. 현재 코드 흐름 설명 3. 문제 원인 후보 정리 4. 수정 가능 지점 정리 5. 위험한 변경 포인트 표시 6. 테스트해야 할 항목 정리 금지: - 아직 파일 수정하지 말 것 - 추측으로 원인 확정하지 말 것 - 대규모 리팩터링 제안부터 하지 말 것 - 확인하지 못한 정보는 UNKNOWN으로 표시할 것 출력 형식: [Claude 1차 분석] 관련 파일: 원인 후보: 수정 후보: 위험 요소: 테스트 필요 항목: GPT / Codex 검토가 필요한 질문:

    07GPT / Codex 검토용 명령문

    아래 Claude Code의 분석을 GPT / Codex가 검토해줘. 검토할 내용: [Claude 분석 붙여넣기] GPT / Codex가 해야 할 일: 1. Claude 분석의 논리 오류 찾기 2. 빠진 원인 후보 찾기 3. 수정 방향이 과한지 검토 4. 더 작은 변경으로 해결 가능한지 판단 5. 테스트 전략 보완 6. Claude에게 줄 최종 수정 지시문 작성 출력 형식: [GPT / Codex 검토] Claude 분석 평가: 누락된 가능성: 논리적 위험: 권장 수정 전략: 수정 범위: 테스트 전략: [Claude에게 줄 최종 지시문]

    08Claude 최종 코드 작성 명령문

    아래 GPT / Codex의 최종 지시문을 기준으로 Claude Code가 실제 코드를 수정해줘. 최종 지시문: [GPT / Codex 지시문 붙여넣기] Claude Code 규칙: 1. 지시문 범위를 벗어난 수정은 하지 않는다. 2. 수정 전 변경 예정 파일 목록을 보여준다. 3. 변경 이유를 파일별로 짧게 설명한다. 4. 실제 수정 후 테스트를 실행한다. 5. 테스트를 실행할 수 없으면 이유를 UNKNOWN 또는 BLOCKED로 표시한다. 6. 수정 결과를 diff 중심으로 요약한다. 출력 형식: [수정 전 계획] 변경 파일: 변경 이유: 리스크: [수정 결과] 변경 파일: 핵심 변경: 테스트 결과: 남은 문제: 추가 확인 필요:

    09Gemini 디자인 검토 명령문

    Gemini는 디자인과 시각 구조에 특화해서 사용한다.

    Gemini에게 아래 화면 또는 문서의 디자인을 검토시켜줘. 대상: [화면 설명 / 문서 / UI 코드 / 마크다운] Gemini가 해야 할 일: 1. 사용자가 처음 봤을 때 이해하기 쉬운지 평가 2. 정보 배치가 자연스러운지 검토 3. 버튼, 입력창, 카드, 표, 여백 구조 개선안 제안 4. 모바일과 데스크톱에서 불편할 지점 찾기 5. 문구를 더 명확하게 바꾸기 6. 디자인 개선안을 코드가 아니라 설명 중심으로 제안 금지: - 핵심 비즈니스 로직 판단 금지 - 보안 로직 판단 금지 - 복잡한 상태 관리 구조 판단 금지 - 최종 코드 수정 지시문 작성 금지 출력 형식: [Gemini 디자인 검토] 좋은 점: 불편한 점: 개선 제안: 우선순위: Claude에게 전달할 UI 수정 요청:

    10코드 + 디자인 혼합 작업 흐름

    UI 기능을 만들 때는 아래 순서를 사용한다:

    1Claude Code 현재 UI 코드 구조 분석, 관련 컴포넌트와 상태 흐름 파악, 아직 수정하지 않음
    2GPT / Codex 기능 요구사항을 코드 전략으로 정리, 상태 관리·API 연결·예외 처리 검토, Claude에게 줄 구현 지시문 작성
    3Gemini 화면 구성, 버튼 배치, 사용자 흐름 검토, 문구와 시각적 구조 개선안 작성
    4Claude Code GPT / Codex 지시문과 Gemini 디자인 요청을 합쳐 실제 구현, 파일 수정, 테스트 실행
    5GPT / Codex 최종 diff 검토, 논리 오류와 누락된 예외 처리 확인

    복붙용 명령문:

    이 UI 기능을 아래 순서로 처리해줘. 작업: [UI 기능 설명] 1단계 Claude: - 현재 UI 코드와 관련 파일을 분석한다. - 아직 수정하지 않는다. 2단계 GPT / Codex: - Claude 분석을 검토한다. - 상태 관리, API, 예외 처리 전략을 만든다. - Claude에게 줄 구현 지시문을 작성한다. 3단계 Gemini: - 화면 구성과 사용자 흐름을 검토한다. - 디자인 개선안을 작성한다. 4단계 Claude: - GPT / Codex의 구현 지시문과 Gemini의 디자인 개선안을 기준으로 실제 코드를 수정한다. - 수정 후 테스트한다. 5단계 GPT / Codex: - 최종 변경 내용을 논리적으로 검토한다.

    11provider 선택 기준

    Claude Code를 먼저 쓰는 경우
    코드베이스 구조를 읽어야 할 때, 여러 파일 관계를 파악해야 할 때, 실제 파일 수정이 필요할 때, 테스트 실행이 필요할 때, 리팩터링 적용이 필요할 때
    GPT / Codex를 먼저 쓰는 경우
    구현 전략이 불명확할 때, Claude의 분석을 검토해야 할 때, 논리적 허점이 걱정될 때, 테스트 전략이 필요할 때, 큰 변경 전에 설계 판단이 필요할 때
    Gemini를 먼저 쓰는 경우
    UI/UX 화면 구성이 핵심일 때, 랜딩페이지 문구가 필요할 때, 문서 구조를 보기 좋게 정리해야 할 때, 카드·표·버튼·섹션 배치가 중요할 때, 디자인 초안이 필요할 때

    12한도 절약 모드

    지금부터 한도 절약 모드로 운영해줘. 역할 제한: GPT / Codex: - 코드 전략 검토와 논리 검증에만 사용 - 장문 설명은 줄이고 핵심 판단만 한다 Claude Code: - 실제 코드 수정이 필요한 경우에만 사용 - 분석만 필요한 작업에는 길게 사용하지 않는다 - 수정 전 반드시 범위를 좁힌다 Gemini: - 디자인, 문서 구조, 짧은 초안에만 사용 - 복잡한 코드 판단에는 사용하지 않는다 공통 규칙: - provider 사용량을 모르면 UNKNOWN으로 표시한다. - 대형 작업은 자동 실행하지 않는다. - 추가 비용이 발생할 수 있으면 먼저 물어본다. - 모든 provider 전환 이유를 한 줄로 기록한다.

    13작업 전 provider 판단 명령문

    이 작업을 처리하기 전에 먼저 provider 역할을 나눠줘. 작업: [작업 내용] 판단 기준: - 코드베이스 분석은 Claude Code - 코드 전략과 논리 검증은 GPT / Codex - 실제 파일 수정은 Claude Code - UI/UX와 디자인 검토는 Gemini - 최종 논리 검토는 GPT / Codex 출력 형식: 작업 유형: 1차 provider: 검토 provider: 실행 provider: 디자인 provider: 선택 이유: 한도 상태: 진행 순서:

    14실제 예시: 로그인 오류 수정

    사용자 명령:

    내 프로젝트에서 로그인 후 세션이 유지되지 않는 문제가 있다. 바로 수정하지 말고 아래 흐름으로 처리해줘. 1. Claude Code가 관련 파일을 분석한다. 2. GPT / Codex가 Claude 분석을 검토한다. 3. GPT / Codex가 최종 수정 지시문을 작성한다. 4. Claude Code가 실제 코드를 수정한다. 5. Claude Code가 테스트를 실행한다. 6. GPT / Codex가 최종 변경 내용을 검토한다. 주의: - 수정 전 변경 예정 파일을 먼저 보여줘. - 인증, 쿠키, 세션, 환경 변수 관련 위험을 반드시 확인해줘.

    좋은 응답 예시:

    작업 유형: 인증 버그 수정 1차 provider: Claude Code 검토 provider: GPT / Codex 실행 provider: Claude Code 디자인 provider: 사용하지 않음 선택 이유: 이 작업은 코드베이스 분석과 실제 파일 수정이 필요하므로 Claude Code가 분석과 실행을 맡고, 세션 로직의 누락 가능성은 GPT / Codex가 검토하는 방식이 안전하다. 진행 순서: 1. Claude Code로 인증 관련 파일 분석 2. GPT / Codex로 분석 검토 3. Claude용 수정 지시문 생성 4. Claude Code로 수정 5. 테스트 실행 6. GPT / Codex로 최종 검토

    15실제 예시: 대시보드 UI 개선

    사용자 명령:

    내 트레이딩 대시보드 UI를 개선하고 싶다. 아래 흐름으로 처리해줘. 1. Claude Code가 현재 UI 컴포넌트 구조를 분석한다. 2. Gemini가 화면 구성과 사용자 흐름을 검토한다. 3. GPT / Codex가 구현 전략과 상태 관리 위험을 검토한다. 4. Claude Code가 실제 코드를 수정한다. 5. GPT / Codex가 최종 변경 내용을 검토한다. 디자인 기준: - 포지션 상태가 한눈에 보여야 함 - 리스크 알림이 가장 먼저 보여야 함 - 모바일에서도 핵심 정보가 안 밀려야 함 - 색상보다 구조와 우선순위를 먼저 개선해야 함

    좋은 응답 예시:

    작업 유형: UI/UX 개선 + 코드 수정 1차 provider: Claude Code 디자인 provider: Gemini 전략 검토 provider: GPT / Codex 실행 provider: Claude Code 선택 이유: 현재 UI 코드 구조는 Claude Code가 읽고, 화면 배치와 정보 우선순위는 Gemini가 검토하며, 상태 관리와 구현 위험은 GPT / Codex가 검증하는 흐름이 적합하다.

    16실제 예시: 리팩터링 작업

    이 리팩터링 작업은 바로 수정하지 말고 아래 순서로 진행해줘. 작업: [리팩터링 대상 설명] 1단계 Claude Code: - 현재 구조 분석 - 중복 코드 확인 - 의존성 확인 - 수정 범위 제안 - 아직 수정하지 않음 2단계 GPT / Codex: - Claude 분석 검토 - 과한 리팩터링 여부 판단 - 작은 변경 단위로 쪼개기 - 테스트 전략 작성 - Claude에게 줄 최종 지시문 작성 3단계 Claude Code: - 1차 리팩터링만 적용 - 테스트 실행 - 변경 내역 보고 4단계 GPT / Codex: - 변경 결과 검토 - 다음 리팩터링 단계 진행 여부 판단

    17최종 검토 체크리스트

    작업 완료 후 GPT / Codex가 아래 기준으로 최종 검토해줘. 검토 항목: 1. 원래 요구사항을 만족했는가 2. 불필요한 파일 수정이 있었는가 3. 인증, 결제, 데이터 삭제, 주문 실행 등 위험 로직을 건드렸는가 4. 테스트가 실행되었는가 5. 테스트가 실패했다면 실패 원인이 설명되었는가 6. 예외 처리가 누락되지 않았는가 7. UI 변경이 있다면 Gemini 디자인 검토가 반영되었는가 8. 추가 수정이 필요한가 출력 형식: [최종 검토] 요구사항 충족: 변경 범위: 위험 요소: 테스트 결과: 남은 문제: 추가 권장 작업:

    18트레이딩 보조 에이전트용 운영 규칙

    너는 트레이딩 보조 에이전트의 개발 라우터다. provider 역할: GPT / Codex: - 전략 로직 검토 - 리스크 계산 로직 검증 - 주문 조건 논리 검토 - 백테스트 해석 검토 - Claude 수정안 검증 Claude Code: - 실제 코드 작성 - 전략 코드 수정 - 백테스트 스크립트 수정 - 테스트 실행 - 로그 확인 Gemini: - 대시보드 UI 디자인 - 리스크 카드 구성 - 알림 화면 구성 - 보고서 레이아웃 - 매매일지 템플릿 디자인 강제 안전 규칙: - 매수·매도 주문을 자동 실행하지 않는다. - 거래소 API 키에 출금 권한을 주지 않는다. - 실거래 로직 수정 전에는 반드시 GPT / Codex 검토를 거친다. - 주문 수량, 레버리지, 손절, 익절 계산 로직은 Claude 단독으로 확정하지 않는다. - Gemini는 트레이딩 판단이나 주문 로직 검증에 사용하지 않는다.

    19하루 운영 루틴

    아침 시작 명령:

    오늘 작업 시작 전 GPT / Codex, Claude Code, Gemini 상태를 점검해줘. 확인할 항목: - 로그인 상태 - 실행 가능 여부 - 최근 에러 - 사용량 한도 - 추가 비용 가능성 - 오늘 권장 역할 확인하지 못한 항목은 UNKNOWN으로 표시해줘. 마지막에 오늘의 기본 라우팅을 정리해줘. 형식: GPT / Codex: - 상태: - 사용량: - 오늘 역할: - 주의사항: Claude Code: - 상태: - 사용량: - 오늘 역할: - 주의사항: Gemini: - 상태: - 사용량: - 오늘 역할: - 주의사항: 오늘의 기본 흐름: 1. 2. 3.

    작업 전 명령:

    이 작업을 바로 실행하지 말고 provider를 먼저 나눠줘. - 분석: - 전략 검토: - 실제 코드 수정: - 디자인 검토: - 최종 검토: 각 provider 선택 이유를 한 줄씩 설명한 뒤 진행해줘.

    하루 종료 명령:

    오늘 사용한 provider별 작업 내역을 정리해줘. 형식: - GPT / Codex가 검토한 작업 - Claude Code가 수정한 작업 - Gemini가 디자인한 작업 - provider 전환이 발생한 작업 - 한도 때문에 보류한 작업 - 내일 개선할 운영 규칙

    20최종 고정 프롬프트

    이 문장을 에이전트의 고정 운영 프롬프트로 사용한다.

    너는 GPT / Codex, Claude Code, Gemini를 함께 사용하는 AI 개발 라우터다. 기본 역할은 다음과 같다. GPT / Codex: - 코드 전략 분석 - 논리 검증 - Claude 분석 검토 - Claude에게 줄 재지시문 작성 - 최종 변경 검토 Claude Code: - 코드베이스 분석 - 실제 코드 작성 - 파일 수정 - 테스트 실행 - 리팩터링 적용 Gemini: - UI/UX 디자인 검토 - 화면 구성 제안 - 문서 디자인 - 시각적 개선안 작성 작업 처리 원칙: 1. 코드 작업은 Claude 단독으로 바로 수정하지 않는다. 2. Claude가 먼저 코드베이스를 분석한다. 3. GPT / Codex가 Claude의 분석을 검토한다. 4. GPT / Codex가 Claude에게 줄 최종 수정 지시문을 만든다. 5. Claude가 실제 코드를 수정한다. 6. GPT / Codex가 최종 변경 내용을 검토한다. 7. 디자인이 포함된 작업은 Gemini가 UI/UX 개선안을 작성한다. 8. Gemini는 복잡한 코드 논리나 트레이딩 판단의 최종 검증자로 사용하지 않는다. 9. 사용량이나 한도 상태를 모르면 UNKNOWN으로 표시한다. 10. 추가 비용이 발생할 수 있는 fallback은 사용자 승인 후에만 사용한다. 11. 한도 우회를 목적으로 provider나 계정을 돌려쓰지 않는다. 12. 중요한 작업은 실행 전 provider 선택 이유를 먼저 말한다. 기본 응답 형식: 작업 유형: 1차 분석 provider: 전략 검토 provider: 실행 provider: 디자인 provider: 최종 검토 provider: 선택 이유: 한도 상태: 진행 순서:

    21이 단원의 핵심 정리

    첫 번째 원칙
    Claude에게 바로 코드를 맡기지 않는다
    두 번째 원칙
    Claude가 먼저 읽고, GPT / Codex가 판단하고, Claude가 다시 실행한다
    세 번째 원칙
    Gemini는 디자인과 시각 구조를 맡는다

    초보자는 아래 3문장만 기억하면 된다.

    1
    Claude는 코드베이스를 읽고 실제 코드를 고친다
    2
    GPT / Codex는 전략과 논리를 검토한다
    3
    Gemini는 디자인과 화면 구조를 정리한다

    실전 명령문:

    이 작업을 바로 실행하지 말고, 먼저 Claude Code로 코드 구조를 분석하고, 그 분석을 GPT / Codex가 검토한 뒤, GPT / Codex가 만든 최종 지시문을 기준으로 Claude Code가 실제 코드를 수정해줘. 디자인이 포함된 작업이면 Gemini에게 UI/UX 검토를 맡기고, Gemini의 결과는 Claude가 구현할 수 있는 수정 요청으로 정리해줘.

    10. 자동 실행 설정하기

    01이 단원에서 하는 일

    이 단원에서는 Mac mini를 재부팅한 뒤 NanoClaw, Hermes Agent, HermesClaw, OpenClaw gateway가 자동으로 다시 실행되도록 설정합니다.

    하지만 자동 실행은 설치 직후 바로 켜는 기능이 아닙니다. 8단원에서 아래 항목을 먼저 통과해야 합니다:

    이 조건을 통과하지 못한 상태에서 자동 실행을 켜면 문제가 더 복잡해집니다.

    02수동 실행이 불안정할 때의 위험

    나쁜 예: 수동 실행도 불안정한데 자동 실행을 켠다

    그 결과:

    이 단원의 목표는 자동 실행이 왜 필요한지 이해하고, Docker restart policy와 launchd의 역할을 구분하며, 재부팅 후 agent가 다시 살아나는지 확인하는 것입니다.

    03왜 자동 실행이 필요한가?

    Mac mini를 AI 자동화 서버처럼 쓰려면 재부팅 후 수동으로 명령어를 다시 치는 구조는 위험합니다.

    자동 실행이 필요한 이유:

    04자동 실행 대상과 피해야 할 것

    자동 실행 대상:

    자동 실행하면 안 되는 것:

    자동 실행의 목적은 설치를 반복하는 것이 아니라, 이미 검증된 실행 상태로 되돌리는 것입니다.

    05자동 실행 방식 세 가지

    Mac mini에서 자동 실행은 보통 세 가지 방식 중 하나를 씁니다:

    Docker restart policy
    Docker 컨테이너가 꺼졌을 때 다시 올리는 역할
    도구 자체 gateway service
    OpenClaw처럼 CLI가 제공하는 service install/start/status 기능을 쓰는 방식
    launchd
    macOS가 로그인 또는 부팅 후 특정 명령을 실행하게 만드는 방식

    06초보자 기준 추천 순서

    Docker 컨테이너 기반:

    1. Docker restart policy부터 사용
    2. Docker Desktop이 재부팅 후 실행되는지 확인
    3. 부족할 때만 launchd 보조 사용

    OpenClaw gateway 기반:

    1. openclaw gateway install 또는 onboard --install-daemon 사용
    2. openclaw gateway status로 확인
    3. launchd plist를 직접 만들기 전에 공식 CLI 기능을 우선 사용

    Hermes Agent / HermesClaw 일반 프로세스 기반:

    1. 수동 실행 명령을 RUNBOOK.md에 기록
    2. start script 작성
    3. launchd LaunchAgent로 실행
    같은 agent를 Docker restart policy와 launchd로 동시에 직접 재시작하게 만들지 않습니다.

    07중복 자동 실행의 결과

    중복 자동 실행은 실무에서 가장 많이 만드는 장애 원인입니다:

    08현재 실행 방식을 RUNBOOK으로 기록하기

    자동 실행을 설정하기 전에 수동 실행 명령을 정확히 알아야 합니다. 각 프로젝트 폴더에 RUNBOOK.md가 있는지 확인합니다:

    find ~/ai-agents/projects -maxdepth 3 -name "RUNBOOK.md"

    없다면 만듭니다:

    nano ~/ai-agents/projects/RUNBOOK-AUTOSTART.md

    아래 형식으로 기록합니다. NanoClaw, Hermes Agent, HermesClaw, OpenClaw의 설치 위치, 수동 실행 명령, 상태 확인 명령어를 각각 적습니다.

    09재부팅 전 상태 저장하기

    자동 실행을 설정하기 전, 현재 상태를 저장합니다:

    mkdir -p ~/ai-agents/checks/autostart

    Docker 상태:

    docker ps -a > ~/ai-agents/checks/autostart/docker-ps-a-before-autostart.txt

    프로세스 상태:

    ps aux | grep -Ei 'nanoclaw|hermes|openclaw|gateway' > ~/ai-agents/checks/autostart/process-before-autostart.txt

    포트 상태, OpenClaw 상태, Hermes 상태도 마찬가지로 저장합니다.

    10Docker 컨테이너 restart policy 확인

    Docker 기반 agent는 Docker restart policy를 먼저 확인합니다. 전체 컨테이너의 restart policy를 확인합니다:

    docker inspect --format '{{.Name}} {{.HostConfig.RestartPolicy.Name}}' $(docker ps -aq)

    결과 예시:

    /nanoclaw-agent unless-stopped /nanoclaw-db no /hermes-gateway always

    no는 자동 재시작 정책이 없는 상태입니다.

    11컨테이너에 restart policy 적용

    특정 컨테이너에 적용합니다:

    docker update --restart unless-stopped 컨테이너이름

    예시:

    docker update --restart unless-stopped nanoclaw-agent

    여러 실행 중인 컨테이너에 한 번에 적용할 수도 있습니다:

    docker update --restart unless-stopped $(docker ps -q)

    하지만 초보자는 한 번에 전체 적용하기보다 컨테이너 이름을 확인한 뒤 필요한 것만 적용하는 편이 안전합니다.

    12always와 unless-stopped 차이

    초보자에게는 보통 unless-stopped가 더 안전합니다:

    always
    컨테이너가 멈추면 계속 다시 시작하려고 함. 수동으로 멈춘 경우에도 Docker daemon 재시작 후 다시 살아날 수 있음
    unless-stopped
    컨테이너가 멈추면 다시 시작하지만, 사용자가 의도적으로 멈춘 상태는 Docker 재시작 후에도 유지함

    운영용 Mac mini에서는 보통 unless-stopped를 권장합니다.

    13Docker Compose 파일에 restart policy 추가

    Compose 기반이면 compose.yaml 또는 docker-compose.yml에 아래처럼 추가합니다:

    services: agent: image: your-agent-image restart: unless-stopped

    이미 service가 여러 개라면 필요한 service마다 지정합니다. Compose 파일을 수정한 뒤에는 단순 docker compose restart만으로 설정 변경이 반영되지 않을 수 있으므로, 보통 아래처럼 다시 올립니다:

    docker compose up -d

    14Docker Desktop이 켜지는지 확인

    Mac에서 Docker 컨테이너 자동 재시작은 Docker 자체가 실행되어야 의미가 있습니다. 재부팅 후 아래 명령을 확인합니다:

    docker info

    아래 오류가 나오면 Docker Desktop이 아직 켜지지 않은 것입니다:

    Cannot connect to the Docker daemon

    확인할 것:

    15Docker restart policy 적용 후 테스트

    컨테이너 하나를 테스트 대상으로 잡습니다:

    docker ps --format "table {{.Names}}\t{{.Status}}"

    정지:

    docker stop 컨테이너이름

    unless-stopped는 사용자가 수동으로 멈춘 컨테이너를 즉시 다시 살리는 정책이 아닙니다. 이 정책은 Docker daemon 또는 시스템 재시작 상황에서 의미가 있습니다. 재시작 정책을 확인합니다:

    docker inspect --format '{{.Name}} {{.HostConfig.RestartPolicy.Name}}' 컨테이너이름

    16OpenClaw gateway 자동 실행 설정

    OpenClaw를 사용하는 경우에는 launchd plist를 직접 만들기 전에 OpenClaw가 제공하는 gateway service 명령을 먼저 사용합니다:

    openclaw gateway status

    gateway service 설치:

    openclaw onboard --install-daemon

    또는:

    openclaw gateway install

    설치 후 시작:

    openclaw gateway start
    OpenClaw는 자체 gateway service 관리 명령이 있으므로, 초보자는 직접 plist를 작성하기보다 OpenClaw CLI의 install/status/restart 흐름을 우선 사용합니다.

    17launchd 소개: LaunchAgent와 LaunchDaemon

    Docker restart policy나 도구 자체 service로 해결되지 않는 일반 프로세스는 macOS launchd로 자동 실행할 수 있습니다. launchd는 macOS에서 백그라운드 작업을 시작하고 관리하는 기본 방식입니다.

    초보자는 보통 LaunchAgent를 씁니다:

    LaunchAgent
    사용자 로그인 세션에서 실행. 위치: ~/Library/LaunchAgents. 개인 Mac mini 운영에 적합
    LaunchDaemon
    시스템 레벨에서 실행. 위치: /Library/LaunchDaemons. root 권한과 파일 소유권 관리 필요. 초보자에게는 권장하지 않음

    이 가이드에서는 사용자 계정 기준 LaunchAgent만 다룹니다.

    18자동 실행용 start script 만들기

    launchd plist에 긴 명령어를 직접 넣기보다 start script를 따로 만듭니다:

    mkdir -p ~/ai-agents/bin

    Hermes gateway 시작 스크립트:

    nano ~/ai-agents/bin/start-hermes-gateway.sh

    스크립트 내용:

    #!/bin/zsh set -euo pipefail export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" echo "[$(date)] starting hermes gateway" hermes gateway start

    실행 권한 부여:

    chmod +x ~/ai-agents/bin/start-hermes-gateway.sh

    19Docker Compose용 start script 예시

    Docker Compose 기반 프로젝트라면 아래처럼 만듭니다:

    nano ~/ai-agents/bin/start-nanoclaw-compose.sh

    스크립트 내용:

    #!/bin/zsh set -euo pipefail export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" cd "$HOME/ai-agents/projects/nanoclaw-v2" echo "[$(date)] starting docker compose project" docker compose up -d

    실행 권한:

    chmod +x ~/ai-agents/bin/start-nanoclaw-compose.sh

    20docker compose up -d와 launchd 역할 분리

    이 방식을 쓸 때는 Docker restart policy와 역할이 겹치지 않는지 확인합니다:

    권장 구조
    launchd는 docker compose up -d를 1회 실행. 컨테이너 재시작은 Docker restart policy가 담당
    피해야 할 구조
    launchd가 컨테이너를 계속 감시하고, Docker restart policy도 동시에 계속 재시작함

    21LaunchAgent plist 폴더와 파일 생성

    LaunchAgent 폴더를 만듭니다:

    mkdir -p ~/Library/LaunchAgents

    Hermes gateway용 plist를 만듭니다:

    nano ~/Library/LaunchAgents/com.aiagents.hermes-gateway.plist

    22LaunchAgent plist 내용 (1/2)

    plist 파일 내용:

    Label com.aiagents.hermes-gateway ProgramArguments /Users/사용자이름/ai-agents/bin/start-hermes-gateway.sh RunAtLoad KeepAlive

    23LaunchAgent plist 내용 (2/2)

    plist 파일 나머지:

    StandardOutPath /Users/사용자이름/ai-agents/logs/hermes-gateway.out.log StandardErrorPath /Users/사용자이름/ai-agents/logs/hermes-gateway.err.log WorkingDirectory /Users/사용자이름/ai-agents

    중요: /Users/사용자이름은 실제 사용자 이름으로 바꿔야 합니다.

    24사용자 이름과 경로 확인

    현재 사용자 이름 확인:

    whoami

    홈 디렉터리 확인:

    echo $HOME

    로그 폴더 생성:

    mkdir -p ~/ai-agents/logs

    plist 문법 확인:

    plutil -lint ~/Library/LaunchAgents/com.aiagents.hermes-gateway.plist

    정상 예시:

    /Users/사용자이름/Library/LaunchAgents/com.aiagents.hermes-gateway.plist: OK

    25LaunchAgent 등록하기

    macOS의 현재 사용자 세션에 등록합니다:

    launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.aiagents.hermes-gateway.plist

    이미 등록되어 있다는 오류가 나오면 먼저 내립니다:

    launchctl bootout gui/$UID ~/Library/LaunchAgents/com.aiagents.hermes-gateway.plist

    다시 등록:

    launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.aiagents.hermes-gateway.plist

    즉시 실행:

    launchctl kickstart -k gui/$UID/com.aiagents.hermes-gateway

    26LaunchAgent 상태 확인과 로그 보기

    상태 확인:

    launchctl list | grep com.aiagents.hermes-gateway

    stdout 로그 확인:

    tail -n 100 ~/ai-agents/logs/hermes-gateway.out.log

    stderr 로그 확인:

    tail -n 100 ~/ai-agents/logs/hermes-gateway.err.log

    27KeepAlive를 처음부터 켜지 않는 이유

    위 예시에서는 KeepAlive를 false로 두었습니다. 초보자에게 처음부터 KeepAlive를 true로 권하지 않는 이유:

    먼저 RunAtLoad로 로그인 시 한 번 실행되게 만들고, 안정성이 확인된 뒤 필요할 때만 KeepAlive를 검토합니다. Docker 컨테이너는 Docker restart policy가 담당하고, launchd는 docker compose up -d를 한 번 호출하는 정도로 제한하는 편이 안전합니다.

    28자동 실행 후 재부팅 전 상태 저장

    자동 실행 설정 후에는 반드시 재부팅 테스트를 합니다. 재부팅 전 상태를 저장합니다:

    mkdir -p ~/ai-agents/checks/autostart
    date > ~/ai-agents/checks/autostart/reboot-test-time.txt

    Docker 상태:

    docker ps -a > ~/ai-agents/checks/autostart/docker-before-reboot.txt

    launchd 상태, 프로세스 상태, 포트 상태도 저장합니다.

    29재부팅과 재부팅 후 상태 확인

    재부팅:

    sudo shutdown -r now

    메뉴에서 재시동해도 됩니다: Apple 메뉴 → 재시동

    재부팅 후 상태 확인:

    docker ps -a > ~/ai-agents/checks/autostart/docker-after-reboot.txt
    launchctl list | grep -Ei 'aiagents|nanoclaw|hermes|openclaw|gateway' > ~/ai-agents/checks/autostart/launchctl-after-reboot.txt

    30재부팅 전후 비교와 정상 기준

    차이 비교:

    diff -u ~/ai-agents/checks/autostart/docker-before-reboot.txt ~/ai-agents/checks/autostart/docker-after-reboot.txt
    diff -u ~/ai-agents/checks/autostart/process-before-reboot.txt ~/ai-agents/checks/autostart/process-after-reboot.txt

    정상 기준:

    31자동 실행이 안 될 때: plist 문법과 등록 여부 확인

    plist 문법 확인:

    plutil -lint ~/Library/LaunchAgents/com.aiagents.hermes-gateway.plist

    정상이 아니면 먼저 plist를 고칩니다.

    등록 여부 확인:

    launchctl list | grep com.aiagents.hermes-gateway

    아무것도 나오지 않으면 등록되지 않은 것입니다. 다시 등록합니다:

    launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.aiagents.hermes-gateway.plist

    32자동 실행 실패 원인 진단: 즉시 실행과 스크립트 검증

    즉시 실행 테스트:

    launchctl kickstart -k gui/$UID/com.aiagents.hermes-gateway

    로그 확인:

    tail -n 100 ~/ai-agents/logs/hermes-gateway.out.log
    tail -n 100 ~/ai-agents/logs/hermes-gateway.err.log

    수동 실행 확인:

    ~/ai-agents/bin/start-hermes-gateway.sh

    수동 실행도 실패하면 launchd 문제가 아닙니다.

    33실행 권한과 PATH 문제 확인

    실행 권한 확인:

    ls -la ~/ai-agents/bin/start-hermes-gateway.sh

    실행 권한이 없으면 부여합니다:

    chmod +x ~/ai-agents/bin/start-hermes-gateway.sh

    PATH 확인:

    grep PATH ~/ai-agents/bin/start-hermes-gateway.sh

    스크립트에 PATH를 명시했는지 확인합니다:

    export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH"

    명령어 위치를 확인합니다: which hermes, which docker, which openclaw

    34Docker Desktop과 포트 충돌 문제

    Docker Desktop 문제 확인:

    docker info

    Docker 기반 자동 실행이 실패하면 먼저 Docker가 살아 있는지 확인합니다. Docker가 늦게 뜨는 환경에서는 start script에 대기 루프를 넣을 수 있습니다.

    포트 충돌 확인:

    lsof -nP -iTCP -sTCP:LISTEN | grep -Ei '18789|19998|19999'

    이미 다른 프로세스가 포트를 쓰고 있으면 자동 실행이 실패할 수 있습니다.

    35중복 자동 실행 확인

    Docker restart policy와 launchd가 같은 대상을 중복으로 관리하는지 확인합니다.

    Docker policy 확인:

    docker inspect --format '{{.Name}} {{.HostConfig.RestartPolicy.Name}}' $(docker ps -aq)

    LaunchAgent 확인:

    launchctl list | grep -Ei 'nanoclaw|hermes|openclaw|gateway|aiagents'

    프로세스 확인:

    ps aux | grep -Ei 'nanoclaw|hermes|openclaw|gateway' | grep -v grep

    36초보자가 하지 말아야 할 것

    37특히 피해야 할 명령어들

    삭제 명령은 절대 하지 말기:

    # 이 명령들은 초보자가 바로 쓰지 않는다 sudo rm -rf /Library/LaunchDaemons/* launchctl bootout system/* docker rm -f $(docker ps -aq) kill -9 $(ps aux | grep gateway | awk '{print $2}')

    삭제보다 먼저 해야 할 것: 상태 확인과 백업입니다.

    38자동 실행 설정 완료 체크리스트

    사전 조건:

    Docker 설정:

    39체크리스트 계속 (OpenClaw와 launchd)

    OpenClaw 설정:

    launchd 설정:

    40체크리스트 마지막 (재부팅과 안전)

    재부팅 테스트:

    보안과 안정성:

    41이 단원의 핵심 정리

    자동 실행은 agent를 더 똑똑하게 만드는 기능이 아니라, 검증된 실행 상태로 다시 돌아오게 만드는 운영 장치입니다.

    가장 중요한 원칙 6가지:

    1. 수동 실행이 안정된 뒤 자동 실행을 켠다
    2. Docker 컨테이너는 Docker restart policy를 우선 사용한다
    3. OpenClaw는 자체 gateway service 명령을 우선 사용한다
    4. 일반 프로세스는 launchd LaunchAgent로 관리한다
    5. 같은 agent를 두 방식으로 중복 관리하지 않는다
    6. 재부팅 후 메시지 수신과 발신까지 확인한다

    42자동 실행 성공의 기준

    초보자가 기억할 문장은 하나입니다:

    자동 실행 설정의 성공 기준은 Mac이 켜졌다는 것이 아니라, 재부팅 후에도 agent가 중복 없이 실행되고 메시지를 정상적으로 주고받는 것입니다.

    10단원을 통과하면 Mac mini는 개인 AI agent를 24시간 운영하기 위한 기본 복구 구조를 갖춘 상태가 됩니다. 다음 단계에서는 보안 설정, 로그 관리, 업데이트 전 백업, 장애 복구 절차를 더 엄격하게 정리해야 합니다.

    11. 보안 설정

    01이 단원에서 하는 일

    이 단원에서는 Mac mini에서 NanoClaw, Hermes Agent, HermesClaw, OpenClaw 같은 AI 에이전트를 운영할 때 반드시 확인해야 하는 보안 설정을 다룬다.

    AI 에이전트는 일반 프로그램보다 보안 위험이 크다. 에이전트가 접근할 수 있는 것들을 살펴보면:

    에이전트가 잘못 설정되면 API 키 유출, 예상치 못한 API 과금, 메시징 계정 정지, 개인 대화 노출, 로컬 파일 삭제, 외부에서 Mac mini 접근, Docker를 통한 파일 접근, 로그에 토큰이 남을 수 있다.

    편의성보다 피해 범위를 줄이는 것이 우선이다.

    02API 키를 안전하게 보관하는 법

    API 키를 코드에 직접 쓰지 않는다

    나쁜 예:

    ANTHROPIC_API_KEY = "sk-ant-..." OPENAI_API_KEY = "sk-..."

    좋은 방향:

    provider별로 키를 분리한다

    용도별로 나누면 문제가 생겼을 때 특정 키만 끊을 수 있다:

    API 키가 설정되어 있는지 확인하기

    키 값을 직접 출력하지 말고, 설정 여부만 확인한다:

    test -n "$ANTHROPIC_API_KEY" && echo "ANTHROPIC_API_KEY is set" || echo "ANTHROPIC_API_KEY is not set"

    전체 관련 변수는 마스킹해서 확인한다:

    env | grep -Ei 'ANTHROPIC|OPENAI|GEMINI|GOOGLE|API_KEY|TOKEN' | sed 's/=.*/=***REDACTED***/'

    절대 이런 식으로 하지 않는다:

    echo $ANTHROPIC_API_KEY

    화면 공유나 로그 복사 중 키가 노출될 수 있다.

    03API 키를 파일에 저장해야 하는 경우

    초보자 환경에서는 .env 파일을 쓰는 경우가 많다.

    파일 권한을 제한한다

    chmod 600 ~/ai-agents/secrets/agent.env

    권한 확인:

    ls -la ~/ai-agents/secrets/agent.env

    정상 예시: -rw-------는 소유자만 읽고 쓸 수 있다는 뜻이다.

    키가 유출됐을 때 해야 할 일

    API 키가 한 번이라도 외부에 노출되었다면 "가렸으니 괜찮다"고 판단하지 않는다:

    1. 해당 provider 콘솔에서 키를 revoke 또는 delete한다
    2. 새 키를 만든다
    3. .env 또는 secret 파일을 새 키로 바꾼다
    4. agent를 재시작한다
    5. 사용량 페이지에서 이상 호출이 있는지 확인한다
    6. 저장소에 올라갔다면 Git history 노출 여부를 확인한다

    주의: GitHub에 올라간 키는 파일을 삭제해도 history에 남을 수 있다. 이 경우 키 폐기가 먼저이고, history 정리는 그다음이다.

    04.env 파일 관리법

    .env 파일은 환경 변수를 한곳에 모아두는 파일이다. 하지만 민감하기 때문에 코드가 아니라 비밀 설정 파일로 다룬다.

    .env에 들어가기 쉬운 민감 정보:

    .gitignore에 반드시 추가하기

    .env .env.* *.env secrets/ *.key *.pem *.p12 *.pfx *.crt *.token *token* *secret* account.json credentials.json

    중요한 주의: .gitignore는 앞으로 추가되는 파일을 막는 장치다. 이미 Git이 추적 중인 파일은 .gitignore에 추가해도 자동으로 빠지지 않는다.

    이미 추적 중인지 확인:

    git ls-files | grep -Ei '(^|/).env|secret|token|credential|account.json'

    민감 파일을 Git 추적에서 제거하되, 로컬 파일은 남긴다:

    git rm --cached .env

    05.env.example과 권한 점검

    .env.example만 저장소에 올리기

    실제 .env 대신 예시 파일만 저장소에 올린다:

    ANTHROPIC_API_KEY= OPENAI_API_KEY= GEMINI_API_KEY= AGENT_MODE=test LOG_LEVEL=info

    원칙:

    권한 점검

    find ~/ai-agents -name ".env" -o -name "*.env" -exec chmod 600 {} ;

    로그에 .env 내용이 찍히지 않게 하기

    위험한 명령:

    cat .env docker logs 컨테이너이름

    마스킹해서 확인:

    sed 's/=.*/=***REDACTED***/' .env

    Docker 로그에서 키 패턴을 찾는다:

    docker logs --tail 500 컨테이너이름 2>&1 | grep -Ei 'sk-|api_key|token|secret|password|credential'

    06메시징 계정 분리하기

    실사용 계정과 테스트 계정을 나눈다

    AI 에이전트를 처음 연결할 때 실사용 메시징 계정을 바로 쓰면 안 된다. 분리해야 할 계정:

    권장 구조: local CLI 또는 테스트용 Telegram bot → 테스트 채팅방 → 운영 전용 계정 → 권한과 대상이 제한된 계정

    메시징 계정별 권한을 줄인다

    메시지 내용에 민감 정보를 보내지 않는다

    보내면 안 되는 것: API 키, 로그인 비밀번호, 2FA 코드, 세션 쿠키, 개인 신분증 정보, 거래소 API secret, SSH private key, .env 전체 내용

    문제를 진단할 때는 마스킹한다:

    07외부 접속 차단하기

    기본 정책

    개인 Mac mini에서 실행하는 AI 에이전트는 기본적으로 외부 인터넷에서 직접 접속할 수 없어야 한다:

    피해야 할 설정

    현재 열려 있는 포트 확인

    lsof -nP -iTCP -sTCP:LISTEN

    AI agent 관련 포트만 좁혀 본다:

    lsof -nP -iTCP -sTCP:LISTEN | grep -Ei 'nanoclaw|hermes|openclaw|claw|gateway|node|python|docker|18789|19998|19999'

    08Docker 포트와 방화벽 설정

    Docker 컨테이너 포트 확인

    docker ps --format "table {{.Names}}\t{{.Ports}}"

    위험한 예: 0.0.0.0:8080->8080/tcp

    상대적으로 안전한 예: 127.0.0.1:8080->8080/tcp

    Compose 파일에서 포트를 localhost에만 묶는 예:

    services: agent: ports: - "127.0.0.1:8080:8080"

    외부 공개가 필요 없으면 ports 자체를 제거하고 내부 통신만 쓰는 것이 낫다:

    services: agent: expose: - "8080"

    expose는 컨테이너 네트워크 내부에서만 의미가 있고, 호스트에 포트를 공개하지 않는다.

    macOS 방화벽 켜기

    Apple 메뉴 → System Settings → Network → Firewall → On

    명령어로 상태 확인:

    /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

    방화벽 켜기:

    sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate on

    stealth mode 켜기:

    sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setstealthmode on

    09공유기 포트 포워딩 확인

    공유기에서 Mac mini로 포트 포워딩을 해두면 macOS 방화벽만으로 충분하지 않을 수 있다.

    확인할 항목:

    권장:

    10컨테이너 권한 줄이기

    컨테이너 보안 원칙

    현재 컨테이너 사용자 확인

    docker exec 컨테이너이름 id

    출력이 uid=0(root) gid=0(root)이면 root로 실행 중이다.

    Compose에서 non-root 사용자 지정

    services: agent: image: your-agent-image user: "1000:1000"

    privileged 모드 사용 금지

    위험한 예:

    services: agent: privileged: true

    초보자 운영에서는 피한다. privileged: true는 컨테이너 권한을 크게 넓힌다.

    Docker socket mount 금지

    아래 설정은 매우 위험할 수 있다:

    volumes: - /var/run/docker.sock:/var/run/docker.sock

    Docker socket을 컨테이너에 주면 컨테이너가 다른 컨테이너를 제어하거나 호스트에 큰 영향을 줄 수 있다.

    11파일 접근 범위 제한하기

    agent가 읽을 수 있는 폴더를 제한한다

    나쁜 예:

    volumes: - ~/:/host - /:/host

    좋은 예:

    volumes: - ~/ai-agents/workspace:/workspace

    더 안전한 예(읽기 전용):

    volumes: - ~/ai-agents/workspace:/workspace:ro

    workspace 폴더 만들기

    agent가 작업할 폴더를 따로 만든다:

    mkdir -p ~/ai-agents/workspace/inbox mkdir -p ~/ai-agents/workspace/outbox mkdir -p ~/ai-agents/workspace/tmp mkdir -p ~/ai-agents/workspace/logs

    위험한 파일 패턴 접근 금지

    agent가 아래 파일을 읽거나 출력하지 않게 한다:

    삭제 명령 제한

    위험한 명령:

    rm -rf ~ rm -rf ~/ai-agents rm -rf / find . -type f -delete

    삭제가 필요하면 먼저 이동한다:

    mkdir -p ~/ai-agents/trash mv 대상파일 ~/ai-agents/trash/

    또는 타임스탐프를 붙여 보관한다:

    mv 대상폴더 대상폴더-disabled-$(date +%Y%m%d-%H%M%S)

    12업데이트 전 백업하기

    업데이트가 위험한 이유

    AI agent 프로젝트는 업데이트 후 갑자기 동작이 바뀔 수 있다:

    따라서 업데이트 전에는 반드시 현재 상태를 백업한다.

    업데이트 전 백업 폴더 만들기

    BACKUP_DIR=~/ai-agents/backups/before-update-$(date +%Y%m%d-%H%M%S) mkdir -p "$BACKUP_DIR"

    프로젝트 파일, Git, Docker 상태 저장

    find ~/ai-agents/projects -maxdepth 5 -type f > "$BACKUP_DIR/projects-file-list.txt" docker ps -a > "$BACKUP_DIR/docker-ps-a.txt" docker images > "$BACKUP_DIR/docker-images.txt"

    Compose 파일 백업

    mkdir -p "$BACKUP_DIR/compose-files" find ~/ai-agents/projects -type f \( -name "compose.yaml" -o -name "docker-compose.yaml" \) -exec cp {} "$BACKUP_DIR/compose-files/" \;

    민감 파일은 목록과 해시만 저장

    백업할 때 특히 조심한다:

    find ~/ai-agents -type f \( -name ".env" -o -name "*.env" -o -name "*token*" \) > "$BACKUP_DIR/sensitive-file-list.txt"

    해시만 저장한다:

    while read -r f; do shasum -a 256 "$f"; done < "$BACKUP_DIR/sensitive-file-list.txt" > "$BACKUP_DIR/sensitive-file-sha256.txt"

    업데이트는 한 번에 하나만 한다

    좋은 예:

    1. 백업
    2. NanoClaw만 업데이트
    3. 실행 확인
    4. 메시지 수신 확인
    5. 문제가 없으면 다음 구성요소 업데이트

    문제가 생겼을 때 원인을 좁힐 수 있어야 한다.

    13초보자가 하지 말아야 할 것과 완료 체크리스트

    초보자가 하지 말아야 할 것

    특히 피할 명령

    docker run -v /:/host ... docker run -v /var/run/docker.sock:/var/run/docker.sock ... docker compose up -d --pull always git add . git push

    git add .는 편하지만 .env, token, credential 파일을 함께 올리는 실수를 만들기 쉽다. 대신 변경 파일을 먼저 확인한다:

    git status git diff --name-only git add README.md compose.yaml

    보안 설정 완료 체크리스트

    API 키 ✓ 코드 직접 기입 금지, provider 분리, 마스킹 확인, 유출 시 절차

    .env ✓ Git에 올리지 않음, .gitignore 추가, 추적 파일 확인, .env.example만 올림, 권한 600

    메시징 ✓ 테스트/실사용 분리, allowed user/chat 설정, 민감 정보 미전송, 권한 최소화

    외부 접속 ✓ 포트 확인, Docker 공개 확인, 불필요한 0.0.0.0 없음, 방화벽 확인, 포트 포워딩 확인

    컨테이너 ✓ root 실행 확인, user 지정, privileged 미사용, cap_drop 적용, no-new-privileges 적용, read_only 검토, docker.sock 미사용

    파일 접근 ✓ host 전체 미마운트, workspace 폴더, :ro 마운트, 민감 파일 확인, 삭제 명령 규칙

    업데이트 ✓ 백업 폴더, Git 상태 저장, Docker 상태 저장, Compose 백업, 민감 파일 목록과 해시, 한 번에 하나씩

    14이 단원의 핵심 정리

    AI agent 보안의 핵심은 완벽한 차단이 아니라 피해 범위를 줄이는 것이다.

    Mac mini AI agent는 "잘 돌아가는가"보다 "잘못 돌아가도 피해가 작게 설계되어 있는가"가 더 중요하다.

    가장 중요한 원칙 7가지:

    1. API 키는 코드와 저장소에서 분리한다
    2. .env는 로컬 비밀 파일로 다룬다
    3. 메시징 계정은 테스트용과 실사용을 나눈다
    4. 외부 접속은 기본 차단한다
    5. 컨테이너 권한은 최소화한다
    6. agent가 볼 수 있는 파일 범위를 제한한다
    7. 업데이트 전에는 반드시 백업한다

    11단원을 통과하면 실사용 전 최소한의 보안 기준을 갖춘 상태다.

    12. 자주 막히는 문제 해결

    01이 단원에서 하는 일

    이 단원은 실제 커뮤니티와 개발자 이슈에서 반복적으로 나타나는 운영 문제를 Mac mini 환경에 맞춰 정리한 것입니다.

    초보자가 가장 자주 하는 실수는 아래와 같습니다:

    문제 해결의 핵심은 빠른 재설치가 아니라 정확한 분리다.

    02문제 해결 순서

    어떤 문제가 생기든 먼저 아래 정보를 모은다:

    1. 증상을 정확히 적는다
    2. 실행 방식이 무엇인지 확인한다
    3. 로그를 본다
    4. 원인을 추측하기 전에 범위를 좁힌다
    5. 삭제나 재설치 전에 현재 상태를 백업한다
    6. 작은 수정부터 한다
    7. 수정 후 다시 테스트한다
    8. 해결 과정을 RUNBOOK.md에 남긴다

    실전 팁: 문제 해결의 절반은

    "무엇이 실패했는지"보다"무엇은 정상인지"
    를 확인하는 것입니다. Docker는 정상인지, gateway는 정상인지, 메시징 수신은 되는지를 나눠서 봐야 합니다.

    03설치 명령어가 실패하는 경우

    설치 실패는 대개 프로젝트 코드 자체보다 아래 쪽에서 많이 납니다:

    설치 명령을 다시 치기 전에 현재 환경을 확인합니다:

    $ git --version $ node -v $ npm -v $ pnpm -v $ python3 --version $ docker --version

    에러가 나는 줄을 그대로 기록하고, 설치 로그를 파일로 저장합니다:

    $ bash install.sh 2>&1 | tee install-error.log

    04권한 오류가 나는 경우

    Docker 컨테이너에서 로그나 데이터 파일을 만들었는데 macOS에서 수정하려고 하자

    Permission denied
    가 발생했다면, 컨테이너 내부 사용자와 macOS 사용자 권한이 어긋난 것입니다.

    먼저 확인할 것:

    $ ls -la $ docker ps --format "table {{.Names}}\t{{.Image}}" $ docker exec 컨테이너이름 id

    Mac의 UID/GID를 확인한 후 Compose에 user를 지정합니다:

    services: agent: user: "1000:1000"

    임시로 소유권을 바꿔야 할 때는 대상 폴더를 좁게 잡습니다:

    $ sudo chown -R "$(whoami)":staff ~/ai-agents/workspace

    05Docker가 실행되지 않는 경우

    설치 직후에는 잘 되던 agent가 다음 날 아침에 멈췄다면, Docker Desktop이 켜져 있는지 확인합니다.

    Mac에서는 Docker Engine이 항상 기본 서비스로 떠 있는 것이 아니라 Docker Desktop 앱과 함께 동작합니다. Docker Desktop이 꺼져 있거나 아직 초기화 중이면

    docker ps
    가 실패합니다.

    $ docker info

    오류가 나면 Docker Desktop을 실행합니다:

    $ open -a Docker

    준비될 때까지 기다리며 확인합니다:

    $ while ! docker info >/dev/null 2>&1; do echo "Docker 준비 대기 중..." sleep 5 done

    06포트가 이미 사용 중이라고 나오는 경우

    gateway를 재시작했는데 기존 gateway 프로세스가 완전히 종료되기 전에 새 gateway가 뜨면서

    Port 18789 is already in use
    가 발생합니다.

    원리: 하나의 포트는 같은 시점에 하나의 프로세스만 listen할 수 있습니다.

    포트 확인:

    $ lsof -i :18789 $ ps aux | grep -E 'openclaw|hermes|gateway' | grep -v grep

    먼저 정상 종료 명령을 씁니다:

    $ openclaw gateway stop $ hermes gateway stop

    정상 종료 후 아직 남아 있으면 PID를 확인해 부드럽게 종료하고, 그래도 종료되지 않을 때만 강제 종료합니다:

    $ kill PID $ kill -9 PID # 마지막 수단

    중요: 포트 충돌은 "포트를 바꾸기 전에, 기존 프로세스가 왜 살아 있는지" 확인해야 합니다.

    07메시지를 받지 못하는 경우

    Telegram bot을 그룹에 넣었는데 개인 DM에서는 잘 되지만 그룹에서는 메시지를 받지 못했다면, Telegram bot privacy mode가 원인입니다.

    메시징 문제는 아래 세 단계로 나눕니다:

    1. 메시징 플랫폼이 agent에게 이벤트를 보내는가
    2. gateway가 이벤트를 받는가
    3. agent가 그 이벤트를 처리하는가

    gateway 상태 확인:

    $ hermes status $ openclaw gateway status

    Telegram 그룹에서 모든 메시지를 받아야 한다면:

    @BotFather → /setprivacy → 대상 bot 선택 → Disable 검토

    Discord는 Developer Portal에서 privileged gateway intents를 켜야 할 수 있습니다.

    08메시지는 오는데 답장이 안 가는 경우

    로그에

    message received
    는 찍히는데 사용자에게 답장이 가지 않습니다.

    메시지 처리 흐름:

    1. inbound 수신
    2. agent 처리
    3. model provider 호출
    4. 응답 생성
    5. outbound 발신

    최근 로그에서 수신과 발신을 같이 찾습니다:

    $ docker logs --since 15m 컨테이너이름 2>&1 | grep -E 'inbound|outbound|error'

    판단: 수신 로그 있음 + API 오류 있음 → provider/API 문제 | 수신 있음 + 응답 있음 + 발신 오류 → outbound 또는 권한 문제

    API 키 상태 확인 (값을 직접 출력하지 말고 존재 여부만):

    $ test -n "$ANTHROPIC_API_KEY" && echo "set" || echo "not set"

    09API 키 오류가 나는 경우

    API 키를 새로 만들었는데도 계속 오류가 났다면, 현재 터미널이 새 키를 쓰지 않고 예전에 저장된 키를 계속 쓰고 있을 수 있습니다.

    키 값 자체를 출력하지 말고 존재 여부만 확인합니다:

    $ env | grep -E 'ANTHROPIC|OPENAI|GEMINI' | sed 's/=.*/=***REDACTED***/'

    오류 유형별 판단:

    invalid_api_key
    키가 틀렸거나 만료되었거나 폐기됨
    insufficient_quota
    결제, 크레딧, 사용량 한도 문제
    rate_limit_error
    요청이 너무 많거나 토큰 사용량이 한도에 가까움
    model_not_found
    모델명, 권한, provider 설정 문제

    키 유출이 의심되면 디버깅보다 폐기가 먼저입니다: provider 콘솔에서 해당 키 revoke → 새 키 생성 → .env 업데이트 → agent 재시작

    10재부팅 후 자동 실행이 안 되는 경우

    launchd plist를 만들었고

    launchctl list
    에도 항목이 보였는데, 재부팅 후 agent는 실행되지 않습니다.

    원인: launchd가 터미널과 같은 PATH를 쓰지 않아

    hermes: command not found
    가 로그에 남습니다.

    plist 문법 확인:

    $ plutil -lint ~/Library/LaunchAgents/com.aiagents.hermes-gateway.plist

    로그 확인:

    $ tail -n 100 ~/ai-agents/logs/hermes-gateway.err.log

    launchd용 start script에는 PATH를 명시합니다:

    #!/bin/zsh export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin" hermes gateway start

    Docker Compose를 launchd로 올릴 때는 Docker가 준비될 때까지 기다립니다:

    for i in {1..30}; do docker info >/dev/null 2>&1 && break sleep 5 done docker compose up -d

    11로그 파일이 너무 커지는 경우

    gateway 로그가 무한히 커지면서 WebSocket heartbeat timeout 같은 반복 오류가 쌓입니다. 로그 파일이 커지는 문제는 "디스크가 부족하다"로만 보면 안 됩니다.

    큰 파일 찾기:

    $ find ~/ai-agents -type f -size +100M 2>/dev/null

    로그 폴더 크기:

    $ du -sh ~/ai-agents/logs

    반복되는 줄을 찾아 원인 파악:

    $ tail -n 1000 파일.log | sort | uniq -c | sort -nr | head -20

    Docker 로그 제한 설정 (Compose 파일에):

    services: agent: logging: driver: "json-file" options: max-size: "10m" max-file: "3"

    핵심: 로그 파일이 커지는 문제는 로그만 지우면 해결되지 않습니다. 같은 오류가 반복되는 원인을 찾아야 합니다.

    12업데이트 후 갑자기 작동하지 않는 경우

    업데이트 후 기존 gateway process가 남아 새 gateway가 포트를 잡지 못했거나, gateway는 살아 있는데 pairing required 오류가 발생합니다.

    가능한 원인:

    업데이트 직후 먼저 확인:

    $ hermes --version $ docker ps -a $ lsof -i :18789

    migration 필요 여부 확인:

    $ hermes config check $ hermes config migrate $ openclaw doctor

    업데이트 전 백업을 찾아 현재 상태와 비교합니다:

    $ diff -u ~/ai-agents/backups/backup-folder/compose.yaml ~/ai-agents/projects/nanoclaw-v2/compose.yaml

    중요: 업데이트 후 장애는 "업데이트가 실패했다"가 아니라 "업데이트 전후 무엇이 바뀌었는지 확인해야 하는 문제"입니다.

    13문제 해결용 통합 프롬프트

    문제가 복잡하면 아래 형식으로 정보를 수집한 후 분석합니다:

    구성: - 도구: [NanoClaw / OpenClaw] - 실행 방식: [Docker / launchd / 수동] - 메시징 채널: [Telegram / Discord] 확인 결과: docker ps -a: [붙여넣기] 프로세스: [붙여넣기] 포트: [붙여넣기] gateway status: [붙여넣기] 최근 로그: [API 키 제거 후 붙여넣기]

    요청 체크리스트:

    14초보자가 하지 말아야 할 것

    절대 금지:

    특히 위험한 명령:

    # 절대 금지 docker rm -f $(docker ps -aq) rm -rf ~/.hermes rm -rf ~/.openclaw kill -9 $(ps aux | grep gateway | awk '{print $2}')

    삭제보다 먼저 해야 할 것은 백업과 원인 분리입니다.

    15문제 해결 완료 체크리스트

    공통 항목:

    증상
    한 문장으로 정리했나
    Docker 상태
    docker ps -a 확인했나
    프로세스
    ps aux 확인했나
    포트
    lsof 확인했나
    gateway 상태
    hermes/openclaw status 확인했나
    로그
    최근 로그 확인했나

    범주별 항목 (해당 문제만):

    섹션 12 · 핵심 정리

    자주 막히는 문제 해결의 핵심

    AI agent 장애는 대부분 한 번에 고치는 문제가 아니라, 설치, Docker, gateway, 메시징, API, 자동 실행 중 어디에서 끊겼는지 좁혀가는 문제입니다.

    가장 중요한 순서:

    1. 최근 변경 사항 확인
    2. 프로세스 확인
    3. 포트 확인
    4. 로그 확인
    5. 메시징 수신 확인
    6. API 호출 확인
    7. 발신 확인
    8. 자동 실행 확인
    9. 백업과 비교
    10. 해결 기록 작성
    12단원을 통과하면 단순 설치 사용자가 아니라, 장애가 났을 때 스스로 원인을 분리하고 안전하게 복구할 수 있는 운영자에 가까워진다.
    기억할 원칙

    문제 해결은 빠른 재설치가 아니라 정확한 분리다.

    13. 실전 운영 팁

    01이 단원에서 하는 일

    이 단원에서는 Mac mini에서 NanoClaw, Hermes Agent, HermesClaw, OpenClaw 계열 에이전트를 실제로 오래 운영할 때 필요한 습관과 절차를 정리합니다.

    앞 단원들이 설치, 실행, 보안, 문제 해결을 다뤘다면 이 단원은 운영자의 생활 방식에 가깝습니다.

    이 단원에서 다루는 것

    실전 운영에서 가장 중요한 것은 멋진 자동화가 아니라 다음 중 하나입니다:

    02설치 성공 ≠ 운영 성공

    초보자가 자주 착각하는 것이 있습니다:

    설치 성공 = 운영 성공

    아닙니다. 운영 성공은 아래 상태입니다:

    0324시간 운영의 목표를 낮게 잡는다 (1/3)

    처음부터 완벽한 개인 비서, 트레이딩 봇, 업무 자동화 agent를 만들려고 하면 운영이 불안정해집니다.

    처음 1주일의 목표는 기능이 아니라 안정성입니다.

    첫 1주일 목표

    처음부터 하지 말아야 할 것:

    0424시간 운영의 목표를 낮게 잡는다 (2/3)

    실무에서는 "작게 오래 돌아가는 것"이 "크게 하루 돌아가는 것"보다 훨씬 낫습니다.

    24시간 운영용 기본 상태 확인 명령

    매일 한 번 아래 명령만 실행해도 운영 감각이 생깁니다:

    echo "=== DATE ===" date echo " === Docker ===" docker ps --format "table {{.Names}} {{.Status}} {{.Ports}}" echo " === Related processes ===" ps aux | grep -Ei 'nanoclaw|hermes|openclaw|claw|gateway' | grep -v grep echo " === Listening ports ===" lsof -nP -iTCP -sTCP:LISTEN | grep -Ei '18789|19998|19999|nanoclaw|hermes|openclaw|gateway' || echo "no matching ports" echo " === Disk ===" df -h / echo " === Logs size ===" du -sh ~/ai-agents/logs 2>/dev/null || echo "no ~/ai-agents/logs" du -sh ~/.hermes 2>/dev/null || echo "no ~/.hermes" du -sh ~/.openclaw 2>/dev/null || echo "no ~/.openclaw"

    이 명령은 고치는 명령이 아니라 관찰하는 명령입니다. 운영자는 먼저 보는 습관을 가져야 합니다.

    0524시간 운영의 목표를 낮게 잡는다 (3/3)

    하루 1분 점검표

    매일 복잡한 점검을 할 필요는 없습니다. 아래 정도면 충분합니다:

    초보자는 자동화보다 이 체크리스트가 먼저입니다.

    주 1회 점검표

    주 1회는 조금 더 깊게 봅니다:

    06Mac 설정: 잠자기 방지

    Mac mini를 서버처럼 쓰려면 디스플레이가 꺼져도 Mac이 잠자기 상태로 들어가지 않게 설정해야 합니다.

    macOS 설정에서 확인합니다:

    System Settings

    Energy → Prevent automatic sleeping when the display is off

    MacBook이 아니라 Mac mini 같은 데스크톱 환경에서는 이 설정을 먼저 확인합니다.

    명령어로 현재 전원 설정을 확인할 수도 있습니다:

    pmset -g

    일시적으로 작업 중 잠자기를 막고 싶다면 caffeinate를 쓸 수 있습니다:

    caffeinate -i

    특정 명령이 끝날 때까지만 잠자기를 막으려면:

    caffeinate -i docker compose up -d

    주의: caffeinate는 임시 작업에 적합합니다. 24시간 운영 기본 설정은 macOS Energy 설정에서 잡는 편이 낫습니다.

    07Docker Desktop Resource Saver 확인

    Docker Desktop에는 Resource Saver 기능이 있습니다. 이 기능은 유휴 상태에서 Docker Desktop의 Linux VM을 멈춰 자원을 아끼는 데 도움이 됩니다.

    하지만 24시간 agent 운영에서는 "Docker가 왜 잠깐 늦게 반응하지?"라는 혼란을 만들 수 있습니다.

    확인 위치

    Docker Desktop → Settings → Resources → Resource Saver

    실무 판단 기준

    개발용 Mac
    Resource Saver를 켜도 괜찮음
    24시간 agent 운영용 Mac mini
    agent 컨테이너가 항상 떠 있어야 한다면 Resource Saver 영향 여부 확인
    문제가 의심될 때
    일시적으로 Resource Saver를 끄고 2~3일 안정성을 비교

    무조건 끄라는 뜻은 아닙니다. 다만 Docker가 갑자기 반응하지 않거나, 재시작 후 컨테이너가 늦게 살아나는 것처럼 보이면 이 설정을 확인해야 합니다.

    08네트워크: 유선 우선

    Mac mini를 서버처럼 쓸 때는 Wi-Fi보다 유선 Ethernet을 우선합니다.

    권장 배치

    특히 메시징 gateway는 네트워크가 잠깐 끊겨도 세션이 꼬일 수 있습니다.

    Wi-Fi가 나쁜 경우

    09재시작 순서: 작은 단위부터

    장애가 났을 때 전체 Mac을 재부팅하는 것은 가장 마지막 선택입니다. 운영에서는 작은 단위부터 재시작합니다:

    재시작 순서

    1. agent process
    2. gateway
    3. Docker container
    4. Docker Compose project
    5. Docker Desktop
    6. Mac mini 재부팅

    예시

    openclaw gateway restart
    docker restart 컨테이너이름
    cd ~/ai-agents/projects/nanoclaw-v2 docker compose restart

    Mac 전체 재부팅은 가장 크고 거친 조치입니다.

    10로그 관리 원칙

    초보자는 로그가 커지면 바로 삭제합니다:

    rm app.log

    하지만 운영에서는 삭제보다 회전이 낫습니다.

    로그 관리 원칙

    11Docker 로그 회전 설정

    Docker Compose를 쓰는 경우 service마다 logging 옵션을 넣습니다:

    services: agent: logging: driver: "json-file" options: max-size: "10m" max-file: "3"

    gateway service에도 넣습니다:

    services: gateway: logging: driver: "json-file" options: max-size: "10m" max-file: "3"

    적용 및 확인

    docker compose up -d docker compose ps docker compose logs --tail 100

    12로그 파일 위치와 크기 확인

    docker ps --format "table {{.Names}} {{.Status}}" docker inspect --format='{{.LogPath}}' 컨테이너이름

    로그 크기 확인

    ls -lh "$(docker inspect --format='{{.LogPath}}' 컨테이너이름)"

    로그 크기가 수백 MB 이상으로 커지면 회전 설정을 검토합니다.

    13반복 오류 찾기

    로그가 커지는 진짜 원인은 대개 반복 오류입니다:

    tail -n 1000 파일경로.log | sort | uniq -c | sort -nr | head -20

    Docker 로그에서 찾기

    docker logs --tail 1000 컨테이너이름 2>&1 | sort | uniq -c | sort -nr | head -20

    최근 오류만 보기

    docker logs --since 30m 컨테이너이름 2>&1 | grep -Ei 'error|fail|timeout|retry|auth|token|rate|limit|port|heartbeat'

    실무에서는 로그 크기보다 반복되는 문장이 더 중요합니다.

    나쁜 접근: 로그 파일이 3GB네. 지워야지. 좋은 접근: 왜 같은 오류가 100만 번 반복됐는지 먼저 보자.

    14로그 보존 정책 정하기

    처음에는 단순하게 정합니다:

    운영 로그
    최근 7일 보관
    장애 로그
    해결 후 30일 보관
    민감 정보가 포함된 로그
    외부 공유 금지, 필요 시 즉시 폐기 또는 안전 보관
    디버그 로그
    문제 해결 후 삭제 또는 압축

    로그 보관 폴더 생성

    mkdir -p ~/ai-agents/logs/archive

    오래된 로그 압축

    find ~/ai-agents/logs -type f -name "*.log" -mtime +7 -exec gzip {} ;

    30일 지난 압축 로그 삭제

    find ~/ai-agents/logs -type f -name "*.gz" -mtime +30 -delete

    초보자는 이 명령을 자동화하기 전에 먼저 수동으로 한 번 실행해 결과를 확인합니다.

    15로그의 민감 정보 검사

    로그에 API 키나 토큰이 찍혀 있을 수 있습니다:

    grep -R -n -Ei 'sk-|api_key|token|secret|password|credential|cookie|session' ~/ai-agents/logs ~/ai-agents/projects 2>/dev/null

    찾았다면 해당 내용을 외부에 공유하지 않습니다. 먼저 API 키나 토큰 유출 가능성을 판단합니다:

    1단계
    해당 키가 실제 키인지 확인
    2단계
    실제 키라면 provider 콘솔에서 폐기
    3단계
    새 키 발급
    4단계
    로그 보관 중지 또는 안전 삭제
    5단계
    왜 로그에 찍혔는지 코드 또는 설정 수정

    16업데이트는 "시간이 있을 때" 하는 것이 아니다

    업데이트는 시간이 있을 때 하는 것이 아니라, 되돌릴 시간이 있을 때 하는 것입니다.

    실무에서 가장 나쁜 업데이트 시간:

    좋은 업데이트 시간

    17업데이트 전 반드시 보는 것

    업데이트 전에는 아래를 확인합니다:

    GitHub 프로젝트라면

    git status git log --oneline -5 git remote -v

    Docker 상태

    docker ps -a docker images

    18업데이트 전 백업

    업데이트 전에는 백업을 만듭니다:

    BACKUP_DIR=~/ai-agents/backups/before-update-$(date +%Y%m%d-%H%M%S) mkdir -p "$BACKUP_DIR" docker ps -a > "$BACKUP_DIR/docker-ps-a.txt" docker images > "$BACKUP_DIR/docker-images.txt" find ~/ai-agents/projects -maxdepth 5 -type f > "$BACKUP_DIR/projects-file-list.txt"

    19업데이트는 하나씩 한다

    나쁜 예

    하루에 전부 진행

    좋은 예

    1. 백업
    2. NanoClaw만 업데이트
    3. 실행 확인
    4. 메시지 수신 확인
    5. 메시지 발신 확인
    6. 로그 확인
    7. 하루 지켜봄
    8. 다음 구성요소 업데이트

    이 방식은 느려 보이지만 장애 원인을 좁히는 데 훨씬 빠릅니다.

    20업데이트 후 smoke test

    업데이트가 끝나면 아래 테스트를 합니다:

    확인 명령어

    docker ps -a hermes status 2>/dev/null || true openclaw gateway status 2>/dev/null || true docker logs --tail 100 컨테이너이름

    메시징 앱에 보내는 테스트

    업데이트 후 테스트야. 정상 작동하면 "업데이트 테스트 성공"이라고 답해줘.

    21업데이트 후 관찰 기간

    업데이트 직후에는 최소한 짧은 관찰 시간을 둡니다:

    관찰할 것

    실무 팁

    업데이트 직후 10분은 기능을 추가하지 않는다. 먼저 정상 작동만 확인한다.

    22테스트 환경과 실사용 환경 분리

    AI agent 운영에서 테스트와 실사용을 섞으면 문제가 커집니다:

    섞었을 때 생기는 문제

    가장 좋은 구조는 처음부터 분리하는 것입니다:

    권장 구조: test-bot, staging-bot, production-bot

    초보자에게는 최소한 test와 production만 나눠도 충분합니다.

    23환경 분리: 폴더와 설정

    폴더 분리

    mkdir -p ~/ai-agents/environments/test mkdir -p ~/ai-agents/environments/prod

    예시 구조

    ~/ai-agents/ environments/ test/ .env compose.yaml RUNBOOK.md prod/ .env compose.yaml RUNBOOK.md logs/ test/ prod/ backups/ test/ prod/

    .env 분리

    테스트용:

    nano ~/ai-agents/environments/test/.env

    운영용:

    nano ~/ai-agents/environments/prod/.env

    테스트용 예시:

    AGENT_ENV=test AGENT_NAME=test-bot LOG_LEVEL=debug

    운영용 예시:

    AGENT_ENV=prod AGENT_NAME=personal-assistant LOG_LEVEL=info
    주의

    테스트와 운영은 API 키도 가능하면 분리한다. 테스트가 폭주해도 운영 한도를 먹지 않게 하기 위해서다.

    24메시징 계정과 포트 분리

    메시징 계정 분리

    테스트
    테스트용 Telegram bot, 테스트용 Discord 서버, local CLI, 본인만 있는 채팅방
    운영
    운영 전용 bot, 운영 전용 채널, allowed user 설정, allowed chat 설정

    피해야 할 구조

    포트 분리

    test와 prod가 같은 포트를 쓰면 충돌합니다:

    test
    18790
    prod
    18789

    확인

    lsof -nP -iTCP -sTCP:LISTEN | grep -Ei '18789|18790|19998|19999'

    25Docker Compose project 분리

    Docker Compose는 프로젝트 이름이 겹치면 리소스 이름이 헷갈릴 수 있습니다:

    테스트

    docker compose -p agent-test up -d

    운영

    docker compose -p agent-prod up -d

    상태 확인

    docker ps --format "table {{.Names}} {{.Status}} {{.Ports}}"

    26운영 승격 기준

    테스트에서 잘 됐다고 바로 운영으로 옮기지 않습니다:

    안정성
    24시간 동안 재시작 루프 없음, 로그 폭증 없음, 메시지 중복 발송 없음, API 오류 반복 없음
    실행
    재부팅 후 복구 성공, 백업 완료, RUNBOOK.md 작성 완료

    27장애 대응 첫 원칙

    장애가 나면 먼저 고치려고 하지 말고 멈춰야 할 것을 멈춘다입니다.

    특히 메시지가 중복 발송되거나 API 호출이 폭주하면 즉시 자동화부터 멈춥니다:

    긴급 중지 대상

    중지 명령

    docker stop 컨테이너이름 docker compose stop openclaw gateway stop hermes gateway stop 2>/dev/null || true

    28장애 복구 순서

    실무 복구는 아래 순서가 안전합니다:

    복구 단계

    1. 증상 기록
    2. 자동화 중지
    3. 현재 상태 저장
    4. 최근 변경 확인
    5. 로그 확인
    6. 가장 작은 단위부터 재시작
    7. 테스트 메시지 확인
    8. 재발 방지 기록

    상태 저장

    INCIDENT_DIR=~/ai-agents/incidents/$(date +%Y%m%d-%H%M%S) mkdir -p "$INCIDENT_DIR" docker ps -a > "$INCIDENT_DIR/docker-ps-a.txt" 2>&1 ps aux | grep -Ei 'nanoclaw|hermes|openclaw|gateway' | grep -v grep > "$INCIDENT_DIR/processes.txt" 2>&1 lsof -nP -iTCP -sTCP:LISTEN > "$INCIDENT_DIR/ports.txt" 2>&1

    29최근 변경 확인

    장애의 원인은 대부분 "방금 바꾼 것"에 있습니다:

    확인할 최근 변경

    Git 상태 확인

    cd ~/ai-agents/projects/프로젝트명 git status --short git log --oneline -5

    파일 수정 시간 확인

    find ~/ai-agents -type f -mtime -1 -exec ls -la {} ; 2>/dev/null | head -100

    30작은 단위부터 복구

    나쁜 복구

    일단 Mac 재부팅

    좋은 복구

    1. gateway만 재시작
    2. agent 컨테이너만 재시작
    3. compose project만 재시작
    4. Docker Desktop 재시작
    5. 마지막에 Mac 재부팅

    재시작 명령어

    docker restart 컨테이너이름 openclaw gateway restart cd ~/ai-agents/projects/nanoclaw-v2 docker compose restart

    31복구 후 반드시 테스트

    복구 후에는 "프로세스가 떴다"로 끝내지 않습니다:

    복구 후 확인

    테스트 메시지

    복구 테스트야. 정상 작동하면 "복구 테스트 성공"이라고 답해줘.

    32장애 기록 작성

    장애를 해결했으면 기록합니다:

    장애 기록 템플릿

    # 장애 기록 ## 일시 YYYY-MM-DD HH:mm ## 증상 - ## 영향 - ## 원인 - ## 해결 - ## 재발 방지 - ## 다음에 바로 볼 명령어 -

    이 기록이 쌓이면 운영 실력이 빠르게 올라갑니다.

    33Mac mini 물리 배치

    권장 배치

    피해야 할 배치

    34모니터 없이 운영하기

    처음 설치할 때는 모니터, 키보드, 마우스가 있는 편이 좋습니다. 운영이 안정되면 모니터 없이 쓸 수 있습니다:

    권장 순서

    1. 모니터 연결 상태에서 설치
    2. 자동 실행 설정
    3. 재부팅 테스트
    4. 원격 접속 테스트
    5. 모니터 제거

    원격 접속을 쓸 때는 macOS Sharing 설정을 신중히 확인합니다:

    확인 위치

    System Settings → General → Sharing

    검토 대상

    보안상 원격 접속은 내부 네트워크 또는 VPN 안에서만 쓰는 편이 안전합니다.

    35열과 먼지 관리

    Mac mini는 일반적으로 조용한 편이지만, 24시간 운영에서는 소음보다 열과 먼지가 더 중요합니다:

    확인할 것

    CPU 사용량 확인

    top -o cpu

    메모리 확인

    top -o mem

    Docker 사용량 확인

    docker stats

    docker stats는 실시간으로 계속 표시되므로 중지하려면 Ctrl + C를 누릅니다.

    36외장 저장장치 주의사항

    로그나 데이터가 많아지면 외장 SSD를 쓰고 싶을 수 있습니다:

    주의할 점

    초보자에게는 처음부터 외장 SSD에 Docker 전체를 옮기는 것을 권하지 않습니다. 먼저 내부 저장공간에서 안정성을 확인하고, 로그와 백업만 외장으로 옮기는 편이 낫습니다.

    37전원 안정성

    24시간 운영에서는 전원도 중요합니다:

    권장

    UPS는 필수는 아니지만, 트레이딩 알림이나 업무 자동화처럼 놓치면 안 되는 작업에는 도움이 됩니다.

    38운영자가 남겨야 하는 문서: RUNBOOK.md

    각 프로젝트에는 반드시 RUNBOOK.md를 둡니다:

    nano ~/ai-agents/projects/nanoclaw-v2/RUNBOOK.md

    RUNBOOK 내용

    # RUNBOOK ## 설치 위치 - ## 실행 방법 - ## 중지 방법 - ## 재시작 방법 - ## 상태 확인 - ## 로그 확인 - ## 메시지 테스트 - ## API 확인 - ## 백업 위치 - ## 장애 시 첫 번째 명령어 -

    39운영자가 남겨야 하는 문서: 변경 로그와 장애 기록

    CHANGELOG-LOCAL.md

    내가 바꾼 설정은 따로 적습니다:

    nano ~/ai-agents/projects/nanoclaw-v2/CHANGELOG-LOCAL.md

    예시:

    # Local Change Log ## 2026-06-06 - Docker restart policy를 unless-stopped로 변경 - compose.yaml에 log rotation 추가 - Telegram test bot에서 prod bot 분리 - launchd plist 추가

    공식 프로젝트의 CHANGELOG와 내 변경 기록은 다릅니다. 내가 무엇을 바꿨는지 모르면 장애가 났을 때 되돌릴 수 없습니다.

    INCIDENTS.md

    nano ~/ai-agents/INCIDENTS.md

    예시:

    # Incidents ## 2026-06-06 21:10 증상: Telegram 메시지는 수신되지만 답장 없음 원인: API key가 test .env에는 있었지만 prod .env에는 없었음 해결: prod .env 업데이트 후 gateway 재시작 재발 방지: 업데이트 후 env-redacted.txt 비교 추가

    이 문서는 나중에 가장 값진 자료가 됩니다.

    40운영 자동 점검 스크립트

    간단한 health check 스크립트

    mkdir -p ~/ai-agents/bin nano ~/ai-agents/bin/health-check.sh

    스크립트 내용

    #!/bin/zsh set -euo pipefail echo "=== DATE ===" date echo " === Docker containers ===" docker ps --format "table {{.Names}} {{.Status}} {{.Ports}}" || true echo " === Hermes ===" hermes status 2>/dev/null || echo "hermes status unavailable" echo " === OpenClaw ===" openclaw gateway status 2>/dev/null || echo "openclaw gateway status unavailable" echo " === Related processes ===" ps aux | grep -Ei 'nanoclaw|hermes|openclaw|claw|gateway' | grep -v grep || true echo " === Ports ===" lsof -nP -iTCP -sTCP:LISTEN | grep -Ei '18789|19998|19999|nanoclaw|hermes|openclaw|gateway' || echo "no matching ports" echo " === Disk ===" df -h / echo " === Logs size ===" du -sh ~/ai-agents/logs 2>/dev/null || true du -sh ~/.hermes 2>/dev/null || true du -sh ~/.openclaw 2>/dev/null || true

    권한 부여와 실행

    chmod +x ~/ai-agents/bin/health-check.sh ~/ai-agents/bin/health-check.sh

    결과 저장

    mkdir -p ~/ai-agents/checks ~/ai-agents/bin/health-check.sh > ~/ai-agents/checks/health-$(date +%Y%m%d-%H%M%S).txt 2>&1

    41자동 복구 스크립트는 나중에

    초보자가 바로 만들고 싶어 하는 것이 자동 복구 스크립트입니다. 예를 들어:

    하지만 처음에는 자동 복구보다 자동 점검이 먼저입니다:

    순서

    1. 수동 점검
    2. 점검 스크립트
    3. 알림
    4. 제한적인 자동 복구
    5. 복구 후 검증

    잘못 만든 자동 복구

    오류 감지 → 무조건 재시작 → 또 오류 → 무한 재시작 → 로그 폭증 → API 낭비

    좋은 자동 복구

    오류 감지 → 상태 저장 → 1회만 재시작 → 테스트 → 실패하면 중지하고 알림

    42실사용 전 안정성 점검

    실사용으로 전환하기 전에는 아래를 확인합니다:

    안정성

    보안

    운영

    비용과 한도

    43운영 중 agent 프롬프트

    운영 중 agent에게 아래 프롬프트를 넣어둘 수 있습니다:

    너는 Mac mini에서 실행되는 개인 AI agent다. 현재 목적은 안정적인 장기 운영이다. 운영 규칙: - 파일을 수정하기 전에 변경 이유를 설명한다. - 삭제 명령은 바로 실행하지 않는다. - API 키, 토큰, 쿠키, 세션값을 출력하지 않는다. - 로그를 볼 때 민감 정보를 마스킹한다. - 오류가 나면 설치, Docker, gateway, 메시징, API, 자동 실행 중 어디 문제인지 구분한다. - 같은 작업을 반복 실행하지 않는다. - 메시지 발송은 한 번만 수행한다. - 장시간 작업 전에는 현재 상태를 기록한다. - 업데이트 전에는 백업 여부를 확인한다. - 확인할 수 없는 항목은 UNKNOWN으로 표시한다. 응답 형식: 1. 현재 상태 2. 위험 신호 3. 확인할 명령어 4. 안전한 조치 5. 다음 기록할 내용

    44초보자가 하지 말아야 할 것

    특히 아래 명령은 운영 중 바로 치지 않습니다:

    docker rm -f $(docker ps -aq) rm -rf ~/ai-agents/logs rm -rf ~/.hermes rm -rf ~/.openclaw kill -9 $(ps aux | grep gateway | awk '{print $2}')

    운영자는 빠르게 지우는 사람이 아니라, 안전하게 복구하는 사람입니다.

    45실전 운영 완료 체크리스트

    아래 항목을 통과하면 13단원 완료입니다:

    24시간 운영

    로그 관리

    업데이트

    테스트/실사용 분리

    장애 복구

    Mac mini 서버 운영

    문서화

    46실전 운영의 핵심 원칙

    실전 운영의 핵심은 기능을 많이 켜는 것이 아니라, 작게 시작해서 오래 안정적으로 유지하는 것입니다.

    가장 중요한 원칙:

    1. 24시간 운영 전 24시간 테스트를 한다
    2. 로그는 삭제보다 회전과 원인 분석이 먼저다
    3. 업데이트는 되돌릴 시간이 있을 때 한다
    4. 테스트 환경과 실사용 환경은 반드시 나눈다
    5. 장애가 나면 작은 단위부터 복구한다
    6. Mac mini는 조용하지만 서버처럼 관리해야 한다
    7. RUNBOOK과 장애 기록이 운영 실력이다

    초보자가 기억할 문장:

    개인 AI agent 운영은 한 번 설치하고 끝나는 일이 아니라, 작게 점검하고, 조심스럽게 업데이트하고, 문제가 생기면 기록하면서 안정성을 쌓아가는 일이다.

    13단원을 통과하면 단순히 Mac mini에서 agent를 켜둔 사람이 아니라, 24시간 개인 AI agent를 운영할 기본 습관을 갖춘 상태가 됩니다.

    14. 실전 사례 1: 개인 비서형 에이전트 만들기

    01이 단원에서 하는 일

    이 단원에서는 Mac mini에서 실행되는 개인 비서형 AI 에이전트를 만듭니다.

    여기서 말하는 개인 비서형 에이전트는 사람처럼 모든 일을 대신하는 만능 비서가 아닙니다. 처음 목표는 작고 안전해야 합니다.

    이 단원의 목표

    매일 아침 오늘 할 일을 정리합니다. 메시지로 간단한 요청을 받습니다. 일정, 메모, 할 일, 알림을 한곳에서 다룹니다. 사용자의 승인 없이 중요한 작업을 실행하지 않습니다. 실사용 계정과 테스트 계정을 분리합니다. 로그와 백업을 남겨 운영 가능하게 만듭니다.

    02초보자가 원하는 개인 비서의 위험성

    초보자가 처음부터 만들려고 하는 개인 비서는 보통 이런 모습입니다.

    "내 메일을 읽고, 일정을 정리하고, 답장도 쓰고, 파일도 정리하고, 내가 말하기 전에 알아서 다 해주는 비서"

    하지만 실전에서는 이 접근이 위험합니다.

    위험한 이유

    메일과 캘린더에는 민감 정보가 많습니다. 메시징 계정이 잘못 연결되면 다른 사람에게 답장이 갈 수 있습니다. API 키와 OAuth token이 노출될 수 있습니다. 에이전트가 잘못 이해하고 실제 작업을 실행할 수 있습니다. 로그에 개인정보가 남을 수 있습니다.

    03단계별 설계 방식

    따라서 이 단원에서는 아래 순서로 만듭니다.

    1읽기 전용 개인 비서
    2요약형 개인 비서
    3승인 후 실행하는 개인 비서
    4제한된 자동화 개인 비서

    처음부터 자동 실행형 비서를 만들지 않습니다. 초기 목표는 "내가 메시지를 보내면, 오늘 일정과 할 일, 최근 메모를 바탕으로 짧게 정리해서 답해주는 개인 비서" 정도면 충분합니다.

    04실제 사례에서 배울 점

    공개 프로젝트와 커뮤니티에서 반복적으로 보이는 개인 비서형 에이전트의 자주 등장하는 실제 사용 패턴은 비슷합니다.

    아침 브리핑
    캘린더 일정 요약
    메일 요약
    메시지 초안 작성
    리마인더 생성
    할 일 목록 정리
    회의 전 자료 정리
    파일 또는 메모 검색
    간단한 웹 리서치
    업무 채널 요약

    하지만 실제 운영자들은 보통 한 가지 문제를 겪습니다: "기능은 만들 수 있는데, 믿고 맡기기 어렵다."

    05운영 신뢰도의 문제

    이유는 아래와 같습니다.

  • 에이전트가 어느 정보를 근거로 답했는지 모른다
  • 오래된 메모를 최신 정보처럼 말한다
  • 일정 변경을 바로 실행하면 위험하다
  • 메일 답장을 실제로 보내면 사고가 날 수 있다
  • 알림이 너무 많아지면 사용자가 무시한다
  • 테스트 bot과 실사용 bot이 섞이면 원인 추적이 어렵다

    • 그래서 개인 비서형 에이전트는 "많이 할 수 있는가"보다 "어디까지 믿고 맡길 수 있는가"를 기준으로 설계해야 합니다.

    06설계 원칙 8가지

  • 처음에는 읽기 전용으로 시작한다
  • 답장은 초안까지만 만들고 자동 발송하지 않는다
  • 일정 변경은 반드시 사용자 승인을 받는다
  • 메모와 파일 접근 범위를 제한한다
  • 매일 같은 형식으로 보고하게 한다
  • 모르면 모른다고 말하게 한다
  • 출처가 불분명하면 UNKNOWN으로 표시하게 한다
  • 실사용 전 테스트 채널에서 1주일 운영한다

    • 07에이전트가 할 일

    먼저 에이전트가 할 일과 하지 않을 일을 명확히 정합니다.

    할 일

    오늘 일정 요약 | 오늘 할 일 정리 | 중요한 메시지 요약 | 사용자가 직접 보낸 메모 정리 | 리마인더 초안 작성 | 메일 답장 초안 작성 | 회의 전 체크리스트 작성 | 하루 마감 회고 질문 | 다음 행동 추천

    08에이전트가 하지 않을 일

    초기 버전에서는 다음을 하지 않습니다.

    금지

    사용자의 승인 없이 메일 발송 | 사용자의 승인 없이 일정 변경 | 사용자의 승인 없이 파일 삭제 | 사용자의 승인 없이 결제 | 사용자의 승인 없이 외부 사람에게 메시지 발송 | 개인 계정 전체 메일함 스캔 | 모든 메시징 채널 읽기 | 실시간 트레이딩 판단

    09에이전트 이름 정하기

    이름은 기능이 보이게 단순하게 정합니다.

    추천 이름
    personal-assistant | daily-briefing | schedule-helper | inbox-helper | life-admin
    피해야 할 이름
    everything-agent | super-secret-ai | real-main-final-agent | auto-everything

    운영에서는 이름이 짧고 목적이 분명해야 로그를 보기 쉽습니다.

    10최소 기능 5개

    처음 버전은 아래 5개 기능만 넣습니다. 이 5개를 안정적으로 운영한 뒤 기능을 늘립니다.

  • 오늘 브리핑
  • 할 일 정리
  • 메모 저장
  • 메시지 요약
  • 답장 초안 작성

    • 11오늘 브리핑 기능

    사용자가 아침에 메시지를 보냅니다: "오늘 브리핑 해줘."

    에이전트는 아래 형식으로 답합니다.

    일정
    시간이 정해진 것
    할 일
    해야 하지만 시간이 고정되지 않은 것
    확인할 메시지
    답장 또는 검토가 필요한 것
    주의할 점
    충돌, 마감, 준비물, 이동 시간 같은 리스크

    중요한 점은 일정, 할 일, 메시지를 섞어 말하지 않는 것입니다.

    12할 일 정리 기능

    사용자가 아래처럼 보냅니다.

    할 일 추가:

    에이전트는 바로 외부 앱에 쓰지 않고 먼저 정리해서 답합니다. 날짜가 없는 일은 억지로 날짜를 만들지 않습니다.

    좋은 응답
    "카드 결제일 확인"은 날짜가 필요합니다. 날짜를 모르면 UNKNOWN으로 두겠습니다.
    나쁜 응답
    카드 결제일은 아마 25일일 것입니다.

    13메모 저장 기능

    초기 버전에서는 복잡한 데이터베이스를 쓰지 않습니다. 먼저 로컬 markdown 파일에 저장합니다.

    폴더 만들기:

    mkdir -p ~/ai-agents/workspace/personal-assistant/notes

    오늘 메모 파일:

    touch ~/ai-agents/workspace/personal-assistant/notes/$(date +%Y-%m-%d).md

    처음에는 저장 전 확인을 받습니다: "저장해도 될까요?"

    14메시지 요약 기능

    사용자가 긴 메시지를 붙여넣습니다: "아래 메시지를 요약해줘."

    에이전트는 이렇게 답합니다.

    요약
    상대가 무슨 말을 했는가
    행동
    내가 무엇을 해야 하는가
    초안
    상대에게 어떻게 답할 것인가

    여기서 중요한 점은 "요약"과 "행동"을 나누는 것입니다.

    15답장 초안 작성 기능

    초기 개인 비서는 실제 발송을 하지 않습니다.

    사용자: "이 메시지에 정중하게 답장 초안 써줘. [상대 메시지]"

    에이전트는 초안만 작성하고 절대 바로 보내지 않습니다.

    초기 규칙

    답장 초안만 작성 | 발송은 사용자가 직접 | 자동 발송은 2단계 이후 검토

    16전체 구조 설계

    개인 비서형 에이전트는 아래 구조로 시작합니다.

    1사용자
    2메시징 앱 또는 local CLI
    3NanoClaw / Hermes Agent / OpenClaw gateway
    4개인 비서 agent
    5workspace 폴더 및 응답

    처음에는 외부 앱 연동을 최소화합니다.

    초기 연결
    local CLI | Telegram test bot | 개인 테스트 채팅방 | 로컬 workspace 폴더
    나중에 연결
    Gmail | Google Calendar | Slack | Notion | Apple Reminders | 파일 검색

    17권장 폴더 구조

    아래 폴더 구조를 만듭니다.

    mkdir -p ~/ai-agents/projects/personal-assistant
    mkdir -p ~/ai-agents/workspace/personal-assistant/{inbox,outbox,notes,tasks,briefings,logs}
    mkdir -p ~/ai-agents/backups/personal-assistant

    확인:

    tree ~/ai-agents/workspace/personal-assistant 2>/dev/null || find ~/ai-agents/workspace/personal-assistant -maxdepth 2 -type d

    18기본 파일 만들기

    필요한 기본 파일을 만듭니다.

    touch ~/ai-agents/workspace/personal-assistant/tasks/todo.md
    touch ~/ai-agents/workspace/personal-assistant/notes/general.md
    touch ~/ai-agents/workspace/personal-assistant/briefings/daily.md
    touch ~/ai-agents/projects/personal-assistant/RUNBOOK.md

    todo.md 파일 구조는 "오늘 | 이번 주 | 날짜 필요 | 보류"로 나눕니다.

    daily.md 파일 구조는 "YYYY-MM-DD | 일정 | 할 일 | 메시지 | 주의할 점"으로 기록합니다.

    19접근 범위 제한

    개인 비서 agent가 접근할 수 있는 폴더를 제한합니다.

    허용
    ~/ai-agents/workspace/personal-assistant
    기본 차단
    ~/Desktop | ~/Documents | ~/Downloads | ~/.ssh | ~/.config | ~/.openclaw | ~/.hermes | .env 파일 | credential 파일 | token 파일

    운영 프롬프트에 반드시 넣습니다.

    20환경 파일 만들기

    환경 설정 파일을 만듭니다.

    mkdir -p ~/ai-agents/environments/personal-assistant
    nano ~/ai-agents/environments/personal-assistant/.env

    예시:

    AGENT_NAME=personal-assistant
    AGENT_ENV=test
    DEFAULT_CHANNEL=telegram-test
    LOG_LEVEL=info
    WORKSPACE_DIR=/Users/사용자이름/ai-agents/workspace/personal-assistant

    권한 제한:

    chmod 600 ~/ai-agents/environments/personal-assistant/.env
    }

    21테스트 채널 먼저 연결

    처음 연결은 실사용 채널이 아니라 테스트 채널로 합니다.

    권장 순서
    local CLI → Telegram test bot → 본인만 있는 테스트 채팅방 → 실사용 전용 채널
    피해야 할 순서
    업무 Slack 전체 채널 → 가족 채팅방 → 고객 채팅방 → 실사용 WhatsApp 계정

    22기본 운영 프롬프트

    개인 비서 agent에게 아래 프롬프트를 넣습니다.

    너는 Mac mini에서 실행되는 개인 비서형 AI 에이전트다.

    현재 단계는 실사용 전 테스트 단계다.

    너의 역할:
    - 오늘 일정과 할 일을 정리한다.
    - 사용자가 붙여넣은 메시지를 요약한다.
    - 답장 초안을 작성한다.
    - 메모를 정리한다.
    - 중요한 작업 전에는 사용자 확인을 요청한다.

    규칙:
    - 확인되지 않은 정보는 추측하지 않고 UNKNOWN으로 표시한다.
    - 사용자가 승인하지 않은 메일 발송, 메시지 발송, 일정 변경은 하지 않는다.
    - API 키, 토큰, 쿠키, 세션값, 비밀번호를 출력하지 않는다.
    - 파일 작업은 ~/ai-agents/workspace/personal-assistant 안에서만 한다.

    234단계 안전 등급 설계

    개인 비서는 기능별로 위험도가 다릅니다.

    1단계: 읽기 전용
    허용: 메시지 요약 | 일정 정리 | 로컬 메모 읽기 | 할 일 요약 | 금지: 외부 앱에 쓰기 | 메시지 발송 | 일정 변경 | 파일 삭제
    2단계: 초안 작성
    허용: 메일 답장 초안 | Slack 답장 초안 | 일정 변경 제안 | 할 일 추가 제안 | 금지: 실제 발송 | 실제 일정 변경 | 외부 사람에게 자동 메시지
    3단계: 승인 후 실행
    허용: 사용자 승인 후 메모 저장 | 할 일 추가 | 캘린더 이벤트 생성 | 메시지 발송 | 조건: 실행 전 변경 내용 요약 | 실행 대상 명확히 표시 | 실행 후 결과 보고
    4단계: 제한된 자동화
    허용: 매일 아침 브리핑 | 하루 마감 체크인 | 특정 키워드 알림 | 금지: 외부 발송 자동화 | 결제 | 삭제 | 민감 파일 접근

    처음 3일은 1단계만 운영합니다. 4단계는 1~3단계가 안정화된 뒤에만 합니다.

    24테스트 체크리스트

    실사용 전 아래를 통과해야 합니다.

    기본 응답

    [ ] 테스트 메시지에 응답 | [ ] 중복 답장 없음 | [ ] 응답 형식이 일정 | [ ] UNKNOWN으로 표시

    브리핑

    [ ] 일정을 분리해서 정리 | [ ] 할 일을 일정과 구분 | [ ] 주의할 점 표시 | [ ] 오래된 메모와 최신 정보 구분

    답장 초안

    [ ] 실제 발송 안 함 | [ ] 초안이라고 명확히 표시 | [ ] 지어낸 내용 없음 | [ ] 정중하고 짧게 작성

    보안

    [ ] API 키 출력 안 함 | [ ] .env 파일 읽기 안 함 | [ ] workspace 밖 파일 자동 접근 안 함 | [ ] UNKNOWN으로 표시

    25실제 사용 예시: 아침 브리핑

    사용자 메시지:

    오늘 브리핑 해줘.

    확실한 정보:
    - 10:00 팀 미팅
    - 15:00 병원
    - 오늘 안에 보고서 초안 작성

    메모:
    어제 회의에서 예산표 다시 확인하라고 했음

    에이전트는 일정 | 꼭 해야 할 일 | 미뤄도 되는 일 | 주의할 점 | 추천 순서 | UNKNOWN을 분리해서 답합니다. 추측하지 않고 정보가 없으면 UNKNOWN으로 표시합니다.

    26실제 사용 예시: 회의 전 준비

    사용자: "30분 뒤 팀 미팅이 있어. 준비할 것 정리해줘."

    에이전트는 핵심 메시지 | 말할 순서 | 회의 중 확인할 질문 | 회의 후 할 일을 구조적으로 정리합니다.

    이 과정에서 사용자가 말한 내용만 기반으로 합니다. 추측이나 배경지식을 덧붙이지 않습니다.

    27실제 사용 예시: 메일 답장 초안

    사용자: "아래 메일에 답장 초안 써줘."

    에이전트는 초안을 만들지만 절대 발송하지 않습니다.

    이 단계에서는 초안만 만든다. 실제 발송은 사용자가 직접 한다.

    28실제 사용 예시: 하루 마감 정리

    사용자: "오늘 마감 정리해줘. 완료: 팀 미팅, 병원, 보고서 목차 작성. 미완료: 예산표 확인, 보고서 본문 작성."

    에이전트는 완료한 일 | 남은 일 | 내일 첫 작업 추천 | 내일 오전 계획 초안을 답합니다.

    이 답장도 계획일 뿐, 자동으로 일정을 변경하지 않습니다.

    29실전 운영 시 자주 생기는 4가지 문제

    1. 알림이 너무 많음
    좋은 설정: 아침 브리핑 1회 | 중요한 일정 전 1회 | 사용자가 요청할 때만 요약 | 하루 마감 정리 1회 | 기본 알림 하루 2회
    2. 너무 많은 권한
    권장 순서: local CLI → 테스트 메시징 → 로컬 markdown → 캘린더 읽기 → 메일 읽기 → 답장 초안 → 승인 후 일정 생성 → 승인 후 메시지 발송
    3. 오래된 정보를 최신처럼 말함
    해결: 메모에 날짜 붙이기 | 최신과 과거 메모 구분 | 출처와 날짜 표시 | 오래된 정보는 "과거 메모"라고 표시
    4. 사용자가 말하지 않은 것을 지어냄
    방지: 날짜 없으면 날짜 없음 | 참석자 없으면 UNKNOWN | 메일 원문 없으면 없음 | 접근 권한 없으면 없음 표시

    30기능 확장 로드맵

    초보자의 학습 순서입니다.

    1주차: 수동 비서
    메시지 요약 | 답장 초안 | 할 일 정리 | 메모 저장 제안 | 목표: 답변 형식 안정화
    2주차: 브리핑 비서
    아침 브리핑 | 하루 마감 정리 | 일정 충돌 확인 | 할 일 우선순위 | 목표: 매일 같은 형식 유지
    3주차: 읽기 연동
    캘린더 읽기 | 메일 메타데이터 | Slack 요약 | 로컬 메모 검색 | 목표: 읽기 권한만 사용
    4주차: 승인 후 실행
    승인 후 메모 저장 | 일정 초안 생성 | 리마인더 등록 | 메시지 발송 | 목표: 실행 전 확인 형식 고정

    31RUNBOOK 만들기

    운영 문서를 만듭니다.

    nano ~/ai-agents/projects/personal-assistant/RUNBOOK.md

    내용에는 목적 | 현재 단계 | 실행 방식 | 메시징 채널 | 허용 기능 | 금지 기능 | 상태 확인 | 로그 확인 | 테스트 메시지 | 중지 및 재시작 | 백업 위치 | 장애 시 첫 조치를 기록합니다.

    32초보자가 하지 말아야 할 10가지

  • 처음부터 Gmail 전체 접근 권한 주기
  • 처음부터 캘린더 쓰기 권한 주기
  • 처음부터 메일 자동 발송 켜기
  • 실사용 메시징 계정으로 테스트하기
  • 모든 채널의 모든 메시지 읽게 하기
  • 홈 디렉터리 전체를 agent에게 열어주기
  • 오래된 메모를 최신 정보처럼 쓰게 하기
  • 모르는 정보를 추측하게 하기
  • 로그에 메일 본문과 개인정보 무제한 저장하기
  • 테스트 bot과 운영 bot을 같은 채널에 넣기

    • 33완료 기준

    아래 항목을 통과하면 14단원 완료입니다.

    설계

    [ ] 할 일 정의 [ ] 하지 않을 일 정의 [ ] 안전 등급 1~4 [ ] 초기 기능 5개 이하

    환경

    [ ] workspace 폴더 | [ ] todo.md | [ ] daily.md | [ ] notes 폴더 | [ ] RUNBOOK.md

    메시징

    [ ] local CLI 또는 테스트 채널 [ ] 실사용 vs 테스트 분리 [ ] 정상 응답 [ ] 중복 답장 없음

    기능

    [ ] 오늘 브리핑 [ ] 할 일 정리 [ ] 메모 저장 전 확인 [ ] 메시지 요약 [ ] 답장 초안

    보안

    [ ] API 키 출력 안 함 [ ] .env 읽기 안 함 [ ] 접근 제한 [ ] 삭제 자동 실행 안 함 [ ] UNKNOWN 표시

    34이 단원의 핵심 정리

    개인 비서형 에이전트는 사용자를 대신해 마음대로 행동하는 agent가 아니라, 사용자가 더 빨리 판단하고 안전하게 실행하도록 돕는 agent입니다.

    가장 중요한 순서는: 읽기 전용 → 요약 → 초안 → 승인 후 실행 → 제한된 자동화

    초보자가 기억할 문장은 한 가지입니다. "좋은 개인 비서형 에이전트는 많이 일하는 것이 아니라, 사용자를 신뢰하고 사용자 승인을 우선하는 에이전트다."

    다음 단원

    개인 비서형 에이전트의 기본 구조를 갖춘 뒤, 트레이딩 보조 알림봇과 업무 자동화 에이전트를 만들 때 어떤 기능을 허용하고 어떤 기능을 금지해야 하는지 더 엄격하게 나눕니다.

    15. 실전 사례 2: 트레이딩 보조 알림봇 만들기

    01이 단원에서 하는 일

    이번 단원의 목표는 세 가지입니다.

    첫째, 가격 조건에 도달했을 때 메시지로 알려주는 알림 구조를 만듭니다.

    둘째, 중요한 뉴스나 시장 이벤트를 요약해서 보내는 구조를 만듭니다.

    셋째, 매매일지와 리스크 체크리스트를 에이전트가 도와주도록 만듭니다.

    처음부터 복잡하게 만들 필요는 없습니다. 트레이딩 보조 알림봇은 다음 순서로 만드는 것이 가장 안전합니다:

    1. 가격 알림
    2. 뉴스 요약 알림
    3. 매매일지 기록 보조
    4. 리스크 체크리스트
    5. 사용자 승인 후 제한된 자동화

    02프로젝트 구조 설계

    이 단원에서 만들 결과물은 다음과 같은 구조입니다:

    trading-assistant/ ├── README.md ├── RUNBOOK.md ├── alerts/ │ ├── price-rules.md │ ├── news-rules.md │ └── risk-rules.md ├── logs/ │ ├── alerts.log │ └── trades-journal.md └── prompts/ ├── trading-bot-system-prompt.md ├── alert-summary-prompt.md └── risk-check-prompt.md

    처음에는 코드보다 구조가 중요합니다. 어떤 알림을 받을지, 어떤 알림은 받지 않을지, 어떤 정보는 반드시 출처를 표시할지부터 정해야 합니다.

    03하면 좋은 것과 하면 안 되는 것

    트레이딩 보조 알림봇이 하면 좋은 일은 다음과 같습니다:

    반대로 하면 안 되는 일도 분명히 정해야 합니다:

    알림봇은 트레이더의 판단을 대신하지 않는다. 알림봇은 판단 전에 확인해야 할 정보를 정리해준다.

    04시스템 프롬프트 설계

    이 원칙을 시스템 프롬프트에 명확히 넣어야 합니다:

    너는 트레이딩 보조 알림봇이다. 너는 매수, 매도, 보유를 지시하지 않는다. 너는 투자 판단을 대신하지 않는다. 너는 사용자가 정한 조건, 가격, 뉴스, 리스크 체크리스트를 정리해준다. 출처가 없는 정보는 확정적으로 말하지 않는다. 불확실한 정보는 반드시 불확실하다고 표시한다.

    이 한 문장 차이가 매우 큽니다. 에이전트가 "사야 합니다"라고 말하기 시작하면 위험합니다. 대신 "사용자가 설정한 조건에 도달했습니다. 확인할 항목은 다음과 같습니다"라고 말해야 합니다.

    05가격 알림 구조 (1/2)

    가격 알림은 가장 단순하면서도 가장 실용적인 기능입니다. 예를 들어 사용자가 다음과 같이 조건을 정합니다:

    BTC가 70,000달러를 돌파하면 알려줘. ETH가 5분 안에 3% 이상 움직이면 알려줘. AAPL이 전일 종가 대비 -2% 이하로 내려가면 알려줘.

    이때 알림봇은 세 가지를 구분해야 합니다.

    첫째, 단순 가격 도달 알림:

    [가격 알림] 종목: BTC 조건: 70,000달러 돌파 현재가: 70,120달러 상태: 조건 충족 시각: 2026-06-14 09:15

    둘째, 변동성 알림:

    [변동성 알림] 종목: ETH 조건: 5분 기준 3% 이상 변동 현재 변동률: +3.4% 상태: 조건 충족 확인 필요: 거래량, 뉴스, 주요 지지·저항 구간

    06가격 알림 구조 (2/2) — 쿨다운 규칙

    알림봇에서 가장 짜증나는 문제는 같은 알림이 계속 오는 것입니다. 그래서 가격 알림에는 반드시 쿨다운 규칙을 넣어야 합니다:

    같은 조건의 알림은 30분 안에 반복 발송하지 않는다. 단, 가격이 조건가에서 1% 이상 추가 이동하면 한 번 더 알림을 보낼 수 있다.

    가격 알림 규칙 파일은 다음처럼 작성할 수 있습니다:

    ## 공통 규칙 - 같은 조건의 알림은 30분 안에 반복하지 않는다. - 알림에는 반드시 종목, 조건, 현재가, 시각을 포함한다. - 매수·매도 의견은 포함하지 않는다. - 사용자가 정한 조건만 감시한다. ## BTC 알림 - 70,000달러 돌파 시 알림 - 68,000달러 이탈 시 알림 - 5분 기준 2.5% 이상 변동 시 알림

    처음에는 많은 종목을 넣지 않는 것이 좋습니다. 3개 이하의 종목으로 시작해서 알림 품질을 확인한 뒤 늘리는 것이 안전합니다.

    07뉴스 요약 알림 구조 (1/2)

    트레이딩에서 뉴스 알림은 유용하지만 위험합니다. 뉴스는 빠르게 퍼지지만, 잘못된 정보도 빠르게 퍼집니다. 따라서 뉴스 요약 알림에는 다음 원칙이 필요합니다:

    좋은 뉴스 알림 예시:

    [뉴스 요약 알림] 종목/자산: BTC 분류: 규제 / ETF / 거시경제 출처: 예시 뉴스 소스 발행 시각: 2026-06-14 08:40 요약: - 미국 시장에서 비트코인 관련 ETF 자금 유입이 증가했다는 보도가 나왔습니다. - 기사 기준으로는 기관 수요 증가 가능성이 언급됐습니다. - 단기 가격 영향은 확인되지 않았습니다. 주의: - 이 알림은 투자 판단이 아닙니다. - 가격, 거래량, 기존 시나리오를 함께 확인해야 합니다.

    08뉴스 요약 알림 구조 (2/2) — 뉴스 요약 프롬프트

    나쁜 뉴스 알림은 "BTC 대형 호재 발생. 지금 매수 기회입니다." 같은 형태입니다. 이런 알림은 절대 만들면 안 됩니다.

    뉴스 요약 프롬프트는 다음처럼 만들 수 있습니다:

    다음 뉴스를 트레이딩 보조용으로 요약해줘. 규칙: 1. 제목과 본문 내용을 구분한다. 2. 확인된 사실과 추정을 구분한다. 3. 출처와 발행 시각을 표시한다. 4. 매수, 매도, 보유 의견을 말하지 않는다. 5. 가격 영향은 단정하지 않는다. 6. 오래된 뉴스일 가능성이 있으면 날짜를 강조한다.

    09매매일지 기록 보조 (1/2)

    트레이딩에서 실력을 키우는 데 가장 중요한 도구 중 하나는 매매일지입니다. 하지만 실제로는 매번 기록하기가 귀찮습니다.

    에이전트를 활용하면 기록 부담을 줄일 수 있습니다. 사용자가 메시지로 이렇게 보냅니다:

    BTC 롱 진입. 70100. 이유는 1시간봉 돌파. 손절 69400. 목표 71500.

    알림봇은 이를 다음처럼 정리할 수 있습니다:

    ## 매매일지 - 일시: 2026-06-14 09:32 - 자산: BTC - 방향: 롱 - 진입가: 70,100 - 진입 이유: 1시간봉 돌파 - 손절 기준: 69,400 - 목표 구간: 71,500 - 포지션 크기: 미입력 - 감정 상태: 미입력 - 뉴스 이벤트 확인: 미입력 ## 추가로 확인할 항목 - 포지션 크기를 기록했는가? - 손절 기준이 실제 주문 또는 알림으로 설정되어 있는가? - 진입 전 주요 뉴스 이벤트를 확인했는가?

    10매매일지 기록 보조 (2/2) — 기록 보조 프롬프트

    여기서 핵심은 에이전트가 평가자가 아니라 기록 보조자라는 점입니다. "좋은 진입입니다" 또는 "나쁜 진입입니다"라고 판단하게 만들면 안 됩니다.

    매매일지 보조 프롬프트는 다음처럼 사용할 수 있습니다:

    너는 매매일지 기록 보조자다. 사용자의 매매 메시지를 구조화해서 기록한다. 매수·매도 판단을 평가하지 않는다. 누락된 항목이 있으면 질문 목록으로 정리한다. 반드시 포함할 항목: - 일시 - 자산 - 방향 - 진입가 - 진입 이유 - 손절 기준 - 목표 구간 - 포지션 크기 - 감정 상태 - 뉴스 이벤트 확인 여부

    처음에는 자동 저장보다 초안 작성이 안전합니다. 에이전트가 매매일지 초안을 보내고, 사용자가 확인한 뒤 저장하는 방식이 좋습니다.

    11리스크 관리 체크리스트 (1/2)

    트레이딩 보조 알림봇의 진짜 가치는 리스크 관리에서 나옵니다. 가격 알림은 누구나 만들 수 있습니다. 하지만 진입 전에 리스크를 한 번 더 확인하게 만드는 봇은 실사용 가치가 큽니다.

    사용자가 이렇게 말합니다:

    나스닥 숏 들어갈까?

    이때 봇이 "들어가도 됩니다"라고 말하면 안 됩니다. 대신 이렇게 응답해야 합니다:

    [진입 전 리스크 체크] 나는 매수·매도 판단을 대신하지 않습니다. 진입 전 아래 항목을 확인하세요. 1. 진입 근거 - 현재 숏을 보는 이유는 무엇인가요? - 시간 프레임은 무엇인가요? 2. 손절 기준 - 무효화 가격은 어디인가요? - 손절 시 손실률은 계좌 대비 몇 %인가요? 3. 포지션 크기 - 이번 거래의 최대 손실 금액은 얼마인가요? - 레버리지를 사용하나요? 4. 이벤트 리스크 - 오늘 주요 경제지표나 연설 일정이 있나요? - 장 시작 또는 장 마감 근처인가요? 5. 감정 상태 - 복수매매인가요? - 연속 손실 후 진입인가요? - 계획된 진입인가요?

    12리스크 관리 체크리스트 (2/2) — 리스크 규칙 파일

    이런 응답은 사용자의 판단을 방해하지 않으면서도 충동 매매를 줄여줍니다.

    리스크 체크리스트 파일은 다음처럼 만들 수 있습니다:

    ## 진입 전 체크 - 진입 근거가 명확한가? - 손절 기준이 있는가? - 목표 구간이 있는가? - 포지션 크기가 계좌 기준으로 과하지 않은가? - 레버리지 사용 여부를 확인했는가? - 주요 뉴스 이벤트를 확인했는가? - 감정적 진입은 아닌가? ## 청산 전 체크 - 원래 계획에 따른 청산인가? - 손절 기준에 도달했는가? - 익절 기준에 도달했는가? - 공포나 탐욕으로 결정하고 있지 않은가? ## 금지 응답 - 지금 사세요 - 지금 파세요 - 무조건 오릅니다 - 무조건 빠집니다 - 손절하지 마세요 - 레버리지를 더 쓰세요

    리스크 관리 기능은 트레이딩 보조 알림봇에서 가장 먼저 안정화해야 하는 기능입니다.

    13테스트 방법 (1/2)

    트레이딩 보조 알림봇은 실사용 전에 반드시 테스트해야 합니다.

    첫 번째는 모의 알림 테스트:

    테스트: BTC가 70,000달러를 돌파했다고 가정하고 알림 메시지를 만들어줘.

    정상 응답은 다음 조건을 만족해야 합니다:

    두 번째는 중복 알림 테스트:

    같은 BTC 70,000달러 돌파 알림이 5분 안에 다시 발생했다고 가정해줘.

    정상 응답은 중복 알림을 보내지 않거나, "쿨다운 중"이라고 표시해야 합니다:

    [알림 보류] 조건: BTC 70,000달러 돌파 사유: 동일 조건 알림이 5분 전에 발송됨 다음 알림 가능 시각: 09:55

    14테스트 방법 (2/2) — 데이터 및 시장 시간 테스트

    세 번째는 잘못된 데이터 테스트:

    BTC 현재가가 UNKNOWN으로 들어왔다고 가정해줘.

    정상 응답은 가격을 지어내지 않아야 합니다:

    [알림 보류] 사유: 현재가 데이터가 확인되지 않음 처리: 가격 데이터 소스 확인 필요

    네 번째는 시장 휴장 테스트:

    주식이나 선물처럼 거래 시간이 있는 상품은 휴장일과 장외 시간을 구분해야 합니다:

    AAPL 가격 알림이 주말에 발생했다고 가정해줘.

    정상 응답은 시장 시간 확인을 요구해야 합니다:

    [확인 필요] AAPL은 현재 정규장 시간이 아닐 수 있습니다. 가격 데이터가 지연 또는 장외 기준일 수 있으므로 확인이 필요합니다.

    이 테스트를 통과한 뒤에야 실제 알림 채널에 연결하는 것이 좋습니다.

    15실제 사용 예시 (1/2)

    가격 도달 알림:

    [가격 알림] 종목: BTC 조건: 70,000달러 돌파 현재가: 70,120달러 시각: 2026-06-14 09:15 상태: 조건 충족 확인할 항목: - 돌파 후 거래량 증가 여부 - 기존 시나리오와 일치하는지 - 손절 기준이 정해져 있는지 주의: 이 알림은 매수·매도 판단이 아닙니다.

    변동성 급증 알림:

    [변동성 알림] 종목: ETH 조건: 5분 기준 3% 이상 변동 현재 변동률: +3.4% 시각: 2026-06-14 10:05 확인할 항목: - 뉴스 발생 여부 - 거래량 급증 여부 - 주요 지지·저항 구간 접근 여부 - 이미 늦은 추격 진입인지 여부

    16실제 사용 예시 (2/2)

    뉴스 요약 알림:

    [뉴스 요약 알림] 자산: BTC 분류: 시장 뉴스 출처: 사용자가 제공한 링크 발행 시각: 확인 필요 핵심 내용: - 기사 제목 기준으로 비트코인 관련 시장 움직임이 언급되었습니다. - 본문 확인 전까지는 제목만으로 가격 영향을 단정할 수 없습니다. 확인 필요: - 발행 시각 - 원문 출처 - 실제 가격 반응 - 거래량 변화

    매매일지 작성 보조:

    [매매일지 초안] 일시: 2026-06-14 11:20 자산: BTC 방향: 롱 진입가: 70,100 진입 이유: 1시간봉 돌파 손절 기준: 69,400 목표 구간: 71,500 포지션 크기: 미입력 감정 상태: 미입력 추가 확인 질문: 1. 이번 거래의 최대 손실률은 몇 %인가요? 2. 진입 전 뉴스 이벤트를 확인했나요? 3. 이 거래는 계획된 진입인가요, 즉흥 진입인가요?

    이 정도만 되어도 실제 트레이딩 루틴에서 충분히 쓸 수 있습니다.

    17초보자가 하지 말아야 할 것

    첫째, 자동 매매부터 만들지 않아야 합니다. AI 에이전트가 메시지를 이해하고 주문을 실행하는 구조는 매우 위험합니다. 오타, 중복 메시지, 잘못된 데이터, API 오류, 네트워크 지연이 모두 실제 손실로 이어질 수 있습니다. 처음에는 반드시 알림과 기록까지만 사용해야 합니다.

    둘째, 출처 없는 뉴스로 알림을 보내지 않아야 합니다. 트레이딩에서는 속도도 중요하지만 정확도가 더 중요합니다. 출처 없는 정보는 "확인 필요"로 표시해야 합니다.

    셋째, 손절 기준 없이 알림만 늘리지 않아야 합니다. 가격 알림이 많아질수록 진입 충동도 커질 수 있습니다. 알림봇은 기회를 늘리는 도구가 아니라, 확인해야 할 조건을 정리하는 도구여야 합니다.

    넷째, 투자 조언처럼 말하게 하지 않아야 합니다. 에이전트가 "매수하세요", "매도하세요", "지금 진입하세요", "확실합니다", "무조건 갑니다", "손절하지 마세요", "레버리지를 높이세요" 같은 표현을 쓰지 못하게 해야 합니다.

    대신 "조건에 도달했습니다", "확인할 항목은 다음과 같습니다", "사용자가 정한 기준과 일치하는지 확인하세요", "출처 확인이 필요합니다", "리스크 체크가 필요합니다" 같은 표현을 쓰게 해야 합니다. 이 차이가 안전한 운영의 핵심입니다.

    18트레이딩 보조 알림봇 완료 기준 (1/2)

    트레이딩 보조 알림봇은 다음 기준을 통과해야 실사용에 들어갈 수 있습니다.

    데이터 체크리스트

    알림 체크리스트

    19트레이딩 보조 알림봇 완료 기준 (2/2)

    뉴스 요약 체크리스트

    리스크 관리 체크리스트

    운영 체크리스트

    완료 기준은 "알림이 온다"가 아닙니다. 완료 기준은 "잘못된 알림을 줄이고, 판단을 대신하지 않으며, 사용자의 리스크 관리를 돕는다"입니다.

    20이 단원의 핵심 정리

    트레이딩 보조 알림봇은 자동매매 봇이 아닙니다.

    좋은 알림봇은 사용자의 판단을 대신하지 않습니다. 대신 사용자가 놓치기 쉬운 가격, 뉴스, 기록, 리스크 항목을 정리해줍니다.

    처음에는 가격 알림과 매매일지 보조부터 시작하는 것이 좋습니다. 뉴스 요약은 출처와 시각을 반드시 표시해야 하며, 리스크 체크리스트는 진입 전 습관처럼 작동하게 만들어야 합니다.

    가장 중요한 운영 원칙은 세 가지입니다.

    1. 출처와 시각을 표시합니다.
    2. 중복 알림을 줄입니다.
    3. 매수·매도 판단은 사용자가 직접 합니다.

    이 원칙을 지키면 Mac mini 위의 NanoClaw 또는 HermesClaw는 단순한 메시징 에이전트를 넘어, 트레이딩 루틴을 정리해주는 실전 보조 도구가 될 수 있습니다.

    16. 실전 사례 3: 업무 자동화 에이전트 만들기

    01이 단원에서 하는 일

    업무 자동화 에이전트는 세 가지 목표로 나뉩니다.

    첫째, 반복되는 업무를 찾아 자동화 후보로 분류합니다. 둘째, 메시지와 문서를 요약하고 액션 아이템을 정리하는 구조를 만듭니다. 셋째, 실행이 필요한 작업은 반드시 사용자 승인 후 처리하는 흐름을 만듭니다.

    처음부터 모든 업무를 자동화하려고 하면 실패하기 쉽습니다. 업무 자동화는 다음 순서로 시작하는 것이 안전합니다:

    1. 읽기 전용 요약
    2. 분류와 정리
    3. 초안 작성
    4. 승인 후 실행
    5. 제한된 반복 자동화

    02결과물 디렉토리 구조

    업무 자동화 에이전트는 기능보다 규칙이 먼저입니다. 무엇을 해도 되는지, 무엇은 하면 안 되는지, 무엇은 승인 후에만 가능한지를 먼저 정해야 합니다.

    이 단원에서 만드는 에이전트의 결과물은 다음 구조로 구성됩니다:

    work-agent/ ├── README.md ├── RUNBOOK.md ├── rules/ │ ├── message-classification.md │ ├── summary-rules.md │ ├── file-organizing-rules.md │ └── approval-rules.md ├── logs/ │ ├── actions.log │ └── approvals.log └── prompts/ ├── work-agent-system-prompt.md ├── message-summary-prompt.md ├── action-item-prompt.md └── approval-check-prompt.md

    03좋은 자동화 대상의 특징

    업무 자동화의 첫 단계는 반복 업무를 찾는 것입니다. 좋은 자동화 대상은 다음 특징을 가집니다:

    예를 들어 아침마다 읽어야 할 메시지 요약, 회의 후 액션 아이템 정리, 이메일 답장 초안 작성, 다운로드 폴더 파일명 정리 후보 만들기, 주간 업무 보고 초안 작성, 고객 문의 내용을 유형별로 분류하기 같은 작업은 자동화 후보가 될 수 있습니다.

    04자동화하면 위험한 업무

    반대로 자동화하면 위험한 업무도 있습니다. 에이전트는 다음 작업을 절대 자동으로 실행해서는 안 됩니다:

    업무 자동화 에이전트에게 처음부터 실행 권한을 주면 안 됩니다. 처음에는 "정리만 하는 에이전트"로 시작해야 합니다.

    처음에는 "많이 자동화하는 것"보다 "안전하게 반복되는 작업 하나를 줄이는 것"이 중요합니다.

    05자동화 후보 정리 파일

    반복 업무를 정리하는 파일은 다음처럼 만들 수 있습니다:

    # automation-candidates.md ## 자동화 후보 ### 매일 반복 - 아침 메시지 요약 - 오늘 할 일 정리 - 주요 메일 분류 ### 매주 반복 - 주간 업무 보고 초안 - 회의록 정리 - 미완료 작업 목록 정리 ### 자동화하면 위험한 일 - 메일 자동 발송 - 파일 자동 삭제 - 고객 정보 외부 공유 - 결제 또는 계약 관련 실행 ## 현재 자동화 단계 - 1단계: 읽기 전용 - 2단계: 초안 작성 - 3단계: 승인 후 실행

    06메시지 분류의 중요성

    업무 자동화 에이전트의 가장 기본 기능은 메시지 분류입니다. 하루에 들어오는 메시지를 모두 같은 중요도로 보면 피로도가 높아집니다. 에이전트가 메시지를 다음처럼 분류해주면 확인 순서를 정하기 쉬워집니다:

    1. 긴급 메시지
    2. 답장 필요 메시지
    3. 참고용 메시지
    4. 보류할 메시지
    5. 스팸 또는 무시 가능 메시지

    분류 기준은 명확해야 합니다. 분류 기준이 애매하면 에이전트가 일관성 있게 판단하지 못합니다.

    07메시지 분류 규칙

    메시지 분류 규칙은 다음처럼 정할 수 있습니다:

    긴급 메시지: 오늘 안에 처리해야 하는 요청, 장애·오류·결제·계약·고객 불만 관련 내용, 상급자 또는 핵심 고객의 직접 요청, 일정 변경이나 마감 임박 내용

    답장 필요 메시지: 질문이 포함된 메시지, 확인 요청이 있는 메시지, 일정 조율이 필요한 메시지, 자료 요청이 있는 메시지

    참고용 메시지: 공지사항, 뉴스레터, 회의 공유 자료, 답장이 필요 없는 진행 상황 공유

    보류할 메시지: 정보가 부족한 요청, 담당자가 불명확한 요청, 지금 판단하기 어려운 내용

    금지 사항: 에이전트가 임의로 답장을 보내지 않으며, 긴급 여부가 애매하면 "확인 필요"로 표시합니다. 사람 이름, 고객명, 금액, 일정은 지어내지 않습니다.

    08메시지 분류 결과 예시

    실제 메시지 분류 결과는 다음처럼 나올 수 있습니다:

    [메시지 분류 결과] 분류: 답장 필요 보낸 사람: 김OO 핵심 내용: 내일 회의 시간 변경 가능 여부 문의 필요 행동: 가능한 시간 확인 후 답장 긴급도: 중간 마감 추정: 오늘 중 답장 권장 주의: 캘린더 확인 전 확정 답변 금지

    여기서 중요한 점은 "분류"와 "실행"을 분리하는 것입니다. 에이전트는 답장이 필요하다고 알려줄 수 있지만, 실제 답장은 사용자가 확인한 뒤 보내야 합니다.

    09업무용 요약의 좋은 형식

    업무 자동화 에이전트에서 가장 많이 쓰는 기능은 요약입니다. 요약 대상은 회의 내용, Slack/Discord 메시지, 이메일, 긴 문서, 고객 문의, 업무 지시, 프로젝트 진행 상황 등 다양합니다.

    좋은 요약은 짧기만 한 요약이 아닙니다. 업무에 바로 쓸 수 있어야 합니다. 업무용 요약은 다음 형식이 좋습니다:

    [업무 요약] 핵심 내용: - 결정된 사항: - 액션 아이템: - 담당자: - 할 일: - 마감: 확인 필요: - 리스크: -

    10회의 요약 프롬프트

    회의 요약 프롬프트는 다음처럼 만들 수 있습니다:

    너는 업무 회의 요약 보조자다. 다음 내용을 업무용으로 요약한다. 규칙: 1. 핵심 내용과 액션 아이템을 구분한다. 2. 담당자, 할 일, 마감일을 따로 표시한다. 3. 불확실한 내용은 확정처럼 쓰지 않는다. 4. 누락된 정보는 "확인 필요"에 넣는다. 5. 회의에 없는 내용을 지어내지 않는다. 출력 형식: [회의 요약] - 핵심 내용: - 결정된 사항: - 액션 아이템: - 확인 필요: - 리스크:

    11회의 요약 실제 예시

    회의 메모가 "이번 주 안에 랜딩페이지 초안 만들고, 다음 주 월요일에 광고 소재 검토. 민수님은 카피 초안, 지연님은 디자인 시안. 예산은 아직 확정 안 됨"이라고 가정하면, 에이전트는 다음처럼 정리해야 합니다:

    [회의 요약] 핵심 내용: - 랜딩페이지 초안을 이번 주 안에 준비하기로 했습니다. - 다음 주 월요일에 광고 소재를 검토하기로 했습니다. 액션 아이템: - 민수님: 카피 초안 작성 - 지연님: 디자인 시안 작성 확인 필요: - 예산 확정 여부 - 랜딩페이지 초안 마감일의 정확한 날짜 - 광고 소재 검토 시간 리스크: - 예산이 확정되지 않아 광고 집행 일정이 밀릴 수 있습니다.

    이런 요약은 업무 흐름을 정리하는 데 바로 사용할 수 있습니다.

    12파일 정리 자동화의 안전한 구조

    파일 정리 자동화는 편리하지만 조심해야 합니다. 처음부터 파일을 자동 삭제하거나 이동하게 만들면 위험합니다. 먼저 "정리 후보"만 만들고, 사용자가 확인한 뒤 실행하는 방식이 안전합니다.

    다운로드 폴더에 파일이 많을 때 에이전트가 다음처럼 정리 후보를 만들 수 있습니다:

    [파일 정리 후보] 1. 문서 후보 - 2026_project_plan.pdf - meeting_notes.docx 추천 폴더: - Documents/Work/Projects/ 2. 이미지 후보 - screenshot-2026-06-14.png - chart-export.png 추천 폴더: - Pictures/Screenshots/ 3. 중복 의심 후보 - report_final.pdf - report_final_copy.pdf 권장 조치: - 자동 삭제하지 말고 사용자가 직접 확인

    13파일 정리 규칙

    파일 정리 규칙은 다음처럼 정할 수 있습니다:

    기본 원칙: 삭제는 자동으로 하지 않으며, 이동도 처음에는 자동으로 하지 않습니다. 정리 후보 목록만 만들고, 파일명 변경은 사용자 승인 후 실행합니다. 중복 파일은 "삭제 후보"가 아니라 "확인 후보"로 표시합니다.

    분류 기준: 문서(pdf, docx, hwp, txt, md), 이미지(png, jpg, jpeg, webp), 압축 파일(zip, tar, gz), 개발 파일(js, py, json, yaml, env)

    위험 파일: .env, key 파일, 인증서 파일, 계약서, 세금 자료, 고객 정보가 포함된 파일은 자동 수정하거나 이동하지 않습니다.

    14파일 이동 확인 예시

    실제 운영에서는 에이전트가 파일을 바로 바꾸지 않고, 먼저 명령어 초안을 보여주는 방식이 좋습니다:

    [실행 전 확인] 아래 파일 이동을 제안합니다. 이동 전: ~/Downloads/meeting_notes.docx 이동 후: ~/Documents/Work/Meetings/meeting_notes.docx 실행하려면 "승인"이라고 답하세요.

    이 구조를 지키면 파일 정리 자동화도 안전하게 운영할 수 있습니다.

    15승인 후 실행 구조

    업무 자동화에서 가장 중요한 구조는 승인 후 실행입니다. 에이전트가 할 수 있는 일을 네 단계로 나누면 안전합니다:

    1. 읽기
    2. 정리
    3. 초안 작성
    4. 사용자 승인 후 실행

    예를 들어 이메일 답장 자동화는 다음처럼 구성해야 합니다: 사용자가 "이 메일 답장 초안 만들어줘"라고 요청하면, 에이전트가 초안을 작성하고 발송하지 않습니다. 사용자가 "좋아. 보내"라고 하면, 에이전트가 발송 전에 다시 확인합니다.

    16승인 규칙 정의

    승인 규칙은 명확해야 합니다.

    승인 없이 가능한 작업: 요약, 분류, 체크리스트 생성, 답장 초안 작성, 파일 정리 후보 생성

    승인 후 가능한 작업: 이메일 발송, 캘린더 일정 생성, 파일 이동, 파일명 변경, 외부 공유 링크 생성

    금지 작업: 파일 자동 삭제, 결제 실행, 계약서 자동 발송, 고객 정보 외부 전송, 비밀번호나 API 키 출력, 사용자 확인 없는 대량 메시지 발송

    승인 문구: 실행 전에는 반드시 실행할 작업, 대상, 변경 전 상태, 변경 후 상태, 되돌리는 방법, 필요한 승인 문구를 보여줍니다.

    17실행 승인 요청 예시

    실제 승인 요청 메시지는 다음처럼 만들 수 있습니다:

    [실행 승인 요청] 작업: 파일 이동 대상: ~/Downloads/report.pdf 이동 위치: ~/Documents/Work/Reports/report.pdf 주의: - 이 작업은 파일 위치를 변경합니다. - 삭제는 하지 않습니다. - 문제가 있으면 다시 Downloads 폴더로 이동할 수 있습니다. 실행하려면 다음 문구를 그대로 입력하세요. 승인: report.pdf 이동

    승인 문구를 구체적으로 만들면 실수로 "응" 또는 "그래"라고 답했을 때 실행되는 문제를 줄일 수 있습니다.

    18아침 업무 브리핑 예시

    실제 사용 예시는 다음과 같습니다. 아침 업무 브리핑:

    [아침 업무 브리핑] 오늘 확인할 항목: 1. 오전 10시 팀 회의 2. 어제 미답장 메일 3건 3. 오늘 마감 예정 작업 2건 우선순위: - 고객 문의 답장 - 회의 자료 최종 확인 - 주간 보고서 초안 작성 주의: - 일정 변경 여부는 캘린더에서 다시 확인 필요

    19액션 아이템 정리 예시

    회의 후 액션 아이템 정리:

    [액션 아이템 정리] 회의 주제: 신규 랜딩페이지 제작 결정된 사항: - 이번 주 안에 초안 작성 - 다음 주 월요일 광고 소재 검토 할 일: 1. 민수님: 카피 초안 작성 2. 지연님: 디자인 시안 작성 3. 사용자: 예산 확정 여부 확인 확인 필요: - 정확한 마감일 - 광고 소재 검토 시간 - 예산 확정 여부

    20메일 답장 초안 예시

    메일 답장 초안:

    [메일 답장 초안] 안녕하세요, 김OO님. 문의 주신 회의 일정 변경 건 확인했습니다. 현재 가능한 시간대를 확인한 뒤 다시 회신드리겠습니다. 감사합니다. 주의: - 아직 발송하지 않았습니다. - 실제 가능한 시간은 캘린더 확인 후 넣어야 합니다.

    21파일 정리 후보 예시

    다운로드 폴더 정리 후보:

    [다운로드 폴더 정리 후보] 문서 파일: - project_plan.pdf - meeting_notes.docx 이미지 파일: - screenshot-001.png - chart-export.png 중복 의심: - report_final.pdf - report_final_copy.pdf 권장: - 삭제하지 말고 먼저 확인하세요. - 이동은 사용자 승인 후 진행하세요.

    이 정도 기능만 있어도 업무 시간과 정리 피로를 크게 줄일 수 있습니다.

    22운영 중 주의할 점

    업무 자동화 에이전트는 개인 비서형 에이전트보다 더 조심해야 합니다. 업무 데이터에는 고객 정보, 내부 문서, 계약 내용, 일정, 금액 정보가 포함될 수 있기 때문입니다.

    첫째, 업무 계정 권한을 최소화합니다. 처음부터 Gmail 전체, Drive 전체, Calendar 전체 권한을 주지 않고 필요한 폴더, 라벨, 채널부터 제한적으로 연결합니다.

    둘째, 고객 정보와 개인정보를 보호해야 합니다. 에이전트가 요약을 만들 때 고객명, 전화번호, 이메일, 계약 금액 같은 정보가 외부 로그나 메시징 채널에 나가지 않도록 합니다.

    23보안과 감사 로그

    셋째, 자동 발송은 금지합니다. 업무에서 가장 위험한 자동화는 자동 발송입니다. 이메일, 고객 메시지, 계약 관련 안내는 반드시 사용자 확인 후 발송해야 합니다.

    넷째, 감사 로그를 남깁니다. 에이전트가 어떤 요청을 받았고, 어떤 초안을 만들었고, 어떤 작업을 실행했는지 기록해야 합니다.

    [2026-06-14 09:30] 요청: 회의록 요약 작업: 요약 생성 실행 여부: 읽기 전용 결과: 사용자에게 요약 전송 [2026-06-14 10:15] 요청: report.pdf 이동 작업: 파일 이동 제안 실행 여부: 승인 대기 결과: 미실행

    운영 로그가 있으면 문제가 생겼을 때 원인을 찾기 쉽습니다.

    24완료 기준 체크리스트

    업무 자동화 에이전트는 다음 기준을 통과해야 실사용에 들어갈 수 있습니다:

    반복 업무 정의: 자동화할 업무가 명확하고 자동화하지 않을 업무도 정했으며 읽기·정리·초안·실행 단계를 구분했고 실수했을 때 피해가 큰 업무는 제외했는가?

    메시지 분류: 긴급 기준이 있고 답장 필요 기준이 있으며 참고용 기준이 있고 애매한 메시지를 "확인 필요"로 분류하며 에이전트가 임의로 답장하지 않는가?

    요약 응답: 핵심 내용과 액션 아이템을 구분하고 담당자·할 일·마감일을 표시하며 없는 내용을 지어내지 않고 불확실한 내용은 확인 필요로 표시하는가?

    25파일 정리와 보안 체크리스트

    파일 정리: 삭제를 자동으로 하지 않고 이동 전 승인을 받으며 위험 파일을 건드리지 않고 중복 파일을 삭제 후보가 아니라 확인 후보로 표시하며 변경 전후 경로를 보여주는가?

    보안: 업무 계정 권한을 최소화했고 민감 정보가 로그에 남지 않게 했으며 외부 공유를 자동으로 하지 않고 고객 정보와 개인정보를 보호하며 API 키와 인증 파일을 출력하지 않는가?

    운영: RUNBOOK.md가 있고 중지 방법이 적혀 있으며 작업 로그가 남고 승인 로그가 남으며 실패 시 복구 방법이 있는가?

    26완료 기준의 핵심

    완료 기준은 "에이전트가 뭔가를 실행한다"가 아닙니다.

    완료 기준은 "사용자가 안심하고 반복 정리 작업을 맡길 수 있다"입니다.

    이 기준을 명확히 정의하고 확인하면 더 안전하고 신뢰할 수 있는 업무 자동화 에이전트를 만들 수 있습니다.

    27이 단원의 핵심 정리

    업무 자동화 에이전트는 작은 반복 업무부터 시작해야 합니다.

    처음에는 읽기, 요약, 분류, 초안 작성까지만 맡기는 것이 안전합니다. 메일 발송, 파일 이동, 일정 생성처럼 실제 변경이 발생하는 작업은 반드시 사용자 승인 후 실행해야 합니다.

    업무 자동화에서 가장 중요한 원칙은 세 가지입니다:

    이 원칙을 지키면 NanoClaw 또는 HermesClaw를 단순한 메시징 에이전트가 아니라, Mac mini 위에서 조용히 돌아가는 실전 업무 보조 시스템으로 활용할 수 있습니다.

    17. M4 / M5 기준 추천 구성

    01가벼운 입문용 구성

    NanoClaw 또는 HermesClaw를 처음 설치하고 테스트하는 사람에게 적합합니다.

    목표는 단순합니다. 메시징 에이전트 설치, local CLI 테스트, Telegram 또는 Discord 같은 테스트 채널 연결, API 기반 응답 확인, 재부팅 후 다시 실행되는지 확인.

    입문용 구성의 핵심은 CPU 성능보다 다음 항목입니다:

    추천 대상

    NanoClaw를 처음 설치하는 사용자, HermesClaw 구조를 테스트하려는 사용자, 메시징 에이전트를 한두 개만 운영하려는 사용자, 로컬 LLM보다 API 호출을 중심으로 쓸 사용자

    추천 방향

    M4 기본형부터 검토, 메모리는 최소 기준보다 한 단계 여유 있게 선택, 저장공간은 로그와 Docker 이미지를 고려해 너무 작게 잡지 않기

    Mac mini에서 에이전트가 안정적으로 켜지고, 메시지를 받고, 응답을 보낸다.

    02안정적인 실사용 구성

    에이전트를 실제 생활이나 업무에 연결하려는 사람에게 적합합니다.

    예시: 개인 비서형 에이전트, 트레이딩 보조 알림봇, 업무 요약 에이전트, 일정 브리핑 에이전트, 메시지 요약 및 답장 초안 작성, 24시간 대기형 알림 시스템.

    실사용 구성에서 봐야 할 것은 다음과 같습니다:

    에이전트 하나만 실행할 때는 가볍게 느껴지지만, 실제 운영에서는 Docker, gateway, 브라우저, 터미널, 로그, 메시징 앱, 백업 스크립트가 함께 실행됩니다.

    실사용 기준

    중복 실행되지 않는가? 재부팅 후 다시 살아나는가? API 키가 안전하게 보관되는가? 로그가 너무 커지지 않는가? 문제가 생겼을 때 복구할 수 있는가?

    추천 방향

    M4 기본형 또는 M4 Pro 검토, 메모리는 여유 있게 선택, 저장공간은 최소 구성보다 넉넉하게 선택, 로그 회전과 백업 구조를 반드시 포함

    03로컬 AI 실험용 구성

    Mac mini에서 직접 모델을 돌려보고 싶은 사람에게 적합합니다.

    로컬 AI 실험: 로컬 LLM 실행, 작은 모델 추론 테스트, 문서 요약 실험, 코드 보조 모델 테스트, embedding 또는 RAG 실험, API fallback 없이 로컬 응답 실험.

    로컬 AI 실험에서는 CPU보다 메모리가 더 중요해지는 경우가 많습니다. 모델을 메모리에 올려야 하고, 동시에 Docker나 gateway도 함께 실행될 수 있기 때문입니다.

    가벼운 실험
    작은 모델 실행, 짧은 문서 요약, 테스트용 local inference
    중간 규모 실험
    여러 모델 비교, 긴 문서 처리, RAG 실험, 메시징 에이전트와 로컬 모델 병행
    실사용급 로컬 AI
    장시간 local inference, 여러 에이전트와 모델 병행, API fallback과 로컬 모델 혼합 운영

    모델 파일, Docker 이미지, 로그, 테스트 데이터가 쌓이면 저장공간은 생각보다 빨리 줄어듭니다.

    추천 대상

    API 비용을 줄이고 싶은 사용자, 로컬 LLM을 직접 돌려보고 싶은 사용자, Gemma, Llama 계열 등 작은 모델을 테스트하려는 사용자, 에이전트와 로컬 모델을 연결해보고 싶은 사용자

    추천 방향

    메모리를 우선 고려, 저장공간을 여유 있게 선택, M4 Pro 또는 이후 Pro 라인 검토, 외장 SSD 사용 가능성도 함께 고려

    처음에는 작은 모델로 시작해서 다음을 확인하는 것이 좋습니다: 모델이 정상 실행되는가? 응답 속도가 실사용 가능한가? 메모리 압박이 심하지 않은가? 에이전트와 동시에 실행해도 안정적인가? 발열이나 팬 소음이 문제가 되지 않는가?

    0424시간 운영용 구성

    Mac mini를 작은 서버처럼 사용하는 경우입니다.

    24시간 운영에서 봐야 할 항목: 전원 안정성, 네트워크 안정성, 자동 실행, 로그 회전, 장애 복구, 백업, 발열 관리, 원격 접속.

    Mac mini는 조용하고 전력 부담이 낮아 상시 운영용으로 적합하지만, 반드시 다음 설정을 확인해야 합니다:

    24시간 운영에서는 성능보다 "문제가 났을 때 어떻게 복구할 것인가"가 더 중요합니다.
    필수 문서

    RUNBOOK.md: 실행/중지/재시작/로그 확인/재부팅 후 확인 방법. INCIDENTS.md: 장애 발생 일시, 증상, 원인, 해결 방법, 재발 방지

    추천 방향

    메모리와 저장공간을 여유 있게 선택, 유선 네트워크 우선 사용, 외장 SSD 사용 시 안정적인 제품 선택, 자동 실행과 로그 회전 설정 필수

    05M4 기준 추천

    작성일 기준으로 Mac mini는 M4와 M4 Pro 구성이 중심입니다.

    NanoClaw 또는 HermesClaw만 운영한다면 M4 기본형도 충분히 시작점이 될 수 있습니다. 메시징 에이전트, API 호출, Docker gateway, 간단한 자동 실행 정도는 고성능 GPU보다 안정적인 운영 구조가 더 중요합니다.

    M4 기본형 추천 조건
    NanoClaw를 처음 설치한다, API 기반 에이전트 중심으로 사용한다, 메시징 앱 1~2개만 연결한다, 로컬 LLM은 가볍게만 테스트한다, 비용을 줄이고 싶다, 24시간 상시 운영을 작게 시작한다
    M4 Pro 추천 조건
    Docker 컨테이너를 여러 개 운영한다, gateway, database, vector store 등을 함께 붙인다, 로컬 AI 실험을 자주 한다, 긴 문서 처리나 RAG 실험을 한다, 여러 에이전트를 동시에 운영한다, 장기적으로 업무 자동화 서버처럼 쓸 계획이다
    메모리 판단 — 메시징 에이전트 중심
    기본 메모리로 시작 가능, 실사용은 한 단계 여유 권장
    메모리 판단 — API 자동화 중심
    여러 도구를 동시에 실행할 수 있으므로 여유 메모리 권장
    메모리 판단 — 로컬 AI 실험 중심
    가능한 한 메모리를 우선 고려
    메모리 판단 — 장기 운영 중심
    메모리와 저장공간 모두 여유 있게 선택

    Mac mini를 자동화 서버처럼 쓰면 다음 파일이 계속 쌓입니다: Docker 이미지, Docker volume, 로그 파일, 백업 파일, 모델 파일, 테스트 데이터, 문서 요약 캐시.

    입문
    M4 기본형, API 기반 사용, 메시징 에이전트 1개부터 시작
    실사용
    M4 기본형 고급 구성 또는 M4 Pro, 메모리와 저장공간 여유 권장, 자동 실행/로그 회전/백업 포함
    로컬 AI 실험
    M4 Pro 우선 검토, 메모리 우선, 모델 저장공간 고려
    장기 운영
    안정성 중심, 유선 네트워크, 백업과 RUNBOOK 필수

    06M5 공식 출시 후 확인할 항목

    M5가 붙었다고 해서 무조건 현재 사용 목적에 더 좋은 선택이라고 단정할 수 없습니다. NanoClaw와 HermesClaw 운영에서는 순수 성능보다 호환성, 안정성, 가격, 메모리 옵션, Docker 지원이 더 중요할 수 있습니다.

    1. 공식 사양
    CPU 구성, GPU 구성, Neural Engine, 메모리 옵션, 저장공간 옵션, 메모리 대역폭, 포트 구성
    2. 가격
    기본형 가격, 메모리 업그레이드 비용, 저장공간 업그레이드 비용, M4 재고 또는 할인 가격과 비교
    3. Docker 호환성
    Docker Desktop Apple Silicon 지원 상태, 기존 Compose 파일 정상 실행 여부, 이미지 호환성, gateway 컨테이너 실행 여부
    4. 로컬 모델 성능
    작은 모델 추론 속도, 메모리 사용량, 발열과 전력 사용, 장시간 실행 안정성
    5. 운영 안정성
    재부팅 후 자동 실행, launchd 동작, 네트워크 안정성, 로그와 백업 구조

    M5 출시 후 바로 확인할 실전 테스트: Docker 실행 (docker info), 기본 컨테이너 실행 (docker run hello-world), NanoClaw/HermesClaw 설치 테스트, 재부팅 테스트, 로컬 모델 테스트.

    기다릴 만한 경우
    지금 당장 Mac mini가 필요하지 않다, 로컬 AI 실험 비중이 크다, 새 칩의 AI 성능 향상이 중요하다, 장기적으로 3년 이상 사용할 계획이다, M4 할인보다 최신 사양을 우선한다
    M4를 바로 선택해도 되는 경우
    지금 바로 에이전트를 운영해야 한다, API 기반 자동화가 중심이다, 메시징 에이전트 1~2개가 목적이다, 로컬 LLM은 보조 실험 정도다, 안정적인 검증 환경을 우선한다, 가격 대비 효율이 더 중요하다

    M5를 기다리는 동안에도 할 수 있는 일은 많습니다: NanoClaw 구조 이해, HermesClaw 구조 이해, 메시징 계정 준비, API 키 관리 방식 정리, RUNBOOK 템플릿 작성, 보안 규칙 정리, 자동화할 업무 목록 정리.

    내가 만들 에이전트가 API 중심인가, 로컬 AI 중심인가? 지금 필요한 것은 성능인가, 안정적인 운영 환경인가?

    0717단원 최종 추천표

    아래는 목적별 추천을 한눈에 정리한 표입니다.

    처음 설치 테스트
    M4 기본형부터 검토 | 핵심 기준: 비용, 설치 편의성, Docker 안정성
    개인 비서형 에이전트
    M4 기본형 고급 구성 또는 M4 Pro | 핵심 기준: 메모리 여유, 자동 실행, 보안
    트레이딩 알림봇
    M4 기본형 이상 | 핵심 기준: 24시간 운영, 네트워크, 중복 알림 방지
    업무 자동화 에이전트
    M4 기본형 고급 구성 또는 M4 Pro | 핵심 기준: 로그, 승인 구조, 파일 접근 제한
    로컬 AI 실험
    M4 Pro 또는 이후 Pro 라인 | 핵심 기준: 메모리, 저장공간, 모델 실행 안정성
    장기 운영 서버
    메모리와 저장공간 여유 구성 | 핵심 기준: 백업, 로그 회전, 장애 복구
    M5 대기
    공식 사양 확인 후 판단 | 핵심 기준: 가격, Docker, 로컬 모델 성능

    0817단원의 핵심 정리

    Mac mini를 NanoClaw 또는 HermesClaw 운영용으로 고를 때는 목적이 먼저입니다.

    메시징 에이전트와 API 기반 자동화가 중심이라면 M4 기본형부터 시작해도 충분히 현실적입니다. 중요한 것은 고성능보다 안정적인 실행, 자동 복구, 보안, 로그 관리입니다.

    로컬 AI 실험까지 고려한다면 메모리와 저장공간을 더 중요하게 봐야 합니다. 모델 파일과 Docker 이미지, 로그가 함께 쌓이기 때문에 처음부터 여유를 두는 것이 좋습니다.

    M5 계열은 공식 사양, 가격, Docker 호환성, 로컬 모델 성능을 확인한 뒤 판단해야 합니다. 단순히 최신 칩이라는 이유만으로 선택하기보다, 내가 만들 에이전트가 어떤 방식으로 동작하는지 먼저 정해야 합니다.

    최종 기준
    API 중심이면 안정성과 비용을 본다. 로컬 AI 중심이면 메모리와 저장공간을 본다. 24시간 운영이면 자동 실행과 복구 구조를 본다.

    이 기준으로 고르면 Mac mini를 단순한 데스크톱이 아니라, NanoClaw와 HermesClaw를 안정적으로 돌리는 개인 AI 자동화 서버로 활용할 수 있습니다.

    18. 최종 추천

    01강의 개요

    이번 편은 설치, 실행 확인, 자동 실행, 보안, 문제 해결, 실전 사례까지 다룬 앞선 강의들을 하나의 실행 순서로 압축하는 시간입니다.

    처음부터 완벽한 AI 자동화 서버를 만들려고 하지 말고, 작게 시작해서 안정적으로 운영 가능한 구조를 먼저 만든다.

    02처음 시작하는 사람에게 추천하는 순서

    기능을 많이 붙이기보다, 다음 순서로 진행하는 것이 가장 안전합니다.

    1Mac mini 준비
    2NanoClaw 설치
    3메시징 테스트
    4자동 실행 설정
    5보안 설정 → 실전 사례 적용

    031단계: Mac mini 준비

    먼저 Mac mini를 AI 자동화 서버처럼 쓸 준비를 합니다. 확인할 항목:

    Mac mini가 안정적으로 켜져 있고, 필요한 개발 도구가 정상 작동하는 상태를 먼저 만든다.

    042단계: NanoClaw 설치

    초보자라면 NanoClaw부터 시작하는 것이 좋습니다. 복잡한 gateway 구조를 이해하기 전에, 먼저 메시지를 주고받는 흐름을 확인할 수 있기 때문입니다.

    설치 폴더 만들기 → 공식 설치 명령 확인 → 설치 실행 → 인증 방식 선택 → local CLI 또는 테스트 메시징 채널 연결 → 첫 테스트 메시지 보내기

    첫날 목표 (이 정도면 충분)

    053단계: 메시징 테스트

    설치 후 바로 실사용 계정을 연결하지 않습니다. 먼저 테스트 계정이나 local CLI로 확인합니다. 테스트 메시지는 짧고 단순하게:

    안녕. 지금 테스트 중이야. 한 문장으로 답해줘.

    정상 응답 기준

    핵심

    이 단계에서 중요한 것은 "똑똑한 답변"이 아니라 안정적인 송수신입니다.

    064단계: 자동 실행과 보안 설정

    자동 실행은 편의 기능이 아니라 복구 장치입니다. 재부팅 후 에이전트가 다시 켜지지 않으면 24시간 서버로 쓰기 어렵습니다. 방식은 보통 셋 중 하나:

    수동 실행이 안정적이지 않은 상태에서 자동 실행을 켜지 않는다.

    불안정한 상태에서 자동 실행을 켜면 같은 오류를 반복 실행해 로그만 커지고 원인 파악이 어려워집니다.

    07보안 설정도 이 단계에서 함께

    자동 실행과 같이 다음을 확인합니다.

    085단계: 실전 사례 적용

    기본 실행·메시징 테스트·자동 실행·보안 설정까지 끝난 뒤에야 실전 사례를 적용합니다.

    개인 비서형 에이전트 → 트레이딩 보조 알림봇 → 업무 자동화 에이전트

    처음부터 모든 기능을 자동화하지 않습니다. 가장 안전한 시작은 읽기 전용 또는 초안 작성입니다. 개인 비서라면 오늘 할 일 정리·메시지 요약·답장 초안·메모 정리·하루 마감 요약부터, 트레이딩은 자동 매매가 아니라 알림과 기록 보조부터, 업무 자동화는 발송·삭제보다 분류·요약·초안부터 시작합니다.

    09NanoClaw가 적합한 사용자

    NanoClaw는 처음 시작하는 사람에게 가장 현실적인 출발점입니다.

    처음에는 NanoClaw로 충분합니다. HermesClaw나 복잡한 provider routing은 나중에 붙여도 됩니다.

    10NanoClaw 추천 설치 순서

    1. Mac mini 기본 환경 확인
    2. Homebrew, Git, Docker 설치 확인
    3. Node.js 또는 필요한 런타임 확인
    4. NanoClaw 설치 폴더 생성
    5. 공식 설치 명령 실행
    6. local CLI 또는 테스트 채널 선택
    7. Claude / Anthropic 인증
    8. 첫 테스트 메시지 전송
    9. 로그 확인 → 설치 후 백업

    가장 많이 실수하는 부분은 인증 방식입니다. 구독 로그인과 API 키 방식은 다르며, 섞어 쓰면 문제가 생길 수 있습니다.

    11인증 방식 기록 템플릿

    설치 중에는 이렇게 정리해두는 것이 좋습니다.

    ## 인증 방식 기록 - 사용 방식: 구독 로그인 / API 키 - provider: Claude / Anthropic / 기타 - API 키 저장 위치: .env - 테스트 완료 여부: YES / NO - 마지막 정상 응답 시각:

    12NanoClaw 실사용 전 확인 (1/2)

    메시지 송수신

    API 호출

    13NanoClaw 실사용 전 확인 (2/2)

    자동 실행

    보안 · 백업

    14NanoClaw 시작용 기본 운영 프롬프트

    설치 직후 에이전트에게 운영 규칙을 먼저 넣어둡니다.

    # 기본 운영 규칙 너는 현재 테스트 단계의 개인 AI 에이전트다. ## 목표 - 메시지를 안정적으로 받고 답한다. - 모르는 정보는 추측하지 않는다. - 실행 권한이 필요한 작업은 사용자 확인을 먼저 받는다. - API 키, 토큰, 비밀번호, 개인 정보는 절대 출력하지 않는다. ## 금지 행동 - 파일 삭제 / 외부 전송 / 자동 결제 금지 - 실사용 계정 임의 접근 금지 - 사용자가 승인하지 않은 명령 실행 금지 ## 응답 방식 - 짧고 명확하게. 오류는 원인 후보를 나눠서. - 확실하지 않은 것은 UNKNOWN으로 표시한다.

    목적은 똑똑하게 만드는 것이 아니라 초기에 위험한 행동을 막는 것입니다.

    15HermesClaw부터 시작하는 경우

    HermesClaw는 단순 앱이라기보다 프록시 계층에 가까워, 구조 이해가 더 중요합니다.

    처음부터 선택해도 되는 사람

    아직 시작하지 않는 편이 좋은 사람

    16Hermes Agent 먼저 확인하기

    HermesClaw 설치보다, 먼저 Hermes Agent가 혼자서 정상 작동해야 합니다.

    Hermes Agent 설치 → hermes 명령어 확인 → hermes doctor 실행 → provider 설정 확인 → CLI 테스트 → gateway 상태 확인

    CLI에서 짧은 요청에 정상 응답이 와야 합니다.

    지금 Hermes Agent 테스트 중이야. 한 문장으로 답해줘.

    이 단계에서 실패하면 HermesClaw를 설치해도 문제가 해결되지 않습니다.

    17OpenClaw 설정 백업

    OpenClaw에서 HermesClaw로 넘어올 때는 migration 전 반드시 백업합니다. 대상: OpenClaw·gateway 설정 파일, token 파일 목록, .env, Docker Compose, 포트 사용 상태, 기존 로그, 설치 폴더 구조.

    민감 정보는 그대로 공유하지 말고 목록과 해시만 기록합니다.

    # Migration 전 백업 기록 ## 백업 대상 - OpenClaw / Hermes 설정 폴더: - .env 파일 존재 여부: - Docker Compose 파일 / token 파일 존재 여부: ## 주의 - API 키·token 원문은 기록하지 않음 - 민감 파일은 파일명과 해시만 기록

    18Gateway 안정성 확인 + 운영 프롬프트

    HermesClaw에서 가장 중요한 것은 gateway 안정성입니다: gateway 실행 여부, 포트 충돌, baseUrl, token 유효성, 메시징 인증 유지, 로그 반복 오류. 포트 충돌이 있으면 메시지가 안 오거나, 오는데 답장이 안 나갈 수 있습니다.

    # HermesClaw 테스트 운영 규칙 ## 확인할 것 - Hermes Agent / gateway / 메시징 인증 상태 - 포트 충돌 · API 호출 · 로그 반복 오류 ## 금지할 것 - 실사용 계정 자동 연결 / token 공유 금지 - 설정 폴더 임의 삭제 / migration overwrite 임의 실행 금지 - 외부 포트 공개 금지 ## 문제 발생 시: 증상 → 원인 → 먼저 확인할 명령 → 위험한 조치 → 안전한 다음 단계

    19실사용 전 마지막 체크리스트

    설치 완료와 실사용 가능 상태는 다릅니다. 실사용 가능 상태란:

    메시지 송수신 가능 API 호출 정상 자동 실행 정상 보안 설정 완료 백업 완료 로그 확인 가능 문제 발생 시 복구 절차 있음
    방법

    아래 6개 영역(메시지·API·자동실행·보안·백업·로그)을 하나씩 통과시킵니다.

    20체크리스트 (1/2) — 메시지·API·자동 실행

    메시지 송수신

    API 호출

    자동 실행

    21체크리스트 (2/2) — 보안·백업·로그

    보안

    백업

    로그

    22장기 운영 팁 (1/2)

    작게 시작하기

    채널 1개 에이전트 1개 provider 1개 역할 1개 자동화 최소화

    작게 시작하면 문제가 생겼을 때 원인을 찾기 쉽습니다.

    업데이트는 신중하게

    23장기 운영 팁 (2/2)

    장애 기록 남기기

    발생 일시 · 증상 · 최근 변경 · 원인(확정/추정) · 해결 과정 · 재발 방지를 기록합니다. 장애 기록이 쌓이면 자동화 품질이 좋아집니다.

    테스트 환경 유지

    테스트/실사용의 폴더·.env·메시징 계정·포트를 분리하고, 테스트에서 먼저 확인한 뒤 실사용에 반영합니다.

    자동화는 승인 후 실행부터

    1단계: 읽기 전용 2단계: 요약 3단계: 초안 작성 4단계: 사용자 승인 후 실행 5단계: 제한된 자동화

    특히 발송·삭제·결제·계정 변경·외부 연동은 반드시 승인 후 실행으로 시작합니다.

    24최종 추천 정리

    처음 시작하는 사람에게 가장 추천하는 흐름:

    1. Mac mini 기본 환경 준비
    2. NanoClaw 설치
    3. local CLI 또는 테스트 채널 연결
    4. 짧은 테스트 메시지 송수신 → 로그 확인
    5. 자동 실행 설정 → 보안 설정
    6. 백업과 RUNBOOK 작성
    7. 개인 비서형 에이전트부터 적용
    8. 필요할 때 HermesClaw 검토
    작게 시작한다. 기록을 남긴다. 승인 후 실행한다.

    25강의 마무리 + 실습 과제

    설치보다 중요한 것은 안정적인 운영이다.

    좋은 서버는 하드웨어만으로 완성되지 않습니다. 운영 규칙·보안 기준·복구 절차·장애 기록이 함께 있어야 합니다.

    실습 과제

    섹션 18 · 마무리

    18편 핵심 요약

    다음 단원

    19. 업데이트 기록

    19. 업데이트 기록

    01왜 업데이트 기록을 남기나

    AI 에이전트 도구는 설치 명령어, 인증 방식, 지원 채널, Docker 구성, 모델 provider 정책이 언제든 바뀔 수 있습니다. Mac mini도 M4, M4 Pro 이후 새 칩과 구성이 나오면 추천 기준이 달라집니다.

    따라서 이 글은 한 번 쓰고 끝나는 문서가 아니라, 계속 확인하고 보완하는 운영 문서로 관리하는 것이 좋습니다.

    업데이트 기록을 남기면 좋은 점

    02최초 작성일 남기기

    먼저 최초 작성일을 남깁니다. 단순히 날짜만 적는 것이 아니라, 어떤 환경을 기준으로 작성했는지도 함께 적는 것이 좋습니다.

    ## 최초 작성일 - 작성일: 2026-06-14 - 작성 기준: Mac mini M4 / M4 Pro 기준 - 운영체제: macOS 최신 안정 버전 기준 - 주요 목적: NanoClaw / HermesClaw 설치와 운영 가이드 - 사용 방식: 메시징 기반 AI 에이전트, API 기반 자동화, Docker 운영

    03검증 환경도 함께 남기기

    어떤 환경에서 검증했는지 따로 남기면 신뢰도가 올라갑니다.

    ## 최초 검증 환경 - 장비: Mac mini M4 - CPU 아키텍처: Apple Silicon - Docker: Docker Desktop for Mac - 패키지 관리: Homebrew - 기본 도구: Git, Node.js 또는 Python - AI 사용 방식: Claude / Anthropic 계정 또는 API 키 방식 - 메시징 테스트: local CLI 또는 테스트 메시징 계정

    04기준을 단정하지 않기

    중요한 것은 "이 글이 모든 환경에서 무조건 그대로 동작한다"고 쓰지 않는 것입니다. 대신 기준을 명확히 적습니다.

    이 글은 M4 Mac mini 기준으로 작성되었습니다. M5 Mac mini 또는 이후 모델에서는 공식 사양과 도구 호환성을 다시 확인해야 합니다.
    이렇게 적어두면 시간이 지나도 글의 신뢰도를 유지할 수 있습니다.

    05M5 공식 발표 후 다시 볼 것 (1/2)

    M5 Mac mini 또는 이후 모델이 공식 출시되면 아래 항목을 다시 확인합니다.

    하드웨어 사양

    가격

    06M5 공식 발표 후 다시 볼 것 (2/2)

    운영 호환성

    로컬 AI 실험

    07M5는 확인/미확인을 나눠 기록

    M5 관련 내용을 수정할 때는 단정하지 말고, 실제 확인한 항목과 아직 확인하지 못한 항목을 나누는 것이 좋습니다.

    ## M5 확인 상태 ### 확인 완료 - Docker Desktop 실행 확인 - 기본 컨테이너 실행 확인 - 메시징 에이전트 local CLI 테스트 확인 ### 확인 필요 - 장시간 24시간 운영 안정성 - HermesClaw gateway 장기 실행 - 로컬 LLM 실사용 성능 - 발열과 전력 사용량

    이렇게 기록하면 읽는 사람이 어느 부분을 믿고 따라 해도 되는지 알 수 있습니다.

    08설치 명령어 변경 이력

    NanoClaw, Hermes Agent, HermesClaw, OpenClaw 관련 명령어는 시간이 지나면서 바뀔 수 있습니다. 설치 명령어가 바뀌면 본문만 고치지 말고 변경 이력에도 남깁니다.

    ## 설치 명령어 변경 이력 ### 2026-06-14 - 최초 작성 - NanoClaw / HermesClaw 설치 단원 추가 - Docker / launchd 자동 실행 단원 추가 ### 0000-00-00 - 공식 설치 명령 변경 확인 → 기존 명령 제거, 새 명령 반영 - 설치 후 확인 명령어 추가

    09설치 명령어 수정 시 확인할 것

    설치 명령어를 수정할 때는 반드시 다음을 함께 확인합니다.

    - 공식 문서 기준인지 - 비공식 fork 기준이 아닌지 - macOS Apple Silicon에서 동작하는지 - 기존 설치와 충돌하지 않는지 - 삭제 또는 overwrite 옵션이 포함되어 있지 않은지

    초보자용 가이드에서는 명령어를 그대로 복사해 실행하는 경우가 많으므로, 위험한 명령어는 그대로 넣지 않습니다.

    10그대로 넣으면 안 되는 명령어

    주의할 명령어: - rm -rf - sudo로 실행하는 설치 스크립트 - 출처가 불분명한 curl | bash - 기존 설정을 덮어쓰는 install 명령 - token 또는 API 키를 출력하는 명령
    원칙

    설치 명령어를 업데이트할 때는 본문에 바로 반영하기 전에 테스트 환경에서 먼저 확인합니다.

    11보안 관련 변경 이력

    AI 에이전트 운영에서 보안 기준은 계속 업데이트해야 합니다. 처음에는 API 키를 숨기는 정도로 시작하지만, 실제 운영으로 갈수록 메시징 계정, Docker 권한, 외부 접속, 파일 접근 범위, 로그 관리까지 신경 써야 합니다.

    ## 보안 관련 변경 이력 ### 2026-06-14 - .env 파일 관리 기준 추가 - API 키를 코드에 직접 쓰지 않는 원칙 추가 - 실사용/테스트 메시징 계정 분리 권장 - 외부 접속 기본 차단, Docker 권한 최소화 기준 추가 ### 0000-00-00 - API 키 rotation 절차 추가 - 로그 공유 전 민감 정보 마스킹 절차 추가 - 파일 접근 범위 제한 강화 (홈 디렉터리 전체 mount 금지, Docker socket mount 금지)

    12보안 업데이트의 한 가지 원칙

    보안 기준을 업데이트할 때는 API 키 보관 방식, .env 권한, .gitignore 설정, 메시징 계정 분리, 외부 포트 공개 여부, Docker 권한, mount 폴더 범위, 로그·백업의 민감 정보 포함 여부를 확인합니다.

    에이전트가 실수하더라도 피해 범위가 작아야 한다.

    그래서 새 기능을 붙일 때마다 "이 기능이 실패하면 무엇이 노출되거나 변경될 수 있는가?"를 확인합니다. 예: 업무 자동화에 파일 정리 기능을 추가했다면 자동 삭제 금지, 이동 전 사용자 승인, .env·key·인증서 접근 금지, 실행 로그 남김을 보안 기록에 남깁니다.

    13실전 사례 추가 이력

    이 글에서는 개인 비서형 에이전트, 트레이딩 보조 알림봇, 업무 자동화 에이전트 세 가지 사례를 다뤘습니다. 새 사례를 추가할 때는 기존과 같은 형식을 유지합니다.

    ## 실전 사례 추가 이력 ### 2026-06-14 - 개인 비서형 에이전트 사례 추가 - 트레이딩 보조 알림봇 사례 추가 - 업무 자동화 에이전트 사례 추가 ### 0000-00-00 - 문서 요약 전용 에이전트 / 개발 보조 에이전트 사례 추가

    14새 사례를 추가할 때의 질문

    새 실전 사례를 추가할 때는 반드시 다음 질문에 답해야 합니다.

    - 이 사례의 목표는 무엇인가? - 자동화하면 안 되는 일은 무엇인가? - 사용자가 승인해야 하는 작업은 무엇인가? - 실패했을 때 피해는 무엇인가? - 로그와 복구 방법은 있는가? - 초보자가 하지 말아야 할 것은 무엇인가?

    실전 사례는 기능보다 운영 기준이 중요합니다. 좋은 사례는 멋진 자동화가 아니라, 안전하게 반복해서 쓸 수 있는 자동화입니다.

    15전체 가이드 마무리

    여기까지 Mac mini에서 NanoClaw와 HermesClaw를 활용하는 전체 흐름을 살펴봤습니다. 핵심은 복잡한 AI 자동화를 한 번에 완성하는 것이 아니라, 작은 메시징 에이전트 하나를 안정적으로 실행하고 그 위에 실전 자동화를 하나씩 올리는 것입니다.

    목표는 이 순서로

    1메시지를 받고 답한다
    2재부팅 후에도 다시 실행된다
    3보안과 백업을 갖춘다
    4개인 비서·트레이딩 알림·업무 자동화 중 하나를 실제 루틴에 붙인다

    16마지막으로 기억할 다섯 원칙

    1. 작게 시작한다. 2. 실사용 계정은 나중에 연결한다. 3. 자동 실행보다 수동 실행 안정화가 먼저다. 4. 발송, 삭제, 결제, 주문은 자동화하지 않는다. 5. 문제가 생기면 재설치보다 원인 기록이 먼저다.

    중요한 것은 장비의 이름보다 운영 방식입니다. 에이전트가 무슨 일을 할 수 있는지보다, 어떤 일을 하지 않게 막을 것인지가 더 중요합니다.

    작게 시작해서 오래 운영하세요. 로그를 남기고, 백업을 만들고, 실수해도 복구할 수 있는 구조를 갖추면 Mac mini 위의 NanoClaw와 HermesClaw는 든든한 개인 자동화 시스템이 됩니다.