OpenClaw 구축·운영 (16/26) — 프로덕션 운영 가이드: launchd·systemd·로그

-

공식 daemon 구조, /tmp 로그 경로, openclaw.json 핫 리로드, 멀티 에이전트 라우팅 실전

핵심 요약

  • 대상 독자: OpenClaw를 데스크톱 테스트를 넘어 홈서버나 작은 VPS에서 24/7 운영하려는 사용자.
  • 얻을 것: --install-daemon이 실제로 만드는 것(launchd/systemd user service), 기본 로그 경로(/tmp/openclaw/), ~/.openclaw/openclaw.json 핫 리로드 동작, 멀티 채널 동시 운영 JSON5 예제, 그룹 채팅 mention-gating, 로그 레벨 제어 3단 우선순위.
  • 선행 조건: #9 설치+Discord 30분까지 완료. Linux/macOS 프로세스 매니저 기초 상식.

1. Daemon은 정확히 무엇이 설치되는가

공식 README 기준:

"OpenClaw Onboard installs the Gateway daemon (launchd/systemd user service)"

  • macOS: launchd 사용자 에이전트 (system이 아니라 user)
  • Linux: systemd user service

두 경우 모두 user scope이므로 root 권한 없이 설치·관리된다. 이 특성 덕분에 공유 서버의 사용자 홈 디렉터리에서도 문제 없이 동작.

openclaw onboard --install-daemon

공식 문서는 정확한 plist/service 파일 경로를 README 레벨에서는 명시하지 않는다. 관례적 위치는:

  • macOS: ~/Library/LaunchAgents/com.openclaw.gateway.plist
  • Linux: ~/.config/systemd/user/openclaw.service

확인 방법 (실제 내 시스템에서):

launchctl list | grep openclaw
ls ~/Library/LaunchAgents/ | grep openclaw

systemctl --user list-units | grep openclaw
systemctl --user status openclaw

2. 수동 관리 — 데몬 재시작·비활성·제거

2.1 macOS (launchd)

launchctl unload ~/Library/LaunchAgents/com.openclaw.gateway.plist

launchctl unload ~/Library/LaunchAgents/com.openclaw.gateway.plist
launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist

launchctl unload ~/Library/LaunchAgents/com.openclaw.gateway.plist
rm ~/Library/LaunchAgents/com.openclaw.gateway.plist

2.2 Linux (systemd user)

systemctl --user stop openclaw
systemctl --user restart openclaw
systemctl --user status openclaw

systemctl --user disable openclaw

systemctl --user stop openclaw
systemctl --user disable openclaw
rm ~/.config/systemd/user/openclaw.service
systemctl --user daemon-reload

2.3 세션 내부 명령 (별도)

README는 에이전트 세션 안의 chat 명령을 별도로 제공: /status, /restart, /reset, /compact, /think <level>, /verbose on|off, /trace on|off, /usage off|tokens|full, /activation mention|always.

이들은 세션 수준 명령이지 데몬 관리 명령이 아니다. 데몬 자체를 껐다 켜려면 위 2.1/2.2 방식이 정확.

3. 로그 — 위치·레벨·subcommand

3.1 기본 로그 경로

공식 문서 명시:

"The Gateway writes logs to /tmp/openclaw/openclaw-YYYY-MM-DD.log by default, using the gateway host's local timezone."

/tmp는 재부팅 시 비워진다. 장기 보관이 필요하면 경로를 변경해야 한다.

3.2 경로 변경

~/.openclaw/openclaw.json:

{
  logging: {
    file: "/var/log/openclaw/gateway.log"
  }
}

해당 디렉터리가 쓰기 가능해야 한다. /var/log 같은 시스템 경로는 미리 권한 세팅:

sudo mkdir -p /var/log/openclaw
sudo chown $USER /var/log/openclaw

3.3 로그 레벨 — 3단 우선순위

공식 정책: 환경변수 > CLI 플래그 > config 파일.

export OPENCLAW_LOG_LEVEL=debug
openclaw gateway

openclaw gateway --log-level trace

config 예:

{
  logging: {
    level: "info",         // 파일 로그 레벨
    consoleLevel: "warn"   // 콘솔 출력 레벨
  }
}

로그 레벨: trace > debug > info > warn > error.

3.4 로그 조회 subcommands

openclaw logs --follow

openclaw channels logs --channel discord

openclaw logs --follow --local-time --json
openclaw logs --follow --plain --no-color

원격 gateway에 붙을 때는 --url + --token 조합.

4. 로그 로테이션 — OpenClaw는 기본 제공하지 않는다

