AI 에이전트 기초
Codex · Hermes · OpenClaw로 이해하는
로컬 작업자와 메신저 기반 AI 비서
AI 에이전트를 실제 작업 흐름에 어떻게 쓰는지 감을 잡는다
AI 에이전트 개념 이해
챗봇과 에이전트가 어떻게 다른지, 목표·도구·결과 확인의 관점에서 살펴봅니다.
Codex로 로컬 설치 보조
명령어를 무작정 따라 치기보다, Codex로 내 환경을 확인하면서 한 단계씩 이해합니다.
Hermes를 팀 업무에 배치
Discord 업무 채널, Skills, cron, Gateway가 팀 작업에서 어떻게 이어지는지 살펴봅니다.
OpenClaw를 개인 비서로 배치
Telegram과 Gateway를 통해 일정, 검색, 알림, 문서 요청을 모바일에서 처리하는 흐름을 이해합니다.
사용자를 대신해 목표를 따라가고 일을 끝까지 처리하는 AI 시스템
IBM은 “사용 가능한 도구로 작업 흐름을 설계해 일을 처리하는 시스템”, Google Cloud는 “사용자를 대신해 목표를 추구하고 작업을 완료하는 소프트웨어 시스템”으로 설명합니다.
개인 생산성
메일, 일정, 회의록을 정리하고 해야 할 일을 우선순위별로 나누어 다음 행동을 제안합니다.
고객 응대·업무 처리
문의 내용을 이해한 뒤 예약 변경, 환불 안내, 내부 시스템 조회처럼 여러 단계를 이어서 처리합니다.
소프트웨어 개발
코드를 읽고 버그 원인을 찾은 뒤, 수정안을 만들고 테스트 결과까지 확인합니다.
조사·분석
웹, 문서, 데이터를 찾아 비교하고 출처를 남기면서 의사결정에 필요한 요약을 만듭니다.
AI 에이전트의 핵심 능력
에이전트는 한 번 답하고 끝나는 도구라기보다, 목표를 기준으로 계획하고 실행하고 다시 확인하는 작업자에 가깝습니다.
목표와 계획
요청을 작업 목표로 바꾸고 필요한 단계를 나누어 봅니다.
도구 사용
파일, 터미널, 웹, 메신저, 일정 같은 도구를 상황에 맞게 사용합니다.
결과 점검
목표에 가까워졌는지 확인하고, 부족하면 다시 시도합니다.
Skills 축적
반복되는 절차와 판단 기준을 저장해 다음 작업에 다시 씁니다.
예약 작업
cron처럼 정해진 시간마다 검색, 정리, 보고서 작성을 맡길 수 있습니다.
로컬 실행
권한을 주면 PC의 프로그램, 파일, 브라우저 화면까지 작업에 활용할 수 있습니다.
대화로 답을 받는가, 작업 흐름을 맡기는가
둘의 경계가 늘 딱 잘리는 것은 아닙니다. 핵심은 “도구가 있느냐”보다, 사용자가 어느 정도의 작업 책임을 맡기느냐에 있습니다.
챗봇
- 사용자의 질문에 답하고 설명, 요약, 번역을 도와줍니다.
- 필요한 정보와 다음 행동은 주로 사용자가 정합니다.
- 결과를 실제 환경에 적용할지는 대체로 사용자가 결정합니다.
AI 에이전트
- 목표를 해석하고 필요한 단계를 나누어 진행합니다.
- 권한을 받은 범위 안에서 파일, 터미널, 브라우저, 메신저 같은 도구를 다룹니다.
- 결과를 확인하고, 부족하면 고치거나 반복 절차로 남깁니다.
Codex
내 컴퓨터의 작업 폴더를 기준으로
코드를 읽고, 수정하고, 실행 결과를 확인하는 로컬 코딩 에이전트
내 작업 폴더에서 코드를 읽고, 고치고, 실행해 보는 코딩 에이전트
OpenAI Developers 문서에 따르면 Codex CLI는 터미널에서 로컬로 실행되는 coding agent입니다. 선택한 디렉터리 안에서 코드를 읽고, 바꾸고, 실행할 수 있습니다.
로컬 작업 범위
Codex는 사용자가 열어 둔 폴더를 기준으로 파일을 읽고 수정합니다. 그래서 처음에는 반드시 연습용 폴더에서 시작합니다.
실행과 점검
코드 수정뿐 아니라 테스트, 빌드, 오류 로그 확인처럼 결과를 확인하는 명령도 함께 다룰 수 있습니다.
여러 사용 경로
CLI, IDE, Desktop app, Codex Web처럼 쓰는 방식이 나뉩니다. 이 수업에서는 로컬 작업을 돕는 도구라는 관점에서 살펴봅니다.
Codex 앱 설치 전 준비
Codex 앱을 설치하기 전에 작업 폴더, Mac 종류, 계정 로그인 상태를 확인합니다.
브라우저에서 openai.com/ko-KR/codex/ 페이지에 접속할 준비를 합니다.
Mac이 Apple Silicon인지 Intel인지 확인합니다. 다운로드 파일이 달라질 수 있습니다.
ChatGPT 계정으로 로그인할 수 있는지 확인합니다.
연습용 작업 폴더를 먼저 만듭니다. 예: ~/ai-agent-class
설치 기록과 오류 메모를 남길 install-notes.md 파일을 준비합니다.
초기 설정에서는 실제 업무 폴더가 아니라 연습용 폴더를 Codex에 지정합니다.
Codex 앱 다운로드와 설치
Codex 앱은 공식 웹사이트에서 macOS용 설치 파일을 내려받아 설치합니다.
1. 공식 Codex 페이지 접속 — 브라우저에서 openai.com/ko-KR/codex/에 들어가 macOS 다운로드 항목을 확인합니다.
2. Mac 종류에 맞는 파일 선택 — Apple Silicon Mac이면 Apple Silicon용, Intel Mac이면 Intel용 다운로드를 선택합니다.
3. 설치 파일 실행 — 다운로드한 파일을 열고 안내에 따라 Codex 앱을 Applications 폴더에 넣습니다.
4. Codex 앱 실행 — 응용 프로그램 폴더에서 Codex를 열고 ChatGPT 계정으로 로그인합니다.
5. 프로젝트 폴더 선택 — 처음 화면에서 연습용 폴더를 프로젝트로 선택하고 Local 작업 모드로 시작합니다.
Codex 앱에서 폴더와 승인 설정
권한 설정은 작은 작업 범위에서 시작합니다. 먼저 폴더를 지정하고, 필요한 경우 앱 안의 승인 옵션을 확인합니다.
1. 작업 폴더 지정 — Codex가 작업할 범위를 연습용 폴더로 제한합니다. 처음부터 홈 폴더 전체를 열지 않습니다.
2. Local 선택 — Codex가 내 Mac에서 해당 폴더를 기준으로 작업하도록 Local 모드를 확인합니다.
3. 승인 옵션 확인 — Codex가 파일 수정이나 명령 실행을 요청하면 앱의 승인 화면에서 내용을 보고 허용합니다.
4. 반복 승인 줄이기 — 반복되는 안전한 작업은 앱의 승인 옵션을 조정해 처리할 수 있습니다.
5. 주의할 작업 — 네트워크 접근, 폴더 밖 파일 수정, 삭제, 토큰 노출이 걸린 작업은 자동 승인하지 않고 직접 확인합니다.
Codex에게 처음 요청해 볼 일
설치명령을 하기 전에 공식 자료를 바탕으로 도구가 어떤 역할을 하는지, 설치는 어떤 순서로 진행되는지 먼저 살펴보게 합니다.
Hermes Agent가 무엇인지 공식 자료 기준으로 조사해 주세요. 그다음 내 Mac mini에 설치하기 전에 확인해야 할 조건을 정리해 주세요. 설치 과정은 한 단계씩 안내하고, 각 단계마다 무엇을 확인해야 하는지 설명해 주세요. 명령어가 필요하면 먼저 그 명령이 무엇을 하는지 설명한 뒤 제시해 주세요.
실습 1: 안전한 작업 공간 만들기
에이전트에게 권한을 주기 전에, 연습에만 사용할 안전한 작업 공간을 먼저 만듭니다.
Hermes 개요
Hermes는 단순 챗봇이 아니라, 사용자의 작업 방식에 맞춰 성장하도록 설계된 로컬/메신저 기반 에이전트 프레임워크입니다.
내 컴퓨터에서 도는 에이전트
터미널 또는 Desktop 앱으로 실행하고, 필요한 경우 Gateway를 켜 메신저에서 호출합니다.
도구를 쓰는 작업자
파일, 터미널, 브라우저, 웹 검색, 메신저, 음성·이미지 도구를 연결해 작업을 수행합니다.
Skills와 Memory
반복되는 업무 절차는 Skills로 남기고, 사용자 선호와 업무 맥락은 Memory로 반영합니다.
Gateway와 Cron
Discord·Telegram 같은 채널에서 부르거나, 정해진 시간에 자동으로 검색·요약·보고하게 만들 수 있습니다.
Hermes 특징 1: Skills와 Memory
Hermes의 강점은 반복 업무를 매번 프롬프트로 다시 설명하지 않고, Skills와 Memory로 축적하는 데 있습니다.
Skills
반복되는 업무 절차를 Markdown 기반 플레이북처럼 저장합니다.
Agent-created skills
복잡한 작업을 해결한 뒤, 비슷한 작업에 재사용할 스킬을 만들거나 고칠 수 있습니다.
Memory
사용자, 환경, 선호, 반복 기준 같은 짧은 정보를 장기적으로 반영합니다.
Profiles
연구자, 개발자, 기획자처럼 역할별로 분리된 에이전트 프로필을 둘 수 있습니다.
Hermes 특징 2: Gateway와 Cron
Hermes는 대화형 CLI에서 끝나지 않고, Gateway와 Cron을 통해 메신저와 정기 작업으로 확장됩니다.
메신저 입구
Discord, Telegram 등에서 메시지를 보내면 Hermes가 같은 에이전트 런타임으로 처리합니다.
예약 실행
정해진 시간마다 새 세션으로 작업을 실행하고 결과를 채팅, 파일, 플랫폼으로 전달할 수 있습니다.
도구 사용
웹 검색, 파일 작업, 브라우저, 음성, 이미지 등 필요한 도구를 설정할 수 있습니다.
실행 위치
로컬, Docker, SSH, 서버리스 환경 등에서 실행할 수 있습니다.
Hermes 설치 전 준비
Hermes는 Desktop installer가 권장 경로지만, 설치 구조를 이해하려면 CLI 설치 명령의 의미도 알아야 합니다.
Codex 앱을 먼저 열고 연습용 폴더를 프로젝트로 지정합니다.
Codex에게 Hermes 공식 문서 기준으로 설치 방법을 조사하게 합니다.
Mac 터미널을 열 준비를 합니다. Hermes 설치 자체는 터미널 명령을 사용할 수 있습니다.
모델 provider를 미리 정합니다. 예: Nous Portal, OpenAI, OpenRouter, Ollama 등
이전 설치 흔적이 있는지 ~/.hermes 폴더 존재 여부를 확인합니다.
Discord 연결은 Hermes 자체가 정상 작동한 뒤에 시작합니다.
Hermes 설치 방법: 두 가지 경로
공식 문서 기준으로 macOS/Windows에서는 Hermes Desktop installer가 쉬운 경로이고, CLI만 설치할 때는 터미널 설치 스크립트를 사용합니다.
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
Hermes 설치 명령어 해설
아래 명령어는 “공식 설치 스크립트를 다운로드해서 bash로 실행한다”는 뜻입니다. 명령을 입력하기 전에 각 부분의 의미를 먼저 이해합니다.
| 부분 | 의미 | 왜 필요한가 |
|---|---|---|
| curl | 웹 주소에서 파일을 내려받는 명령 | Hermes 설치 스크립트를 가져옵니다. |
| -f | 실패 시 오류 처리 | 잘못된 주소나 서버 오류를 놓치지 않습니다. |
| -sS | 진행 표시를 줄이고 오류는 보여줌 | 화면은 깔끔하게, 오류는 확인 가능하게 합니다. |
| -L | 리다이렉트를 따라감 | 공식 주소가 다른 위치로 안내해도 따라갑니다. |
| | bash | 다운로드한 스크립트를 bash로 실행 | 설치 과정을 자동으로 실행합니다. |
Hermes 초기 설정: 무엇을 입력하는가
설치가 끝나면 Hermes가 어떤 모델을 쓸지, 어떤 도구를 켤지, 메신저를 어떻게 연결할지 정해야 합니다.
1. hermes setup — 전체 설정 마법사입니다. 처음 설치 후 provider, 모델, 도구, 권한을 한 번에 잡을 때 사용합니다.
2. hermes model — OpenAI, Nous Portal, OpenRouter, Ollama 같은 모델 provider와 모델명을 선택합니다.
3. hermes tools — 파일 작업, 터미널, 웹 검색, 브라우저 등 어떤 도구를 켤지 선택합니다.
4. hermes doctor — 설치 상태와 설정 문제를 진단합니다. 오류가 날 때 Codex에게 결과를 붙여 넣습니다.
5. hermes gateway setup — Discord나 Telegram 같은 메신저 연결 설정을 시작합니다.
Hermes 명령어별 역할
Hermes 설치 후 자주 쓰는 명령어는 각각 역할이 다릅니다. 오류가 날 때는 어느 단계 명령에서 막혔는지부터 구분합니다.
| 명령어 | 입력 위치 | 역할 |
|---|---|---|
| hermes | Mac 터미널 | Hermes 대화 화면을 실행합니다. 설치가 제대로 되었는지 첫 확인에 씁니다. |
| hermes setup | Mac 터미널 | 처음 설정 마법사입니다. provider, 모델, 도구 설정을 전체적으로 잡습니다. |
| hermes model | Mac 터미널 | 사용할 LLM provider와 모델을 다시 선택합니다. |
| hermes tools | Mac 터미널 | 파일 작업, 웹 검색, 브라우저 등 도구 사용 여부를 설정합니다. |
| hermes doctor | Mac 터미널 | 설치·설정·provider 문제를 진단합니다. 결과를 Codex에 붙여 넣어 해석시킵니다. |
| hermes gateway setup | Mac 터미널 | Discord나 Telegram 같은 메신저 연결을 설정합니다. |
Hermes 기본 작동 확인
Discord에 연결하기 전에 Hermes 자체가 정상적으로 대화하는지 확인해야 합니다. 이 단계를 건너뛰면 문제 원인을 찾기 어렵습니다.
1. hermes 실행 — 터미널에서 hermes를 실행해 대화 화면이 열리는지 봅니다.
2. 모델 확인 — 간단한 질문에 답하는지 확인합니다. 답이 없으면 provider 인증부터 봅니다.
3. 파일 확인 요청 — 연습용 폴더 안의 install-notes.md를 읽고 요약하게 해봅니다.
4. 도구 확인 — 파일 읽기나 간단한 명령 실행이 가능한지 확인합니다.
5. 그다음 Gateway — 기본 대화가 되면 그때 Discord 연결로 넘어갑니다.
실습 2: Hermes 로컬 대화 확인
문제 원인을 분리하려면 로컬 대화 → 도구 사용 → 메신저 연결 순서로 확인합니다.
Hermes 주요 폴더 구조
설치가 끝나면 Hermes 관련 설정과 기록은 주로 ~/.hermes 아래에 쌓입니다.
| 위치 | 내용 | 확인 이유 |
|---|---|---|
| ~/.hermes/config.yaml | 비밀값이 아닌 런타임 설정 | provider, gateway, 도구 설정 확인 |
| ~/.hermes/.env | API key, bot token 같은 비밀값 | 화면 공유 시 반드시 숨김 |
| ~/.hermes/skills/ | Skills 저장 위치 | 반복 업무 플레이북 관리 |
| ~/.hermes/cron/ | 예약 작업과 출력 | 정기 리포트·검색 작업 확인 |
| ~/.hermes/logs/ | 로그 파일 | Gateway나 모델 오류 추적 |
Hermes Skills 실습 흐름
Skills는 설치 후 바로 모든 것을 만들기보다, 반복되는 업무 하나를 골라 작게 시작합니다.
# 설치된 스킬 확인 hermes skills list # 스킬 탐색 hermes skills browse # 키워드로 검색 hermes skills search report # 스킬 설치 hermes skills install <skill-name>
Hermes Cron 실습 흐름
Cron은 에이전트를 ‘물어볼 때만 답하는 도구’에서 ‘정해진 시간에 움직이는 작업자’로 바꿉니다.
# 자연어로 예약 작업 요청 예시 매일 오전 9시에 AI 에이전트 관련 최신 자료를 검색하고, 중요한 변화 5가지를 요약해서 Telegram으로 보내줘. # 직접 명령 스타일 예시 /cron add "every weekday 9am" "Check AI agent news and write a Korean digest." /cron list
Hermes + Discord 연결 개요
Discord 연결은 “Discord Bot 계정”과 “Hermes Gateway”를 이어주는 과정입니다. 단순 웹훅이 아니라 Hermes의 도구·메모리·스킬 실행 파이프라인을 거칩니다.
개인 테스트
DM에서는 보통 봇에게 직접 메시지를 보내고 응답 여부를 빠르게 확인합니다.
업무 채널
서버 채널에서는 기본적으로 @멘션해야 Hermes가 응답합니다.
대화 맥락 분리
DM, 스레드, 사용자별 세션이 분리되어 혼선과 토큰 낭비를 줄입니다.
메시지 통로
권한 확인 → 멘션 확인 → 세션 조회 → Hermes 실행 → Discord 응답 전달 순서로 처리합니다.
Discord 채널 설계
Hermes를 붙이기 전에 채널 구조를 먼저 설계해야 합니다. 채널이 곧 업무 흐름의 뼈대입니다.
프로젝트 전체
일정, 진행 상황, 주요 공지
문제와 이슈
문제 제기, 원인 분석, 해결 논의
검토와 승인
문서·코드·디자인 검토
요약과 보고
일일/주간 리포트, 결정 사항 정리
Discord Bot 준비: Developer Portal
Discord 쪽에서는 먼저 Hermes가 사용할 Bot 계정을 만듭니다. 여기서 만든 토큰이 Hermes Gateway에 들어갑니다.
1. Application 생성 — Discord Developer Portal → Applications → New Application에서 실습용 앱을 만듭니다.
2. Bot 메뉴 확인 — 왼쪽 Bot 메뉴에서 봇 계정을 만들고 이름과 아이콘을 정합니다.
3. Public Bot 확인 — 추천 흐름에서는 Public Bot을 ON으로 두어 Discord 제공 초대 링크를 사용할 수 있게 합니다.
4. Token 발급 — Reset Token으로 새 토큰을 발급하고 즉시 복사해 안전한 곳에 저장합니다.
5. 토큰 주의 — 토큰은 한 번만 보이며, 노출되면 누구나 내 봇을 조종할 수 있으므로 즉시 재발급해야 합니다.
Discord Intents와 초대 권한
봇이 서버에 들어와도 Message Content Intent가 꺼져 있으면 메시지 내용을 읽지 못합니다. Hermes가 응답하지 않는 가장 흔한 원인입니다.
1. Privileged Gateway Intents — Bot 메뉴에서 Server Members Intent와 Message Content Intent를 켭니다.
2. Message Content Intent — 사용자가 입력한 메시지 텍스트를 봇이 읽을 수 있게 합니다.
3. OAuth2 초대 — Installation 또는 OAuth2에서 bot, applications.commands scope를 포함합니다.
4. 필수 권한 — View Channels, Send Messages, Read Message History, Attach Files, Embed Links를 확인합니다.
5. 서버 초대 — 실습용 서버에 초대하고, 테스트 채널에서 읽기·쓰기 권한을 확인합니다.
Hermes Gateway: Discord 연결 상세
Discord Bot Token과 내 Discord User ID를 Hermes에 알려주면 Gateway가 Discord 메시지를 Hermes 실행 파이프라인으로 전달합니다.
1. User ID 복사 — Discord 설정 → Advanced → Developer Mode를 켠 뒤 내 사용자 이름을 우클릭해 Copy User ID를 선택합니다.
2. 대화형 설정 실행 — 터미널에서 hermes gateway setup을 실행하고 Discord를 선택합니다.
3. Bot Token 입력 — Discord Developer Portal에서 발급한 Bot Token을 붙여 넣습니다.
4. Allowed Users 입력 — 내 Discord User ID를 넣어 허용된 사용자만 에이전트와 대화하게 합니다.
5. Gateway 실행 — hermes gateway를 실행하면 봇이 온라인으로 보이고, DM 또는 채널에서 테스트할 수 있습니다.
Discord 연결 후 동작 확인
Hermes는 Discord에서 DM과 서버 채널의 응답 방식이 다릅니다. 이 차이를 알아야 “왜 답이 없지?”를 줄일 수 있습니다.
DM. 봇에게 직접 메시지 — DM에서는 보통 @멘션 없이도 모든 메시지에 응답합니다.
채널. @멘션 필요 — 서버 채널에서는 기본적으로 @Hermes처럼 봇을 멘션해야 응답합니다.
스레드. 대화 분리 — 자동 스레드가 켜져 있으면 멘션 대화가 스레드로 분리되어 채널이 덜 지저분해집니다.
free-response. 멘션 없는 채널 — 특정 채널을 free-response로 지정하면 멘션 없이도 답하게 만들 수 있습니다.
업무 테스트. 실제 업무 요청 — 인사말보다 이슈 요약, 리뷰 정리, 주간 보고서 초안 같은 요청으로 테스트합니다.
실습 3: Hermes와 Discord 연결
연결 과정은 Bot 생성, 권한 설정, Gateway 실행, 채널 테스트 순서로 확인합니다.
Hermes 문제 해결
답장이 없을 때는 감으로 고치지 말고 층을 나눠 확인합니다.
| 층 | 확인 항목 | 대표 증상 |
|---|---|---|
| Discord | 봇 초대·채널 권한·Message Content Intent | 채널에 있는데 메시지를 못 읽음 |
| Gateway | hermes gateway 실행 여부 | Discord 입력이 Hermes로 전달되지 않음 |
| Hermes | hermes 자체 대화 가능 여부 | Gateway 이전 단계부터 응답 불가 |
| Model | provider 인증, 모델 이름, 크레딧 | provider authentication error |
| Skills/Cron | 스킬 설치 여부, cron job 상태 | 특정 명령이나 예약 작업만 실패 |
OpenClaw 개요
OpenClaw는 여러 메신저와 AI 에이전트를 연결하는 self-hosted Gateway입니다.
내 기기/서버에서 실행
데이터와 권한을 직접 관리하는 방식입니다.
여러 채널 연결
Telegram, Discord, WhatsApp, Slack 등 다양한 채널을 하나의 Gateway로 연결합니다.
브라우저 대시보드
채팅, 설정, 세션, 노드 상태를 확인할 수 있습니다.
모바일 호출
메신저에서 개인 비서처럼 빠르게 부를 수 있습니다.
OpenClaw와 Hermes의 차이
둘 다 에이전트 흐름에 연결되지만, 강조점이 다릅니다.
| 구분 | Hermes | OpenClaw |
|---|---|---|
| 중심 구조 | 에이전트 런타임·학습 루프 중심 | Gateway·채널 라우팅 중심 |
| 강점 | Skills, Memory, Cron, 개인화 | 여러 메신저 채널, 세션 라우팅, Control UI |
| 추천 사용 | 팀 업무 채널, 정기 리포트, 반복 업무 축적 | 모바일 개인 비서, 메신저 기반 접근, 여러 채널 연결 |
| 활용 예 | Discord 협업 에이전트 | Telegram 개인 비서 |
OpenClaw 설치 전 준비
OpenClaw는 Node 기반 설치 흐름이므로 Node 버전과 npm 상태를 먼저 확인합니다.
Node 24 권장 또는 Node 22 LTS 22.19+ 호환 여부를 확인합니다.
npm이 정상 작동하는지 확인합니다.
사용할 모델 provider의 API 키를 준비합니다.
OpenClaw 설정 폴더 ~/.openclaw 존재 여부를 확인합니다.
Telegram 봇 연결을 할 경우 BotFather로 토큰을 만들 준비를 합니다.
OpenClaw 설치와 Onboarding
공식 Quick Start 기준 기본 흐름은 npm 전역 설치 → onboarding → dashboard 확인입니다.
# OpenClaw 설치 npm install -g openclaw@latest # 온보딩과 서비스 설치 openclaw onboard --install-daemon # 브라우저 Control UI 열기 openclaw dashboard
OpenClaw Gateway 개념
OpenClaw에서 Gateway는 메신저와 에이전트 사이의 단일 연결 지점입니다.
OpenClaw 설정 파일
OpenClaw의 주요 설정은 ~/.openclaw/openclaw.json에 저장됩니다.
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "123:abc",
"dmPolicy": "pairing",
"groups": {
"*": { "requireMention": true }
}
}
}
}
Telegram BotFather 설정
Telegram 연결은 BotFather에서 봇 토큰을 만든 뒤 OpenClaw 설정에 넣는 흐름입니다.
1. BotFather 확인 — Telegram에서 @BotFather를 정확히 확인합니다.
2. /newbot 실행 — 봇 이름과 username을 정합니다.
3. Token 저장 — 발급된 bot token을 안전하게 보관합니다.
4. OpenClaw config에 등록 — botToken 또는 TELEGRAM_BOT_TOKEN으로 등록합니다.
5. Gateway 시작 — openclaw gateway를 실행해 첫 DM을 감지합니다.
Telegram Pairing과 접근 제어
Telegram은 기본 DM 정책이 pairing입니다. 개인 비서 용도라면 아무나 접근하게 두지 않는 것이 중요합니다.
| 정책 | 의미 | 권장 설정 |
|---|---|---|
| pairing | 처음 접근한 사용자를 승인 코드로 연결 | 초기 실습에 적합 |
| allowlist | 허용된 Telegram user ID만 사용 | 개인 비서 용도에 적합 |
| open | allowFrom에 *를 넣으면 누구나 접근 가능 | 공개 봇이 아니면 피함 |
| disabled | DM 사용 안 함 | 그룹 전용 구성에서 검토 |
Telegram Gateway 실행과 승인
토큰을 넣은 뒤 Gateway를 실행하고 pairing 코드를 승인합니다.
# Gateway 실행 openclaw gateway # pairing 코드 확인 openclaw pairing list telegram # 특정 코드 승인 openclaw pairing approve telegram <CODE>
실습 4: OpenClaw와 Telegram 연결
OpenClaw는 Gateway 중심 도구입니다. 그룹 연결보다 개인 DM, pairing, 접근 제어를 먼저 확인합니다.
Telegram 그룹 연결 주의점
개인 DM과 그룹은 다르게 동작합니다. 그룹에서는 privacy mode와 mention 정책을 확인해야 합니다.
Telegram 봇은 기본적으로 Privacy Mode가 켜져 있어 모든 그룹 메시지를 보지 못할 수 있습니다.
그룹 메시지를 모두 보려면 BotFather /setprivacy 설정 또는 관리자 권한을 검토합니다.
실습 초반에는 groups 설정에서 requireMention: true를 유지하는 것이 안전합니다.
group chat ID는 channels.telegram.groups 아래에 넣어야 합니다.
권한을 열기 전에 개인 DM에서 먼저 정상 응답을 확인합니다.
OpenClaw 개인 비서 시나리오
OpenClaw는 처음부터 큰 자동화보다 자주 쓰는 개인 업무부터 연결하는 것이 좋습니다.
오늘 일정과 마감
아침에 오늘 일정·마감·이동 시간을 요약합니다.
조건 기반 리마인드
마감 전날, 회의 전, 특정 키워드 발견 시 알려줍니다.
작업 폴더 검색
프로젝트 폴더, 메모, 링크에서 관련 자료를 찾아줍니다.
초안·요약·체크리스트
회의록 요약, 이메일 초안, 할 일 목록 생성을 맡깁니다.
OpenClaw 첫 테스트 요청
단순 ‘안녕’보다 개인 비서 역할이 드러나는 요청으로 테스트합니다.
오늘 내 일정과 해야 할 일을 요약해줘. 아래 형식으로 정리해줘. 1. 오늘 꼭 해야 할 일 2. 시간대별 일정 3. 놓치면 안 되는 마감 4. 지금 바로 처리하면 좋은 작업 5. 저녁에 다시 확인할 항목
OpenClaw 문제 해결
Telegram에서 답이 없을 때는 Gateway, Token, Pairing, 정책을 순서대로 확인합니다.
| 층 | 확인 항목 | 대표 증상 |
|---|---|---|
| BotFather | 봇 token 정확도 | 401 unauthorized, getMe 실패 |
| Config | botToken / env / tokenFile 우선순위 | 토큰을 넣었는데 다른 값이 적용됨 |
| Gateway | openclaw gateway 실행 여부 | DM을 보내도 pairing이 안 뜸 |
| Pairing | 승인 코드 만료 여부 | 코드가 보였지만 승인 실패 |
| Policy | dmPolicy, allowFrom, requireMention | 특정 사용자나 그룹에서만 무응답 |
보안: 토큰과 권한
에이전트는 내 컴퓨터와 메신저 사이에 놓이는 도구이므로 권한을 작게 시작해야 합니다.
비밀번호처럼 관리
Discord Bot Token, Telegram Bot Token, API Key는 화면 공유와 문서에서 숨깁니다.
작은 작업 폴더
초기에는 연습용 폴더 안에서만 작업하도록 제한합니다.
자동 실행 제한
파일 삭제, 외부 전송, 프로그램 실행은 승인 후 처리합니다.
테스트 채널 우선
실제 업무 채널 전에 DM 또는 테스트 채널에서 확인합니다.
실습 시간표
3시간 기준 실습 흐름입니다. 개념 이해, 로컬 설치, 메신저 연결, 보안 점검을 순서대로 다룹니다.
| 시간 | 내용 | 완료 기준 |
|---|---|---|
| 10분 | AI 에이전트 개념과 도구 역할 | 챗봇/에이전트 차이 설명 |
| 15분 | Codex 설치와 작업 폴더 준비 | Codex가 폴더 기준으로 응답 |
| 25분 | Hermes 설치와 기본 대화 확인 | hermes 기본 응답 확인 |
| 20분 | Hermes Discord 또는 OpenClaw Telegram 연결 | 메신저에서 업무형 요청 테스트 |
| 15분 | 오류 해결과 보안 정리 | 문제 해결 지도와 체크리스트 작성 |
최종 체크리스트
마지막으로 아래 항목을 확인합니다.
Codex가 작업 폴더를 기준으로 파일과 오류를 설명할 수 있다.
Hermes의 핵심 특징을 Skills, Memory, Cron, Gateway로 설명할 수 있다.
Hermes 설치와 기본 대화 확인 순서를 설명할 수 있다.
Discord Bot 생성과 Hermes Gateway 연결 흐름을 설명할 수 있다.
OpenClaw를 Gateway 중심 구조로 설명할 수 있다.
Telegram BotFather, Token, Pairing, dmPolicy의 역할을 설명할 수 있다.
토큰 노출, 권한 확대, 자동 실행의 위험을 설명할 수 있다.
공식 자료
도구는 빠르게 바뀌므로 실제 사용 전 공식 문서에서 명령어와 화면을 다시 확인합니다.