읽는 데 10분조회 14
OpenClaw 구축 및 운영 가이드
버전 1.0.0
작성 기준: 2026-08-28
문서 상태: 현재 운영 환경 상세 초안 (2026-08-28 운영 정비 반영)
대상 환경: 현재 운영 중인 개인 OpenClaw 서버
1. 문서 목적과 구축 개요
이 문서는 현재 서버에 구축된 OpenClaw의 구성, 연동 방식, 운영 절차와 복구 기준을 정리한다. 단순 설치 설명보다 실제 운영 환경을 재현하고 장애 발생 시 복구할 수 있도록 하는 데 목적이 있다.
현재 환경은 OpenClaw Gateway를 중심으로 Telegram, Google Workspace, 모델 Provider, Tools·Skills·Plugins, Browser, Memory, Cron·Heartbeat 및 OpenClaw 전용 백업 체계가 연결된 개인 AI 에이전트 시스템이다. 인증 토큰, 비밀번호, 개인키와 사용자 식별자는 문서에 기록하지 않는다.
2. 전체 아키텍처와 처리 흐름
요청 처리 흐름
사용자
→ Telegram 직접 대화 또는 OpenClaw Control UI
→ 127.0.0.1:18789의 OpenClaw Gateway
→ Main Agent
→ 세션별 모델 선택과 Agent 실행
→ Tools·Skills·MCP Connector
→ Google Workspace, 브라우저, 서버 명령, Memory, Cron 등 허용된 기능
→ message 도구를 통한 Telegram 최종 응답
구성·기억 흐름
~/.openclaw/openclaw.json
→ Gateway·Agent·모델·채널·도구·플러그인 설정
~/.openclaw/workspace
→ AGENTS.md·SOUL.md·USER.md·TOOLS.md
→ MEMORY.md·memory/YYYY-MM-DD.md
→ 세션 지침, 승인 규칙, 사용자 문맥과 운영 기록
Gateway는 systemd 사용자 서비스로 실행되며 loopback 주소에만 바인딩된다. Telegram과 Connector가 Gateway를 통해 Main Agent에 요청을 전달하고, Main Agent는 작업 성격에 따라 모델과 도구를 호출한다.
3. 서버 환경 및 사전 준비
확인 시점의 운영 환경은 Ubuntu 26.04 LTS, ARM64 Oracle 커널, Node.js 24.19.0, OpenClaw 2026.7.1-2다. OpenClaw는 일반 사용자 계정으로 운영하며 Gateway는 systemd 사용자 서비스로 관리한다.
환경 확인 명령:
cat /etc/os-release
uname -a
node --version
npm --version
openclaw --version
openclaw status
systemctl --user status openclaw-gateway --no-pager
이 문서는 OpenClaw 자체 구성과 직접 연동된 기능만 다룬다.
운영 계정의 홈 디렉터리와 OpenClaw 경로:
/home/leechis/.openclaw
/home/leechis/.openclaw/workspace
4. OpenClaw 설치와 기본 실행
OpenClaw 설치 방식은 사용 중인 배포판과 해당 버전의 공식 설치 지침에 맞춘다. 현재 서버에서는 Node.js 런타임 위에 OpenClaw가 설치되어 있고 Gateway가 사용자 서비스로 자동 시작된다.
openclaw --version
openclaw status
openclaw gateway status --deep
openclaw doctor --non-interactive
openclaw security audit --deep
설정 변경 절차는 ‘현재 설정 백업 → 변경안 검토와 승인 → 설정 수정 → Gateway 재시작 → status·doctor·security audit 검증 → Telegram 실사용 시험’ 순서로 수행한다. 로그는 systemd 사용자 저널과 OpenClaw 상태 출력에서 확인한다.
systemctl --user restart openclaw-gateway
systemctl --user status openclaw-gateway --no-pager
journalctl --user -u openclaw-gateway -n 200 --no-pager
5. 주요 디렉터리와 설정 파일
~/.openclaw/openclaw.json
OpenClaw의 핵심 설정 파일. Gateway, 모델, 채널, 도구, 에이전트 기본값을 관리한다.
~/.openclaw/workspace/AGENTS.md
작업 공간의 운영 규칙과 승인 절차를 정의한다.
~/.openclaw/workspace/SOUL.md
에이전트의 정체성, 말투, 행동 원칙을 정의한다.
~/.openclaw/workspace/USER.md
사용자 환경과 선호 정보를 관리한다.
~/.openclaw/workspace/MEMORY.md
장기 기억을 정리한다. 개인 메인 세션에서만 사용한다.
~/.openclaw/workspace/memory/
날짜별 작업 기록과 프로젝트별 기억을 저장한다.
~/.openclaw/workspace/TOOLS.md
서버와 계정에 특화된 도구 사용 메모를 기록한다.
6. Gateway·인증·보안 설정
Gateway는 OpenClaw의 요청 진입점이다. 현재 systemd 사용자 서비스로 실행되며 127.0.0.1:18789에만 바인딩되고 토큰 인증을 사용한다. 따라서 일반 네트워크 인터페이스에서 Gateway 포트를 직접 받지 않는다.
현재 핵심 운영값:
- 서비스 방식: systemd user unit
- 수신 주소: 127.0.0.1:18789
- 인증: Gateway token
- Agent 동시 실행 한도: 4개
- Heartbeat: 1시간
- Telegram: 직접 대화 allowlist, 그룹 비활성, partial streaming
- openclaw.json 및 민감 파일: 소유자 전용 권한 600/700
- 명령 소유자: 승인된 Telegram 계정으로 제한
- elevated: 승인된 Telegram 계정으로 제한
- host exec: security=allowlist, ask=on-miss, askFallback=deny
- 심층 보안 감사 결과: 0 critical · 0 warn
보안 원칙:
- Gateway 토큰과 Provider 인증정보는 문서·메모리·Git에 기록하지 않는다.
- openclaw.json, 인증 프로필, .env와 백업 파일은 소유자만 읽을 수 있도록 제한한다.
- elevated와 exec full 권한은 신뢰된 직접 대화 및 명시된 승인 절차에서만 사용한다.
- Telegram 명령 소유자를 명시해 허가되지 않은 사용자가 관리 명령을 실행하지 못하게 한다.
- 구성 변경 전 OpenClaw 전용 백업을 만들고 변경 후 doctor와 security audit를 재실행한다.
점검 명령:
openclaw status
openclaw gateway status --deep
openclaw doctor --non-interactive
openclaw security audit --deep
ss -lntp | grep 18789
systemctl --user status openclaw-gateway --no-pager
7. Agent·SOUL·USER·Memory 운영
Main Agent는 Telegram 직접 대화와 Control UI의 중심 에이전트다. 동작 기준은 AGENTS.md, SOUL.md, USER.md에 분리해 관리한다.
기억은 다음처럼 구분한다.
- MEMORY.md: 장기간 유지할 핵심 정보
- memory/YYYY-MM-DD.md: 일별 작업 기록
- memory/projects/: 프로젝트 단위 기록
- 세션 기록: 대화 문맥과 과거 작업 검색
민감한 개인 기억은 그룹 대화나 가족 대화에 노출하지 않는다. 이전 작업, 결정, 일정, 선호를 답할 때에는 memory_search로 먼저 확인한다.
8. 모델 Provider와 기본 모델
현재 기본 모델은 openai/gpt-5.6-terra이며, 세션별로 다른 모델을 고정할 수 있다. 확인 당시 Telegram 세션은 openai/gpt-5.6-sol로 고정되어 있었다. Sol·Terra·Luna 같은 사용자용 별칭은 긴 Provider 모델 ID와 분리해 관리한다.
모델 선택 우선순위는 세션 고정 모델 → Agent·작업 지정 모델 → 전역 기본 모델 → fallback 순서다. 인증 프로필은 Provider별로 분리한다. 일부 정기 Cron 작업은 의도적으로 Sol(openai/gpt-5.6-sol)로 고정해 운영한다.
예시:
openai/gpt-5.4-mini alias: GPT54m
openai/gpt-5.4 alias: GPT54
openai/gpt-5.5 alias: GPT55
API 토큰은 파일을 임의로 직접 편집하기보다 OpenClaw 인증 명령을 사용해 등록한다.
openclaw models auth paste-token --provider <provider> --profile-id <profile-id>
등록 후 기본 모델, 별칭, 런타임과 인증 프로필을 확인한다. 실제 토큰은 출력하거나 문서에 붙여 넣지 않는다. 확인 당시 Anthropic·Gemini 인증 프로필 일부가 만료 상태였으므로, 사용하는 프로필은 재인증하고 사용하지 않는 프로필은 정리한 뒤 실제 요청으로 검증한다.
9. Telegram 채널 연결과 메시지 처리
Telegram Bot은 사용자 요청을 Gateway의 Main Agent로 전달한다. 현재 직접 대화는 allowlist 방식이며 그룹 정책은 disabled, 응답 스트리밍은 partial로 구성되어 있다.
Telegram update → 채널 정책과 발신자 확인 → Main Agent 세션 선택 → 세션 모델과 작업 공간 지침 적용 → 도구 실행 → message(action=send)로 최종 결과 전달 순서로 처리한다.
운영 원칙:
- 직접 대화와 그룹 대화를 구분한다.
- 명령 소유자 목록에는 승인된 Telegram 사용자 ID만 등록한다.
- 그룹에서는 사용자 개인정보와 장기 기억을 공유하지 않는다.
- 파일·설정 변경과 수동 명령 실행은 변경안과 명령을 먼저 제시하고 승인 후 수행한다.
- 자동 Cron은 미리 승인된 작업을 직접 수행하며 매 실행마다 승인 요청을 보내지 않는다.
- 중간 진행 알림은 짧게 보내고 최종 결과를 별도로 전달한다.
- Bot Token과 채팅 식별자는 공개 문서에서 마스킹한다.
10. Google Workspace 연동
현재 Google Workspace MCP Connector를 사용하며 개인 계정과 회사 계정을 논리적으로 분리한다. 별도 언급이 없으면 개인 계정을 사용하고, ‘회사’가 명시된 작업만 회사 계정을 사용한다. Connector 호출 전에는 대상 계정, 파일 ID 또는 폴더 위치를 확인한다.
주요 기능:
- Google Drive 파일과 폴더 검색
- Google Docs 생성·읽기·편집·서식 적용
- Gmail 조회와 발송
- Calendar 일정 조회와 생성
- Sheets 데이터 읽기와 쓰기
Google Docs 개발문서 기본 저장 위치:
내 드라이브/문서/개발문서
문서 작업은 대상 파일을 먼저 확인하고, 변경안을 제시한 뒤 승인 후 반영한다. 메일 발송은 외부 행동이므로 수신자·제목·본문을 제시하고 승인 후 실행한다. 개인 계정과 회사 계정의 인증정보 및 자료를 서로 섞지 않는다.
11. Tools·Skills·Browser Relay
Tools는 외부 시스템을 직접 다루는 실행 단위이고, Skills는 특정 작업의 절차와 안전 규칙을 묶은 지침이며, Plugins는 기능을 Gateway에 등록하는 확장 단위다. 현재 활성 구성에는 Google Workspace MCP, Browser, Codex, OpenAI, Microsoft TTS와 Memory 관련 플러그인이 포함된다.
대표 활용:
- browser: 웹 페이지 탐색과 자동화
- Google Workspace Connector: Drive, Docs, Gmail, Calendar
- exec: 서버 상태 확인과 명령 실행
- cron: 정확한 시간의 자동 작업
- memory_search: 과거 결정과 작업 검색
- message: Telegram 결과 전달
Browser Relay는 사용자가 로그인한 Chrome 세션을 활용해야 하는 작업에 사용한다. 브라우저에서 no-sandbox를 사용하면 격리 수준이 낮아지므로 전용 사용자, 최소 권한과 제한된 네트워크를 함께 적용한다. Relay Port와 Token은 외부에 노출하지 않으며, 연결 실패 시 확장 프로그램 상태, Gateway 인증, 포트와 네트워크 경로를 순서대로 확인한다.
12. Cron·Heartbeat·자동화
현재 Heartbeat 간격은 1시간이며 Agent 동시 실행 한도는 4개다. Cron은 정확한 시각에 독립적으로 실행할 작업에 사용한다. Heartbeat는 이메일, 일정, 날씨처럼 약간의 시간 오차가 허용되는 여러 점검을 묶을 때 사용한다. OpenClaw Cron, OS crontab과 Heartbeat의 책임은 중복되지 않게 구분한다.
구분 기준:
- Cron: 정시 실행, 일회성 알림, 독립 작업
- Heartbeat: 주기적 묶음 점검, 대화 문맥이 필요한 작업
- 수동 실행: 승인과 즉시 확인이 필요한 작업
자동 Cron은 매번 승인 요청을 보내는 형태가 아니라 승인된 목적의 실제 작업을 직접 수행하도록 구성한다.
13. Hooks·Plugins·Memory Search 운영
OpenClaw 내부 기능은 Hook, Plugin, Skill과 Tool 계층으로 나누어 관리한다. Hook은 특정 이벤트에 반응하고, Plugin은 기능을 Gateway에 등록하며, Skill은 작업 절차를 정의하고, Tool은 실제 조회·실행을 담당한다.
Memory는 장기 기억, 일별 기록과 세션 transcript를 검색 대상으로 사용한다. 현재는 무료 FTS 키워드 검색만 사용하며 의미 기반(semantic) 검색은 명시적으로 비활성화했다(memorySearch.enabled=false, provider=none). 이는 외부 임베딩 API 비용과 개인정보 노출을 피하기 위한 의도된 구성이며, 확인 당시 134/134 파일·332 chunk가 정상 인덱싱되어 있었다. 향후 의미 기반 검색이 필요하면 로컬 임베딩을 별도로 구성한 뒤 검색 품질과 개인정보 노출 범위를 함께 검증한다.
세션 저장소는 2026-08-28 정비에서 12개 엔트리 중 현재 활성 Telegram 세션 1개만 유지하도록 정리했고, transcript가 이미 사라진 cron 세션 11개와 미참조 아티팩트 578개를 정리했다. Telegram legacy thread-binding은 doctor --fix로 새 Plugin State 형식으로 이전했다. 정리 전에는 dry-run으로 대상을 확인하고 활성 세션을 보호하며, OpenClaw가 제공하는 정리·복구 절차를 우선 사용한다.
점검 명령:
openclaw status
openclaw doctor --non-interactive
openclaw security audit --deep
Plugin과 Skill을 추가할 때에는 출처, 권한, 외부 통신, 민감정보 접근 여부와 자동 실행 조건을 검토한다.
14. 백업과 복구 체계
OpenClaw 백업 스크립트:
~/bin/backup-openclaw.sh
실행 주기:
매주 일요일 03:00 KST
백업 정책:
- openclaw-YYYYMMDD-HHMMSS.tar.gz 생성
- SHA-256 체크섬 생성
- 로컬 최근 10개 보관
- Google Drive 백업 폴더에 누적 보관
- 백업 파일 권한 600 유지
- 토큰, 설정, DB 등 민감정보가 포함될 수 있으므로 외부 공유 금지
이 문서에서는 OpenClaw 전용 백업과 복구만 다룬다. 서버 전체 또는 다른 서비스의 백업은 별도 운영 문서에서 관리한다.
OpenClaw 복구 절차는 다음 문서를 기준으로 한다.
~/bin/BACKUP-RESTORE.md
복구 시험에서는 압축 해제 가능 여부, 체크섬, 설정 파일, 인증 프로필, 서비스 기동과 Connector 연결을 확인한다.
15. 운영 점검과 장애 해결
기본 점검 순서:
1) OpenClaw 버전과 전체 상태 확인
2) Gateway 사용자 서비스와 로그 확인
3) doctor와 security audit 실행
4) 127.0.0.1:18789 수신 및 Gateway 인증 확인
5) 기본·세션 모델과 Provider 인증 확인
6) Telegram allowlist·전달·최종 message 전송 확인
7) Google Workspace와 Browser Connector 확인
8) Hooks·Plugins·Memory·Cron 상태 확인
9) 최근 OpenClaw 설정 변경과 전용 백업 확인
주요 명령:
openclaw --version
openclaw status
openclaw gateway status --deep
openclaw doctor --non-interactive
openclaw security audit --deep
systemctl --user status openclaw-gateway --no-pager
journalctl --user -u openclaw-gateway -n 200 --no-pager
ss -lntp | grep 18789
df -h
free -h
장애 조치 후에는 원인, 변경 내용, 검증 결과와 재발 방지책을 날짜별 memory 파일에 남긴다.
부록 A. 운영 보안 체크리스트
- 토큰·비밀번호·개인키가 문서와 Git에 없는가
- 인증 파일과 백업 파일 권한이 제한되어 있는가
- Gateway가 127.0.0.1에만 바인딩되어 있는가
- Telegram 명령 소유자와 직접 대화 allowlist가 명시되어 있는가
- elevated·exec full 권한의 사용 범위와 승인 절차가 제한되어 있는가
- Gateway 로그에 반복 오류가 없는가
- OpenClaw doctor와 security audit가 정상인가
- 백업 파일과 SHA-256이 최근 날짜로 생성되었는가
- Google Drive 백업 전송이 성공했는가
- Telegram 그룹에서 개인정보가 분리되는가
- 자동 작업이 승인된 범위만 수행하는가
- 복구 문서가 현재 구성과 일치하는가
부록 B. 다음 개정 항목
- openclaw.json의 민감정보 마스킹 예시와 필드별 설명 추가
- Telegram → Gateway → Agent → Model → Tool 처리 구성도 추가
- 설치부터 초기 설정까지 명령을 현재 OpenClaw 버전에 맞춰 검증
- Telegram·Google Workspace 연결 화면과 절차 보강
- Gateway·Browser·Memory 장애 사례 추가
- 보안 개선 후 doctor·security audit 결과 기록
- OpenClaw 전용 복구 리허설 결과와 소요 시간 기록
댓글
첫 댓글을 남겨보세요.