공식 문서는 로그 파일 이름에 YYYY-MM-DD 날짜를 포함한다(일일 파일 생성)는 사실만 명시. 명시적 회전 정책(용량 기반, 보관 기간 등)은 제공하지 않는다.

프로덕션에서는 OS 레벨 logrotate로 보완해야 한다.

4.1 Linux — /etc/logrotate.d/openclaw

/var/log/openclaw/*.log {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
    create 0644 myuser myuser
    postrotate
        systemctl --user reload openclaw 2>/dev/null || true
    endscript
}

14일 보관, 압축, postrotate에서 gateway에 SIGHUP 비슷한 신호(여기서는 systemctl reload) — OpenClaw가 파일 핸들을 새로 잡도록.

4.2 macOS — newsyslog.d 또는 cron

macOS는 logrotate 대신 newsyslog가 기본. /etc/newsyslog.d/openclaw.conf:

/var/log/openclaw/gateway.log    myuser:wheel    644    14    *    $D0    J

14개 로테이션, 일일, gzip 압축.

5. 핫 리로드 — config 편집이 즉시 반영

공식 문서 명시:

"The gateway automatically monitors openclaw.json for changes and applies safe updates without restart. Configuration must pass strict schema validation before loading — unknown keys or malformed types cause startup failure."

실무 의미:

  • 안전한 변경은 재시작 없이 반영(예: 채널 추가, 로그 레벨 변경, 바인딩 재구성).
  • 스키마 검증 실패는 startup failure — 기존 gateway는 기동 상태 유지하고 새 config는 거부.
  • 검증 상태 확인:
openclaw doctor

편집 후 적용 패턴:

vim ~/.openclaw/openclaw.json

openclaw doctor

openclaw logs --follow

핫 리로드가 안 되는 변경(예: gateway 포트 자체 변경)은 데몬 재시작 필요.

6. 멀티 채널 공존 — 한 gateway가 여러 메신저

공식 문서 기준 22개 이상 채널을 동시에 연결 가능. 각 채널은 channels.<provider> 아래에 독립 설정.

6.1 JSON5 예 (Discord + Telegram + Slack)

{
  channels: {
    discord: {
      enabled: true,
      token: { ref: { provider: "default", source: "env", id: "DISCORD_BOT_TOKEN" } },
      dmPolicy: "pairing",
      allowFrom: ["discord:123456789"]
    },
    telegram: {
      enabled: true,
      botToken: { ref: { provider: "default", source: "env", id: "TELEGRAM_BOT_TOKEN" } },
      dmPolicy: "allowlist",
      allowFrom: ["tg:123"]
    },
    slack: {
      enabled: true,
      token: { ref: { provider: "default", source: "env", id: "SLACK_BOT_TOKEN" } },
      dmPolicy: "pairing"
    }
  }
}

6.2 DM Policy — 4가지 옵션

공식 명시:

값 동작
"pairing" (기본) 모르는 발신자는 일회용 승인 코드를 받음
"allowlist" allowFrom에 명시된 ID만 허용
"open" 모든 DM 허용 (위험, allowFrom: ["*"] 필수)
"disabled" 모든 DM 무시

공개 서버의 봇이라면 "allowlist"가 가장 안전. "open"은 자동화 테스트 외에는 사용 금지.

7. 멀티 에이전트 라우팅 — 한 gateway에 여러 봇

7.1 에이전트별 워크스페이스 분리

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" }
    ]
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } }
  ]
}

매 inbound 메시지는 bindings 규칙에 따라 에이전트를 선택. 각 에이전트는 자체 workspace·skills·memory를 가진다.

7.2 기본 에이전트

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      sandbox: { mode: "non-main" }   // 공유 채널이면 필수
    }
  }
}

README가 강조한 보안 규칙: 기본 main 세션은 호스트에서 전체 권한 실행. 채널 공유 시 sandbox.mode: "non-main"으로 격리.

8. 그룹 채팅 — 멘션 게이팅

봇이 모든 메시지에 반응하면 그룹에서 노이즈가 된다. mention-gating 설정.

{
  agents: {
    list: [{
      id: "main",
      groupChat: {
        mentionPatterns: ["@openclaw", "openclaw", "헤이 클로"]
      }
    }]
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } }
    },
    discord: {
      groups: { "*": { requireMention: true } }
    }
  }
}
  • mentionPatterns: 네이티브 @-멘션 외 텍스트 패턴(정규식)도 허용.
  • requireMention: true: 그룹에서는 멘션이 있을 때만 반응. DM에는 영향 없음.

9. 설정 파일 구조 — 탑 레벨 6섹션

~/.openclaw/openclaw.json (JSON5 형식) 주요 섹션:

{
  gateway: { port: 18789 /* 서버, auth, health */ },
  agents:  { /* 모델, skills, sandbox */ },
  channels: { /* provider별 설정 */ },
  session: { /* 대화 범위, reset 정책 */ },
  cron:    { /* 예약 작업 */ },
  hooks:   { /* webhook */ }
}

