OpenCode 2.0 로컬 공유 서비스와 멀티에이전트, 연결과 위임 구조 이해하기

OpenCode 2.0의 로컬 공유 서비스와 멀티에이전트는 맡은 일이 다릅니다. 로컬 공유 서비스는 연결을, 멀티에이전트는 작업 위임을 담당해요. 로컬 공유 서비스는 사용자 계정 단위로 도는 백그라운드 서버 하나에 여러 클라이언트를 붙이는 방식입니다. 멀티에이전트는 부모 세션이 자식 세션에 작업을 넘기는 구조이고요. 그러니 터미널 창을 여러 개 열었다고 서버나 에이전트가 그만큼 생기지는 않아요.

구조는 '클라이언트 → 공유 서버 → 부모·자식 세션' 순서로 따라가면 잘 보입니다. 터미널과 웹 UI는 접속 창구일 뿐이고, 세션과 실행을 관리하는 쪽은 서버예요. 에이전트는 각 세션 안에서 실제 작업을 수행합니다. 저는 먼저 지금 어느 서버에 연결돼 있는지부터 확인하고, 그다음에 그 안에서 누가 누구에게 일을 맡기는지 보시길 권해요. 연결 구조를 잡지 않은 채 위임부터 보면 '창 하나 = 에이전트 하나' 같은 오해가 섞이기 쉽습니다.

터미널과 웹 UI는 어디에 연결될까

공유 서버가 관리하는 것은 세션, 설정, 권한, 도구 실행입니다. 기본 실행에서는 이미 떠 있는 백그라운드 서버를 찾고, 없으면 새로 시작해요. 로컬 클라이언트들은 모두 이 서버에 붙습니다. 터미널마다 독립된 실행 환경이 하나씩 생긴다고 생각하면 연결 구조를 잘못 이해하게 돼요.

실행 방식은 접속 목적에 따라 고르면 됩니다.

• opencode: 사용자 계정의 공유 백그라운드 서버에 연결합니다.
• opencode --standalone: 전용 서버를 사용합니다.
• opencode --server <URL>: 지정한 서버에 연결합니다.

지금 실제로 어떤 상태인지, 접속 주소가 무엇인지는 opencode service status로 확인할 수 있어요.

웹 UI도 터미널 UI와 같은 서버를 씁니다. 기본 수신 범위는 localhost이고 비밀번호로 보호되기 때문에, 웹 화면이 있다고 해서 외부에 공개된 서비스로 볼 필요는 없어요. 연결 방식을 바꿀 생각이라면 공식 CLI 문서를 기준으로 공유 연결과 전용 서버 실행을 나눠서 보시면 됩니다.

구현 담당이 읽기 전용 리뷰 담당에게 일을 넘기는 방식

OpenCode에서 에이전트는 시스템 프롬프트, 모델, 권한 등을 하나로 묶은 이름 있는 프로필입니다. 모드는 세 가지예요. primary는 주 세션에서, subagent는 자식 세션에서 쓰이고, all은 양쪽 모두에 쓸 수 있습니다. 여기서 흔히 놓치는 부분이 있는데, 새로 만든 사용자 정의 에이전트의 기본 모드가 primary라는 점이에요. 리뷰 담당을 위임 대상으로 쓰려면 모드부터 확인하는 게 순서입니다. 모델을 따로 지정하지 않은 서브에이전트는 부모 세션의 모델을 그대로 물려받아요.

예를 들어 구현 담당이 코드 변경을 끝낸 뒤 읽기 전용 리뷰 담당을 호출한다고 해 봅시다. 부모 쪽에는 그 리뷰 에이전트를 호출할 수 있는 subagent 권한이 있어야 해요. 자식 쪽에는 edit와 shell을 거부하도록 설정해서 파일 수정과 셸 실행을 막아 두세요. 정리하면 호출할 수 있느냐는 부모의 권한이, 호출된 뒤 무엇을 할 수 있느냐는 자식의 권한이 결정합니다. 구체적인 설정 예시는 공식 Agents 문서에 있어요.

역할 이름에 '읽기 전용'이라고 붙이는 것보다 실제 권한 설정이 먼저입니다.

위임 요청을 쓸 때도 헷갈리는 지점이 하나 있어요. 자식 세션은 새 컨텍스트에서 시작하기 때문에 부모가 나눈 대화를 알지 못합니다. 그런데 다 알고 있을 거라 기대하고 "방금 작업을 검토해 줘"라고만 보내면 작업 범위가 흐려지죠. 위임 요청에는 에이전트 ID와 짧은 작업 설명을 넣고, 프롬프트에는 목표, 관련 파일, 제약, 반환 형식을 담아 주세요. 리뷰라면 검토할 파일과 변경 목적, 수정 금지 조건에 더해 문제 위치와 이유를 돌려달라는 요구까지 적어 두는 편이 훨씬 분명합니다.

실행 방식은 전경과 백그라운드로 나뉩니다. 전경 실행은 자식의 결과가 나올 때까지 기다려요. 반면 background: true는 곧바로 반환하고, 작업이 끝나면 부모에게 완료를 알립니다. 결과를 받아야 다음 판단을 내릴 수 있다면 전경이, 기다리는 동안 다른 일을 진행할 수 있다면 백그라운드가 맞아요. 반환된 sessionID를 쓰면 같은 자식 대화를 이어갈 수도 있습니다.

자식 세션과 작업 공간은 어디까지 나뉠까

문서에 나오는 기본 중첩 깊이 1은 위임이 아래로 몇 단계까지 이어질 수 있는지를 뜻합니다. 동시에 돌릴 수 있는 자식 세션 수의 상한과는 다른 개념이에요. 이 값만 보고 "에이전트는 하나만 실행할 수 있다"고 읽으면 안 됩니다.

대화 컨텍스트가 나뉘는 것과 파일 작업 공간이 분리되는 것도 따로 봐야 해요. 공식 Tools 문서는 worktree 생성과 세션 이동을 별도 기능으로 소개합니다. 그러니 자식 세션을 만드는 것만으로 별도 worktree가 생기거나 파일 충돌까지 해결된다고 보기에는 근거가 부족해요. 구현 작업을 여러 개 맡길 계획이라면 수정할 파일 범위와 작업 공간을 나눌지부터 정해 두세요.

공유 서버에서 프로젝트별 성능이 격리되는지도 확인된 보장으로 전제하지 말고, 필요한 실행 조건을 따로 확인하시길 권합니다.

여기서 설명한 범위는 2026-10-21 기준 공식 V2 문서이며, 특정 2.0.x 패치에서 검증된 동작을 뜻하지는 않습니다.