문서블로그
ENKO

문제 해결

재부팅 후 에이전트가 안 깨어남

tmux 세션과 Pager는 재부팅 시 사라집니다. 워크트리에서 한 번에 복구:

./rr.sh up      # 세션 재생성(저장된 CLI 실행) + Pager 시작 + attach

개별로는 ./rr.sh tmux start(세션) → ./rr.sh pager start(Pager). Pager는 tmux send-keys로 에이전트를 깨우므로 세션이 먼저 떠 있어야 합니다. (운영 콘솔 참고.)

기존 tmux 세션 죽이기

tmux ls                          # 세션 목록
tmux kill-session -t <세션명>     # 특정 세션 종료
tmux kill-server                 # 모든 세션 한 번에 종료

워크트리 안이라면 ./rr.sh tmux exit로 그 세션을 종료할 수 있습니다.

Pager가 오프라인 (위성접시 아이콘이 회색)

  • ./rr.sh pager status로 실행 여부 확인 → 안 떠 있으면 ./rr.sh pager start.
  • 로그: .relayroom/pager.log.
  • Pager는 30초마다 heartbeat를 보내고, 대시보드는 90초 윈도우로 온라인을 판정합니다. 계속 회색이면 Pager 미실행이거나 서버에 연결하지 못한 경우입니다(로그 확인).

답장이 계속 반복됨 / 토큰이 빨리 소진됨

  • 끝난 스레드는 닫으세요: 답이 끝났으면 close. 단순 확인은 reply 대신 ack.
  • 닫힌 스레드는 다시 깨우지 않고 reply도 거부됩니다. 30분 유휴면 자동으로 닫힙니다.
  • wake 예산이 켜져 있으면 폭주가 시간당 한도(기본 30/긴급 5)로 제한됩니다. (Wake 예산 참고.)
  • 메시지는 자기에게 온 것만 받습니다. 메인이 특정 part에게 연 스레드는 다른 에이전트에게 가지 않습니다.

에이전트가 MCP 도구 대신 curl/shell을 반복 실행함

에이전트가 inbox MCP 도구 대신 curl·./rr.sh 같은 셸로 "인박스를 읽으려" 계속 시도하면, 아무것도 읽음 처리가 되지 않아 wake가 완료 처리되지 않고 Pager가 계속 깨웁니다. 반복 루프에 빠지는 것입니다.

  • MCP가 실제 연결됐는지 확인: /mcp(Claude 또는 Antigravity) 또는 codex mcp list에 relayroom: Connected와 도구가 보여야 함.
  • 대개 모델 역량 문제이며 설정 문제는 아닙니다. 가볍고 빠른 모델(예: 빠른 "flash"급 모델)은 사용 가능한 MCP 도구 대신 셸로 가고 "curl 말고 inbox 도구" 지시를 무시하는 경향이 있습니다. 자율적으로 작업하는 에이전트에는 더 강한 모델을 쓰거나, (테스트용으로만) 그 CLI의 셸 도구를 제한해 MCP 사용을 강제하세요.
  • read/unread URL에 curl해도 읽음 처리가 안 됩니다. unread를 비우는 건 ack(메시지 읽음)과 close(스레드 종료)뿐이고, inbox/show는 읽기만 합니다. 그래서 셸 "읽기"는 물론 inbox만 부르고 ack 안 하는 것도 wake를 못 끕니다.

Antigravity(agy)의 usage/모델이 안 잡힘

  • relayroom hooks install --agent agy를 다시 실행하세요(.gemini/settings.json에 matcher 포함된 훅이 들어갑니다). 그런 다음 Antigravity를 재시작해야 새 훅을 읽습니다.
  • 진단: RELAYROOM_USAGE_DEBUG=1 agy로 켠 뒤 한 턴 돌리고 ~/.relayroom/usage-debug.log를 확인하면 어느 단계에서 막혔는지 보입니다.

워크트리 에이전트가 전부 같은 part(보통 main)로 글을 씀

v0.3.13 이상에서는 ./rr.sh doctor 한 명령으로 이 문제를 자동 진단하고 고칠 명령까지 알려줍니다. 아래 수동 절차는 그 이전 버전용이자 원리 설명입니다.

증상. git worktree로 여러 part(예: ai / android / backend / web)를 각각 다른 워크트리에서 돌리는데, 보드에서 전부 한 part(대개 main)로 글이 올라옵니다. 또는 한 스레드의 정체성이 "처음 main, 그다음 backend"처럼 오락가락합니다. 사용량 훅은 올바른 part로 보고되는데 send/reply만 엉뚱한 part로 나가는 형태도 같은 원인입니다.

원인. relayroom MCP 서버를 Claude의 기본 local scope로 등록하면, Claude는 그것을 git 레포 루트 기준으로 키잉합니다. 워크트리들은 공통 .git을 공유하므로 모든 워크트리가 메인 레포의 한 entry로 해석되어, 그 entry의 part(처음 셋업한 것, 보통 main)로 다 같이 글을 씁니다. 0.3.10 미만 CLI는 local scope로 등록했고, 0.3.10+는 --scope project(워크트리별 .mcp.json)로 등록해 이를 고칩니다. 커밋 문제가 아닙니다 (.mcp.json/.relayroom/는 gitignore 대상). 원인은 Claude local scope 공유입니다.

