문제 해결

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

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인지는 에이전트 CLI 설치을 보세요.

up --use-herdr가 잘 돌았는데 워크트리는 여전히 tmux

그 워크트리의 rr.sh가 0.8.0 이전 것입니다. 그 세대는 아는 플래그만 골라 쓰고 나머지는 조용히 버렸기 때문에, 명령은 성공하고 tmux가 떴습니다. 아무것도 그렇다고 말해주지 않았습니다.

터미널이 아니라 설정에 물어보세요.

grep multiplexer .relayroom/config.json

multiplexer 필드가 없으면 전환은 일어나지 않은 것입니다. 스크립트를 고친 뒤 전환하세요.

npm i -g @relayroom/cli
./rr.sh update --self
./rr.sh up --use-herdr

0.8.0부터 같은 실수는 플래그를 지목하는 에러가 됩니다. 그 전에 기록된 rr.sh 사본에만 해당하는 문제입니다. 업데이트를 보세요.

herdr 파트인데 tmux로 전달되고 있음

Pager가 herdr 소켓에 도달하지 못해 tmux 전달로 폴백하고 계속 돌고 있는 것입니다. wake는 여전히 도착합니다. 그래서 고장으로 보이지 않습니다. 그 파트가 요청받은 곳에서 돌고 있지 않을 뿐입니다.

정상이 아니라 degraded 상태입니다. 이 머신에서 herdr가 떠 있는지 확인한 뒤 ./rr.sh up으로 원래 경로에 되돌리세요.

대시보드에서 확인하려면 에이전트 목록의 그 파트 행을 보세요. 배지는 실제로 전달되고 있는 멀티플렉서를 보여주고, 그것이 요청한 것과 다르면 amber로 바뀌면서 요청한 값에 취소선을 긋습니다. 설정이 아니라 측정값이라서 당신이 고른 것과 어긋날 수 있고, 그 어긋남이 바로 이 배지가 존재하는 이유입니다. 배지가 아예 없는 파트는 0.8.0 이전 Pager를 쓰는 것이라 두 값 중 아무것도 보고하지 않습니다. 그건 "tmux"가 아니라 "보고 안 됨"입니다.

의도된 비대칭에 주의하세요. up --use-herdr는 소켓에 도달할 수 없으면 시작을 거부하지만, Pager는 조용해지는 대신 폴백합니다. 전달이 계속되는 것이 깔끔한 것보다 낫습니다.

herdr 서버 재시작 뒤 에이전트가 권한 프롬프트에서 멈춤

herdr가 레이아웃과 각 에이전트의 대화를 복원했으므로 전부 복구된 것처럼 보입니다. 하지만 복원된 명령은 맨 claude --resume <id>입니다. 실행 플래그는 복원 대상이 아니라서, --bypass로 띄웠던 파트가 그것 없이 돌아온 것입니다.

그 워크트리에서 ./rr.sh up --restart를 돌리세요. 그냥 up으로는 안 됩니다. 페인에 이미 에이전트가 있는 것을 보고 플래그가 적용되지 않았다고 알려줍니다. herdr 서버가 재시작된 뒤를 보세요.

herdr 머신인데 relayroom init이 "not inside a tmux session"이라고 함

error: not inside a tmux session.
...
(advanced: pass --no-tmux-check to skip this guard.)

이 파트가 어느 멀티플렉서를 쓰는지 init에 알려주세요.

relayroom init --code <connect_code> --part backend --multiplexer herdr
./rr.sh up --use-herdr

--multiplexer herdr가 선택을 기록하고 검사를 건너뜁니다. 이 가드는 Pager가 에이전트의 tmux 페인에 타이핑해서 깨우기 때문에 있고, init은 달리 말해주지 않는 실행에는 계속 적용합니다.

여기 도달하는 이유가 두 가지이고, 해결책이 서로 다릅니다.

--no-tmux-check도 비상구로 여전히 동작하지만 --multiplexer herdr를 쓰세요. 검사를 억누르기만 하는 대신 그 워크트리에 대해 참인 것을 말해주는 쪽이고, 다음 가드에서도 살아남는 건 앞쪽입니다.

up이 다른 에이전트나 다른 파트로 떴음

대개 위와 같은 문제가 한 단계 뒤에 나타난 것입니다. 위의 가드는 init이 무언가를 쓰기 전에 종료하므로, .relayroom/config.json에는 이전 실행이 남긴 값이 그대로 있습니다. 예전 파트나 다른 에이전트요. 그리고 up은 그것을 충실히 띄웁니다.

입력한 명령이 아니라 설정을 읽으세요.

cat .relayroom/config.json

part나 agent가 요청한 것과 다르면 init이 완료되지 않은 것입니다. 다시 실행하고(herdr 머신이면 --multiplexer herdr와 함께) 그다음 up입니다.

0.8.1부터는 원인 단계에서 걸립니다. --part나 --agent를 명시적으로 줬는데 저장된 설정과 다르면 init이 거부하고, 두 값을 모두 출력한 뒤 의도적으로 워크트리를 옮기려면 --force를 쓰라고 알려줍니다. 플래그를 생략하면 예전처럼 저장된 값을 그대로 재사용하므로, 인자 없는 재실행의 동작은 달라지지 않습니다.

"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은 이걸 자동으로 합니다.