macmini-agent-fleet

맥미니에 상주하는 디스코드 대화 에이전트들(지식봇A·스터디봇B·밤냥이)을 손보거나 새로 만들 때 읽을 것. "봇이 답을 안 해", "봇 하나 더 만들자", "사용량 한도 터졌다", "봇 재시작해줘" 같은 요청을 처리한다. 이 기기 특유의 함정 두 가지(저전력 모드·CLAUDE.md 자동로딩)를 담고 있다.

SKILL.md

GitHub

이 스킬이 시스템에 하는 일 (설치 전 확인)

  • 상주 작업(launchd)을 등록하고 프로세스를 죽였다 살립니다.
  • 봇 토큰이 필요합니다. 환경변수·.env에서만 읽습니다.
  • 저전력 모드에서 상주 작업이 조용히 죽는 문제를 다룹니다. 전원 설정을 바꾸는 단계가 포함됩니다.

맥미니 에이전트 무리

밤밤의 맥미니(ssh mac-mini)에 대화형 디스코드 봇이 셋 상주한다. 전부 같은 뼈대를 쓴다.

봇 폴더 아는 것 launchd
지식봇A ~/Projects/knowledge-bot-a/ 커뮤니티A 8기수 기록 + 원자료 55개 com.bambam.knowledge-bot-a
스터디봇B ~/Projects/daily-brief-agent/ 대상 커뮤니티 글 2,000건 + 지난 아티클 + 밤밤 스킬·메모리 com.bambam.daily-brief-agent
밤냥이 ~/Projects/getback/discord_bot/ 겟백 커뮤니티 운영(길드·슬래시명령 등) com.getback.bamnyangi

파이썬은 셋 다 ~/Projects/getback/.venv/bin/python 를 공유한다. 서버는 ai공작실(<DISCORD_ID>) 하나. 허용 계정은 밤밤 <DISCORD_ID>, GET100 <DISCORD_ID>.

공통 뼈대

  • bot.py — 디스코드 게이트웨이. DM은 전체 지식, 공개 채널은 멘션받을 때만
  • answer.py — 인격+기억+자료를 조립해 LLM 호출
  • store.py — 단기 대화를 SQLite 에 영구 저장 (재시작·재부팅에도 유지)
  • persona.md — 인격·말투. 매 응답마다 읽으므로 고치면 재시작 없이 반영
  • memory.md — 장기기억. 응답에 MEMORY: 줄을 쓰면 자동 적립

기억이 두 층이라는 게 핵심이다. 단기(대명사 받기) + 장기(세션 끊어도 남는 사실). 초기화는 단기만 끊고 장기는 남긴다.

⚠️ 이 기기의 함정 세 가지

1. 저전력 모드가 KeepAlive 자동 재시작을 막는다

맥미니에 lowpowermode = 1 이 켜져 있으면, 프로세스가 죽어도 launchd 가 되살리지 않는다.

state = not running
pended nondemand spawn = inefficient

"요청 없이 스스로 재기동하는 건 비효율적"이라며 무기한 보류한다. plist 에 KeepAlive 가 제대로 있어도 소용없고 ProcessType 을 바꿔도 안 통한다. 40초를 기다려도 안 풀리는 걸 실측했다.

  • 배포·재시작할 때는 항상 launchctl kickstart -k 를 명시적으로 쓴다. bootstrap 만으로는 프로세스가 안 뜬다. kickstart 는 명시적 요청이라 보류 정책을 우회한다.
  • 근본 해결은 sudo pmset -a lowpowermode 0 인데 비번 없는 sudo 가 안 걸려 있어 SSH 로는 못 한다. 밤밤이 직접 쳐야 한다.
  • 이건 지식봇A만의 문제가 아니라 이 기기의 모든 launchd 상주 작업에 적용된다.

2. CLAUDE.md 가 모든 CLI 호출에 자동으로 딸려간다

claude CLI 는 실행 디렉터리에 CLAUDE.md 가 없으면 상위 폴더로 거슬러 올라가며 찾아서 프롬프트에 넣는다.

밤냥이가 호출당 14만 토큰을 쓰던 원인이 이거였다. 밤집사가 실제로 만드는 프롬프트는 4,766자인데, discord_bot/ 한 칸 위의 ~/Projects/getback/CLAUDE.md(당시 170KB)가 매번 통째로 붙고 있었다. 2026-08-16 에 밤알바생·옛 작업이력을 docs/CLAUDE-archive-*.md 로 옮겨 1만 4천 자(92% 감소) 로 줄였다.

  • 새 봇을 만들 때는 subprocess 에 cwd 를 그 봇 폴더로 고정하고, 그 폴더에 큰 CLAUDE.md 를 두지 않는다
  • 토큰이 예상보다 크면 프롬프트 코드부터 의심하지 말고 상위 폴더의 CLAUDE.md 크기를 먼저 재라
  • ~/.claude/CLAUDE.md(전역, 약 5KB)는 항상 붙는다. 이건 어쩔 수 없다

3. launchd PATH 에는 homebrew 가 없다 — 절대경로만으론 부족하다

