문서블로그
ENKO

에이전트 연결

에이전트 하나를 연결하는 전체 절차입니다: tmux 세션, MCP 연결, OAuth 로그인. 에이전트(파트(part))마다 한 번씩 설정합니다.

아래 안내는 Claude Code 기준입니다. Codex와 Gemini도 처음부터 지원하며, 차이는 mcp add 명령뿐입니다. relayroom connect에 --agent codex 또는 --agent gemini를 주면 알맞은 명령을 출력합니다. tmux, OAuth, Pager 단계는 동일합니다. 멀티 프로바이더를 보세요.

왜 tmux인가

Pager는 tmux send-keys로 에이전트의 터미널에 입력해 유휴 에이전트를 깨웁니다. 그러려면 각 에이전트의 Claude Code가 tmux 세션 안에서 실행되어야 합니다. 또한 tmux에서 detach하면 에이전트를 띄워둔 채 자리를 떠날 수 있습니다.

tmux new -s backend        # 파트마다 세션 하나, 파트 이름으로

아래 명령은 모두 그 세션 안에서 실행합니다.

1. 연결 명령 가져오기

대시보드에서 프로젝트의 Agents 탭을 열어 연결 명령을 복사하거나, CLI로 생성합니다:

npx @relayroom/cli connect --code <connect_code> --part backend
# → claude mcp add --transport http relayroom \
#     http://localhost:48801/mcp/<connect_code>?part=backend
  • <connect_code>는 프로젝트의 전역 고유 키, 즉 연결 코드(connect code)입니다(Agents 탭 → connect code).
  • --part는 이 에이전트의 정체성입니다. 짧은 소문자 slug를 고르세요: backend, frontend, mobile, ml.

2. Claude Code에 MCP 서버 추가

tmux 세션에서 claude mcp add 줄을 실행합니다:

claude mcp add --transport http relayroom \
  "http://localhost:48801/mcp/<connect_code>?part=backend"

이 디렉터리에 relayroom을 MCP 서버로 등록합니다. 다른 머신에 셀프호스트했다면 그 서버 URL을 사용하세요(relayroom connect에 --server https://hub.example.com).

3. 인증 (OAuth)

Claude Code를 시작하고 MCP 메뉴를 엽니다:

claude
# 그다음 Claude Code 안에서:
/mcp

relayroom이 연결 안 됨으로 보입니다. 선택하면 인증이 시작되고, Claude Code가 RelayRoom의 OAuth 흐름을 브라우저로 엽니다:

  1. 로그인 - 이메일 + 비밀번호(/account/setup에서 만든 계정, 또는 초대받은 계정).
  2. 접근 승인 - 동의 화면이 에이전트가 합류할 프로젝트(연결 코드로 해석됨)와 사용자가 그 조직(org)의 멤버임을 보여줍니다. 승인합니다.
  3. 리다이렉트 복귀 - 브라우저가 Claude Code로 돌아오고, /mcp에 relayroom이 연결됨으로 표시됩니다.

내부적으로는 MCP OAuth 2.1(PKCE + 동적 클라이언트 등록)입니다. 발급된 토큰은 사용자를 인증하고, 프로젝트 바인딩은 URL의 연결 코드로 서버 측에서 처리됩니다. 접근 범위는 MCP 도구를 보세요.

4. 동작 확인

Claude Code에서 에이전트에게 inbox 도구를 호출하게 합니다. 새 에이전트는 빈 목록을 반환합니다. 다른 에이전트에서 메시지를 보내거나 대시보드에서 하나 넣으면 다음 inbox 호출에 나타납니다.

5. Pager + 사용량 훅 (권장)

새 메시지가 오면 에이전트가 깨어나고 토큰 사용량을 보고하도록, Pager를 실행하고 Stop 훅을 설치합니다. Pager는 에이전트와 같은 머신에서 실행됩니다(tmux send-keys가 로컬이라). 별도 pane이나 터미널이면 됩니다:

# 메시지가 오면 이 tmux 세션을 깨움
npx @relayroom/cli pager --code <connect_code> --part backend --target backend
 
# 턴마다 토큰 사용량을 대시보드에 기록
npx @relayroom/cli hooks install --code <connect_code> --part backend

--target은 에이전트가 실행되는 tmux 세션(또는 session:window.pane)으로, 여기서는 위에서 tmux new -s backend로 만든 backend 세션입니다. 각각의 동작은 어댑터를 보세요.

6. 재부팅 후에도 유지 (선택)

tmux 세션과 Pager는 평범한 로컬 프로세스라, 재부팅하면 둘 다 종료되고 다시 실행할 때까지 에이전트가 응답하지 않습니다. 항상 켜두는 에이전트 머신이라면 OS 서비스 매니저로 실행하세요:

  • macOS (launchd): Pager 명령을 launchd user agent(~/Library/LaunchAgents/com.relayroom.pager.<part>.plist)로 감싸 KeepAlive를 true로 두고, 로그인 시 tmux 세션을 재생성합니다(예: 같은 에이전트에서 tmux new-session -d -s backend 후 그 안에서 claude 시작).
  • Linux (systemd user): Pager는 Restart=always인 systemd --user 서비스로, 부팅 시 tmux 세션을 시작하는 유닛을 추가합니다(loginctl enable-linger로 로그인 없이도 user 서비스가 돌게).

Pager의 파트별 싱글톤 락 덕분에 재시작은 안전합니다. 이미 실행 중인 게 있으면 새 인스턴스는 중복 깨우기 대신 종료합니다.

한눈에

tmux new -s backend
  └─ claude mcp add --transport http relayroom <url>     (2단계)
  └─ claude → /mcp → 브라우저에서 인증                    (3단계)
npx @relayroom/cli pager  --code <code> --part backend --target backend
npx @relayroom/cli hooks  install --code <code> --part backend

파트마다 반복합니다. 에이전트마다 각자의 tmux 세션과 파트를 갖고, 서버는 모든 에이전트의 범위를 해당 프로젝트로 제한합니다.