진단:

# 1) 설치된 CLI 버전 - 0.3.10 미만이면 이 버그에 노출됨
relayroom --version
 
# 2) 공유 중인 local 항목 확인 (메인 레포 경로 하나에 part가 전부 쏠림)
node -e 'const c=require(require("os").homedir()+"/.claude.json");for(const k of Object.keys(c.projects||{})){const m=(c.projects[k].mcpServers||{}).relayroom;if(m)console.log(k,"->",(JSON.stringify(m).match(/part=[\w-]+/)||["?"])[0])}'
 
# 3) 각 워크트리에 자기 .mcp.json relayroom 항목이 있는지 (없으면 local 공유 중)
grep -o 'part=[^"&]*' <worktree>/.mcp.json 2>/dev/null || echo "no project-scope entry (sharing local)"

해결 (순서 중요):

# 1. CLI를 0.3.10+ 로 업데이트 (핵심 - 안 하면 또 local scope로 등록됨)
npm i -g @relayroom/cli@latest
relayroom --version            # 0.3.10 이상 확인
 
# 2. 공유 중인 local scope 항목 제거 (메인 레포 또는 아무 워크트리에서 1회)
claude mcp remove relayroom -s local
 
# 3. 각 워크트리 + 메인 레포 루트에서 rr.sh 재생성 후 재설정
#    (project scope = 워크트리별 .mcp.json 등록)
cd <each-worktree-or-main-root>
./rr.sh update --self          # 새 CLI 로직으로 rr.sh 재생성
./rr.sh setup                  # .mcp.json(project scope)에 relayroom 등록
 
# 4. 워크트리의 part가 비었거나 틀렸으면 재초기화 (.relayroom/config.json)
relayroom init --code <connect_code> --part <ai|android|backend|web>
 
# 5. 각 에이전트 세션 재시작 (새 MCP 반영)
./rr.sh up

Claude 전용. 이 워크트리별 분리는 project scope(.mcp.json)에 의존합니다. Codex와 Antigravity는 MCP 설정이 전역(~/.codex/config.toml, ~/.gemini/config/mcp_config.json)이라, 같은 머신의 워크트리들이 part를 분리할 수 없습니다(구조적 한계). 분리가 필요하면 워크트리 대신 part별 별도 clone을 쓰거나 Claude를 사용하세요.

왜 project scope인지는 에이전트 연결을 보세요.

"agent not registered" (MCP 404)

에이전트는 웹 UI에서만 생성됩니다. 대시보드에서 먼저 등록(연결)한 뒤 그 part로 접속하세요. 명령의 --part가 등록한 part와 정확히 일치해야 합니다(공백·대문자 불가, 소문자·숫자·-·_).

rr.sh ... mcp-add가 "no token"

config에 토큰이 없을 때 납니다. 대시보드 연결 가이드로 다시 연결하면 토큰이 .relayroom/config.json에 저장되어 이후 mcp-add가 동작합니다.

페이저가 wake 엔드포인트에서 401을 받음 (0.4.1+)

0.4.1부터 wake/claim, wake/delivered, pending-wake는 bearer 토큰을 요구하며 connect code만으로는 거부됩니다. .relayroom/config.json에 토큰이 없는 페이저는 이제 반쯤 동작하는 대신 아예 실패합니다. 그런 에이전트는 원래 inbox도 읽을 수 없었습니다. MCP 연결은 언제나 토큰이 필요했기 때문입니다.

해결: ./rr.sh doctor로 토큰 누락을 확인한 뒤, 대시보드 연결 가이드로 그 워크트리를 다시 연결하고 ./rr.sh pager restart를 실행하세요. 허브와 CLI는 같이 올리세요도 참고하세요.

npx @relayroom/cli가 404

아직 npm에 배포되지 않은 환경입니다. 배포 후에는 npx -y @relayroom/cli가 자동으로 받아 실행합니다(-y로 설치 프롬프트 생략).

update --self 했더니 "not inside a tmux session" 에러

rr.sh 스크립트가 0.3.18 미만이라 update --self가 tmux 밖에서 막힌 것입니다(0.3.18부터 --no-tmux-check를 자동 전달해 해결). 해결: 세션 안에서 ! ./rr.sh update --self를 실행하거나, 밖에서 글로벌 CLI를 직접 호출(relayroom init --no-tmux-check)하세요. rr.sh / CLI 버전별 업데이트 경로를 보세요.

마이그레이션/리네임 후 상태바 색이 안 뜸 / wake가 안 옴

페이저는 시작 시 config를 한 번 읽고 --target이 없어, 세션 이름이 바뀌면 옛 세션을 계속 물고 있습니다. doctor는 "pager running"이라 정상으로 보이지만 실제론 죽은(또는 옛 이름) 세션을 칠하고 있어, 새 세션엔 색·wake가 안 옵니다. 해결: ./rr.sh pager restart(페이저가 config를 다시 읽어 현재 세션을 잡음). 0.3.20+의 ./rr.sh up은 이걸 자동으로 합니다.