launchd 는 PATH 를 /usr/bin:/bin:/usr/sbin:/sbin 으로만 준다. 그래서 CLI 를 절대경로로 불러도, 그 CLI 자체가 node 스크립트면 죽는다.

Codex rc=127: env: node: No such file or directory

codex 는 /opt/homebrew/lib/node_modules/@openai/codex/bin/codex.js 로 가는 심링크이고 셔뱅이 #!/usr/bin/env node 다. PATH 에 /opt/homebrew/bin 이 없으면 node 를 못 찾는다. claude 는 네이티브 Mach-O 바이너리라 이 문제가 없다 — 그래서 claude 는 멀쩡한데 codex 폴백만 조용히 죽어 있는 상태가 만들어진다. 2026-08-16 TWC 조사봇이 주간 한도에 걸렸을 때 폴백도 같이 실패해 15시간 리포트가 끊긴 원인이 이거였다.

두 겹으로 막는다.

  1. plist 에 PATH 를 박는다 (근본)
    <key>EnvironmentVariables</key>
    <dict>
      <key>PATH</key>
      <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
    </dict>
    
  2. 스크립트에서도 env 를 보강한다 (수동 실행 대비). subprocess.run(..., env=_tool_env()) 로 /opt/homebrew/bin 을 PATH 앞에 끼운다.

진단 코드도 같이 봐라. subprocess.run 은 셔뱅 실패(rc=127)에 예외를 안 던진다. try/except 만으로 점검하면 죽은 CLI 를 OK 로 찍는다. TWC 조사봇 --check 가 정확히 이 버그였고, 그래서 폴백이 몇 달 고장난 걸 아무도 몰랐다. 반드시 returncode 를 확인할 것.

검증은 launchd 환경을 재현해서 한다.

ssh mac-mini 'cd ~/ops/<봇> && env -i HOME=$HOME PATH=/usr/bin:/bin:/usr/sbin:/sbin /opt/homebrew/bin/python3 followup.py --check'

LLM 호출은 구독으로만

API 키(ANTHROPIC_API_KEY)를 쓰지 않는다. 밤밤이 명시적으로 금지했다. ~/Projects/getback/agents/llm_cli.py 가 공용 호출 모듈이다. claude -p --output-format text 를 stdin 으로 부르고, CLAUDE_CODE_OAUTH_TOKEN 을 넘긴다. PATH 가 없는 launchd 환경 대비로 /opt/homebrew/bin/claude 하드코딩 폴백이 있다.

사용량 한도(weekly limit) 문구가 나올 때만 Codex 로 한 번 재실행한다. 일반 오류로는 넘어가지 않는다. 자세한 규칙은 claude-codex-fallback 스킬.

모델은 --model 을 안 줘서 CLI 기본값(2026-08 기준 claude-sonnet-5)을 쓴다. 고정하려면 --model sonnet|opus|fable.

자주 하는 일

# 상태
ssh mac-mini 'for S in com.bambam.knowledge-bot-a com.bambam.daily-brief-agent com.getback.bamnyangi; do echo "=== $S ==="; launchctl print gui/$(id -u)/$S 2>/dev/null | grep -iE "^\s+(state|pid) "; done'

# 재시작 (kickstart 필수)
ssh mac-mini 'launchctl kickstart -k gui/$(id -u)/com.bambam.knowledge-bot-a'

# 로그 — 실제 로그는 bot.error.log 에 쌓인다 (bot.log 는 비어있는 경우가 많다)
ssh mac-mini 'tail -30 ~/Projects/knowledge-bot-a/bot.error.log'

# 디스코드 안 거치고 답변 엔진만 시험
ssh mac-mini 'cd ~/Projects/knowledge-bot-a && set -a && . ./.env && set +a && ~/Projects/getback/.venv/bin/python answer.py "질문"'

코드는 로컬에서 쓰고 scp 로 보낸다. 히어독으로 원격에 파이썬을 직접 쓰면 따옴표·한글 이스케이프가 깨진다(실제로 깨졌다).

새 봇을 만들 때

knowledge-bot-a 를 통째로 복사하고 answer.py 의 지식 소스만 바꾸는 게 가장 빠르다. store.py·bot.py·persona.md 는 거의 그대로 간다.

만들기 전에 확인할 것:

  • 어느 계정으로 DM 하는가 — 봇은 자기와 같은 서버에 있는 사람하고만 DM 이 열린다
  • 공개 채널에도 둘 것인가 — 그렇다면 지식 범위를 나눈다. 지식봇A은 DM 에선 밤밤판(대외비 포함), 채널에선 커뮤니티A판(내부 데이터 없음)을 쓴다. 규칙으로 막지 말고 자료를 안 주는 방식으로 분리한다
  • 봇끼리 무한루프 — 사람이 안 끼어든 연속 봇 응답이 3회 넘으면 침묵하게 한다
  • 응답에 식별 접두어를 붙인다(📓 [지식봇A] 등)
  • allowed_mentions=discord.AllowedMentions.none() 로 멘션 사고를 막는다