6개 섹션 개념을 숙지하고 있으면 공식 reference를 참조할 때 빠르게 해당 섹션으로 이동할 수 있다.

9.1 JSON5 사용 이점

  • 주석 허용 (//, /* */)
  • 후행 콤마 허용
  • 싱글 쿼트 허용

일반 JSON보다 읽기·유지 편함. 다만 GitHub으로 공유할 때 syntax highlighting이 부족한 편집기라면 확장자를 .json5로 바꾸는 것이 가독성에 도움.

10. 모니터링 — 최소 관찰 세트

개인 프로덕션에서 놓치지 말 것:

10.1 openclaw doctor

openclaw doctor

Node 버전·gateway 상태·채널 연결·토큰 유효성·config 스키마 검증을 한 번에 점검. 주기적으로 cron으로 돌려 이상 시 알림:

*/10 * * * * /usr/local/bin/openclaw doctor > /tmp/openclaw-doctor.log 2>&1 || osascript -e 'display notification "OpenClaw doctor FAIL" with title "OpenClaw"'

10.2 openclaw channels status --probe

각 채널 연결 상태를 실측 probe.

10.3 로그 keyword 감시

openclaw logs --follow | grep -Ei 'error|fatal|panic|disconnected'

11. 자원 소비 — 관찰 가능한 한계

공식 문서가 구체 수치는 밝히지 않는다. 실측 기준이 필요하면:

  • 메모리: gateway + 연결된 채널 수 + 활성 세션에 비례. 관찰적으로 기본 구성에서 100~400MB 사이.
  • 디스크: /tmp/openclaw/*.log가 장기 누적되면 커짐. 경로 변경 + logrotate 필수.
  • 네트워크: 각 메신저 연결 유지 + API 호출. 24/7 가동이라면 월 수 GB 소모는 흔함.
  • Daemon 재시작 주기: 공식 권장 없음. 하지만 메모리 누수 가능성을 고려해 주간 재시작 크론 추천.
0 4 * * 0 systemctl --user restart openclaw

12. 반대 시나리오 — 프로덕션 운영 말고 다른 선택

  • 개인 데스크톱에서만 쓴다 → daemon 없이 openclaw gateway 수동 실행이 더 유연. 껐다 켜는 비용이 낮다.
  • 이미 다른 프로세스 매니저(PM2 등) 사용 중 → launchd/systemd 대신 PM2로 감싸는 것도 가능. 단 --install-daemon 경로와 충돌하지 않도록.
  • Docker로 격리하고 싶다 → 공식 Docker 이미지는 README에 명시되지 않음. 커스텀 Dockerfile이 필요하며 PTY·채널 자격 마운트 고민 필요. 난이도 높다.
  • 완전한 로그 보존/감사가 필요 → OpenClaw 기본은 약함. journald + 외부 SIEM으로 stream 필요.

13. 프로덕션 체크리스트

  • [ ] --install-daemon으로 launchd/systemd user service 설치
  • [ ] 로그 경로를 /tmp/ 밖으로 이전 (~/.openclaw/openclaw.json의 logging.file)
  • [ ] logrotate/newsyslog 설정 추가 (14일 보관, 압축)
  • [ ] OPENCLAW_LOG_LEVEL=info 기본, 디버깅 시 debug/trace로 일시 상승
  • [ ] 공유 채널이면 agents.defaults.sandbox.mode = "non-main" 강제
  • [ ] 그룹 채팅에는 requireMention: true + mentionPatterns 설정
  • [ ] DM Policy를 "allowlist" 기본 (새 발신자는 별도 승인)
  • [ ] openclaw doctor를 cron으로 10분 주기 점검 + 실패 알림
  • [ ] 주간 재시작 크론 (메모리 누수 대비)
  • [ ] 환경 변수(토큰 등)를 systemd Environment= 또는 .env.local로 분리

14. 다음 단계

프로덕션 운영이 안정됐다면:

  1. OpenClaw ↔ Claude Code 브릿지 — 채널 트리거로 coding agent 호출 (예정)
  2. OpenClaw 설치 + Discord 30분 — 기본 개념.
  3. Claude Code 훅 완전 가이드 — 코딩 자동화 훅 패턴 참고.

참고

이 글은 "AI 코딩 CLI 진입 가이드" 시리즈의 10/15 편입니다. last verified: 2026-04-25 (openclaw/openclaw 공식 GitHub README + docs.openclaw.ai 기준).

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »