OpenCode + oh-my-opencode 운영 체크리스트 2026 — 팀에서 실제로 굴릴 때 먼저 막히는 5가지

Posted on by

설치는 금방 된다.

오히려 문제는 그다음이다.

OpenCode를 띄우고 oh-my-opencode까지 붙이면, 처음 30분은 꽤 신난다.

“어, 이거 거의 다 되네?”

근데 팀에서 실제로 굴리려는 순간부터 분위기가 달라진다.

권한은 어디까지 열지, 세션 공유는 켜도 되는지, 에이전트를 몇 개까지 돌릴지, 런북 없이 돌려도 되는지.

이런 질문이 한꺼번에 몰려온다.

Quick Answer
OpenCode + oh-my-opencode는 개인 실험 단계에서는 진입장벽이 낮다.
하지만 팀 운영 단계에서는 권한 정책, 세션 공유, 설정 drift, 역할 분리, 런북 이 다섯 군데에서 가장 먼저 막힌다.
2026년 4월 기준으로는 “설치 성공”보다 “운영 규칙을 얼마나 얇고 명확하게 잡았는가”가 훨씬 중요하다.

이 글이 필요한 사람

  • OpenCode + oh-my-opencode를 개인 장난감이 아니라 팀 도구로 올려보려는 사람
  • Claude Code 대안이나 보완재로 OpenCode 진영을 검토 중인 사람
  • 설치는 됐는데 팀원이 같이 쓰는 순간부터 귀찮아지는 이유를 알고 싶은 사람
  • AGENTS.md, opencode.json, wrapper 스크립트 같은 운영 표준을 어디까지 잡아야 할지 고민인 사람

지금 결론

  1. OpenCode 자체는 꽤 잘 만들어졌지만, 팀 운영의 난이도는 기본 기능보다 정책 레이어에서 생긴다.
  2. oh-my-opencode는 생산성을 올려주기도 하지만, 동시에 설정 표면적을 넓혀서 운영 난이도를 키운다.
  3. 팀 도입 초반에는 “기능을 많이 켜는 것”보다 “공유, 권한, 역할”을 먼저 고정하는 편이 덜 아프다.
  4. 가장 안전한 시작점은 2명 파일럿 + wrapper 명령 1개 + 수동 share + 최소 권한 조합이다.

왜 지금 이 체크리스트가 필요한가

OpenCode 공식 사이트는 2026년 4월 기준으로 이 도구를 terminal, IDE, desktop 어디서나 쓸 수 있는 오픈소스 AI coding agent로 소개한다.

여기에 multi-session, share links, GitHub Copilot login, 75+ providers 같은 메시지가 같이 붙는다.

이 말만 보면 거의 만능처럼 보인다.

문제는 팀 운영에서는 “된다”와 “굴러간다” 사이가 꽤 멀다는 거다.

OpenCode 공식 docs를 보면 권한 시스템도 있고, share 모드도 있고, tool 제어도 세밀하다.

즉, 기능은 충분하다.

그런데 기능이 충분하다는 건 반대로 운영 결정을 사람이 많이 내려야 한다는 뜻이기도 하다.

oh-my-opencode 쪽도 마찬가지다.

지금 GitHub README를 보면 기존 oh-my-opencode 명칭이 oh-my-openagent 쪽으로 넘어가는 과도기 설명이 있고, ultrawork, background agents, built-in MCPs 같은 강한 기능을 전면에 세운다.

생산성 냄새는 아주 진하다.

근데 이런 류의 도구는 기능이 강할수록 팀 룰 없이는 금방 삐끗한다.

그래서 이 글은 “설치법” 보다 “팀에서 어디서 먼저 막히는가” 에 초점을 둔다.

먼저 보는 한 장 표

체크포인트 개인 실험 팀 운영
모델/공급자 선택 대충 골라도 됨 비용, 안정성, 계정 정책까지 봐야 함
권한 설정 넉넉하게 열어도 버팀 bash, edit, webfetch부터 정책 필요
share 설정 켜도 큰일 없을 수 있음 기본값부터 다시 봐야 함
에이전트 수 많으면 재밌음 많을수록 조율 비용 증가
운영 문서 없어도 어떻게든 됨 없으면 사람마다 다른 도구가 됨

이 표가 핵심이다.

OpenCode 진영이 나쁘다는 얘기가 아니다.

오히려 반대다.

도구가 강해서 조금만 룰이 없으면 팀마다 완전히 다른 괴물이 된다.

1. 권한 정책부터 안 정하면 첫 주에 바로 꼬인다

OpenCode docs의 Tools 페이지를 보면 permission 필드로 bash, edit, webfetch 같은 도구를 allow, deny, ask 형태로 제어할 수 있다.

이건 장점이다.

근데 동시에 운영 질문이 생긴다.

“우리 팀은 뭘 allow로 두지?”

여기서 보통 첫 번째 삐끗이 난다.

흔한 증상

  • 어떤 팀원은 bash: allow
  • 어떤 팀원은 bash: ask
  • 어떤 팀원은 거의 풀오픈
  • 결과적으로 같은 프롬프트를 넣어도 행동이 다름

이 상태가 되면 도구를 쓰는 게 아니라 사람마다 다른 에이전트를 쓰는 셈이 된다.

최소 수정안

초기 파일럿에선 이 정도가 현실적이다.

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "read": "allow",
    "grep": "allow",
    "list": "allow",
    "edit": "ask",
    "bash": "ask",
    "webfetch": "allow"
  }
}

왜 이렇게 잡냐면, 처음부터 전부 막으면 사용성이 너무 떨어지고, 전부 열면 운영 검증이 불가능해진다.

즉 읽기/탐색은 열고 수정/실행은 물어보게 하는 중간 지점이 좋다.

내 기준 권장선

  • 파일럿 1주차: edit ask, bash ask
  • 파일럿 2주차: 특정 repo에서만 edit allow
  • 배포/인프라 repo: 끝까지 bash ask

여기서 괜히 멋부리다가 모든 repo에 같은 정책 밀어넣으면 진짜로 아프다.

프로젝트 성격이 다르기 때문이다.

2. 세션 공유를 기본으로 켜면 편할 줄 알았는데, 꼭 그렇진 않다

OpenCode의 Share docs를 보면 기본 모드는 manual 이다.

즉 자동 공유가 기본값이 아니다.

이건 이유가 있다.

수동 공유가 귀찮아 보여도 운영 측면에서는 꽤 건강하다.

왜냐면 팀에서 공유 링크는 단순 편의 기능이 아니라 사실상 기록 유출 지점이 될 수 있기 때문이다.

docs 기준으로 share: auto 를 쓰면 모든 새 대화가 자동 공유될 수 있고, 공유된 대화는 명시적으로 unshare 하기 전까지 접근 가능하다.

이건 혼자 쓸 땐 멋진 기능인데, 팀에선 질문이 바뀐다.

“이 세션에 민감한 로그나 코드 조각이 들어갔으면?”

팀 도입 초반 권장

{
  "$schema": "https://opencode.ai/config.json",
  "share": "manual"
}

프로젝트 단위로 더 빡세게 가려면 문서 기준 disabled도 가능하다.

즉 기본 전략은 이렇다.

  • 개인 실험: manual
  • 보안 민감 repo: disabled
  • 대놓고 데모용 repo: 그때만 auto

초반부터 auto를 켜두면 편의는 늘지만 통제는 줄어든다.

그리고 팀 도입 초반엔 편의보다 통제가 더 중요하다.

3. 설정 drift가 생각보다 빨리 생긴다

이건 OpenCode보다도 oh-my-opencode 쪽을 붙였을 때 더 크게 느껴진다.

왜냐면 기본 도구 하나가 아니라 설정층이 한 겹 더 생기기 때문이다.

지금 oh-my-openagent README를 보면 명칭 전환기 때문에 패키지명은 oh-my-opencode, 플러그인 엔트리는 oh-my-openagent, 레거시 파일명도 일부 호환하는 구조가 공존한다.

이건 과도기엔 현실적인 선택이다.

근데 팀 운영에서는 무슨 일이 벌어지냐면, 누군가는 예전 이름으로 설치하고, 누군가는 새 문서를 보고 따라 하고, 누군가는 둘 다 섞는다.

그 순간부터 drift가 생긴다.

흔한 drift 예시

  • 사용자 A: 구버전 설치 방식
  • 사용자 B: 최신 설치 문서 기반
  • 사용자 C: JSONC 파일 사용
  • 사용자 D: 프로젝트 단 설정 없이 개인 홈 설정만 사용

겉보기에는 다 “OpenCode 쓴다”인데 실제로는 네 가지 다른 하네스를 돌리는 셈이다.

해결책

초기엔 멋지게 하지 말고 딱 하나만 고정해야 한다.

예를 들어:

  1. 설치 명령 1개
  2. 설정 파일 위치 1개
  3. wrapper 명령 1개
  4. 점검 명령 1개

이 네 개만 같아도 운영 난이도가 확 줄어든다.

추천 문서 한 장

팀 위키에 최소 이 네 줄은 있어야 한다.

bunx oh-my-opencode install
opencode --version
cat ./opencode.json
./scripts/agent-run.sh

이 정도가 없으면 나중에 모든 디버깅이 “너 뭐로 깔았는데?” 부터 시작된다.

진짜 귀찮다.

4. 에이전트를 많이 돌리면 무조건 빨라질 거라는 기대가 가장 위험하다

oh-my-openagent README는 background agents 와 ultrawork 를 강하게 민다.

이건 분명 매력적이다.

근데 팀 운영에서는 에이전트 수가 생산성과 거의 1:1로 비례하지 않는다.

오히려 초반엔 반대일 때가 많다.

왜 느려지냐

  • 모델 호출 수가 늘어난다
  • 로그 읽는 비용이 늘어난다
  • 누가 최종 결정권자인지 흐려진다
  • 실패했을 때 원인 추적이 어려워진다

즉 에이전트가 늘어날수록 사람의 오케스트레이션 비용도 같이 오른다.

2명 파일럿 기준 권장 구조

역할 권장 수
메인 실행 에이전트 1
탐색/리서치 보조 1
동시에 돌리는 총 에이전트 2

처음부터 4개, 5개, 6개 돌리는 건 데모는 멋있어도 운영은 잘 안 예쁘다.

특히 팀원이 도구에 아직 익숙하지 않으면 결과 요약을 읽는 시간만 길어진다.

이럴 때만 늘려라

  • 명확하게 독립된 탐색 작업이 있을 때
  • 결과물을 합치는 주체가 명확할 때
  • 세션 로그를 누가 검토할지 정했을 때

그러니까 “에이전트 많이 = 고급” 이 아니다.

“에이전트 많이 = 운영비도 같이 증가” 에 더 가깝다.

5. 런북 없는 도입은 거의 항상 사람 피곤하게 끝난다

여기서 말하는 런북은 거창한 운영 백서가 아니다.

진짜 최소한이면 된다.

예를 들면:

  • 어떻게 설치하는지
  • 어떤 명령으로 시작하는지
  • 어디까지 허용하는지
  • 세션 공유는 어떻게 하는지
  • 실패하면 어디부터 보는지

이 다섯 줄만 있어도 된다.

문제는 많은 팀이 이 다섯 줄을 안 쓴다는 거다.

왜냐면 처음엔 다들 “알아서 하겠지” 싶기 때문이다.

근데 OpenCode류 도구는 알아서 하겠지 모드로 시작하면 결국 각자 다른 방식으로 익숙해진다.

그럼 그다음부터는 표준화 비용이 더 비싸다.

내가 권하는 최소 런북 구성

설치

  • 설치 명령
  • 버전 확인 명령

실행

  • 기본 실행 명령
  • 파일럿용 권장 플래그

공유

  • 기본값은 manual
  • 외부 공유 금지 repo 명시

권한

  • bash/edit 기본 ask
  • 예외 repo 목록

장애 대응

  • 설정 파일 경로
  • 로그 확인 순서
  • 재설치 명령

이 정도면 충분하다.

중요한 건 두께가 아니라 모두가 같은 문서를 본다는 사실이다.

2명 파일럿으로 시작할 때 실제 체크리스트

아래 정도면 초반 사고를 꽤 줄인다.

시작 전

  • OpenCode 버전 통일
  • oh-my-opencode 설치 방식 통일
  • opencode.json 샘플 배포
  • 공유 정책 결정
  • 민감 repo 제외

1주차

  • 2명만 사용
  • 읽기/탐색 중심 태스크만 허용
  • 편집/실행은 ask 유지
  • 세션 공유는 manual만
  • 매일 10분 회고

2주차

  • 반복 태스크 1개 자동화
  • wrapper 명령 1개 고정
  • 공통 프롬프트 문장 최소화
  • 실패 로그 예시 수집

3주차

  • allow 범위 확대 여부 결정
  • 서브에이전트 수 재조정
  • 팀용 문서 1차 확정

이렇게 가면 속도는 아주 폭발적이지 않을 수 있다.

대신 덜 망한다.

그리고 팀 도입 초반엔 덜 망하는 게 훨씬 중요하다.

실수 TOP 5

1. 설치 성공을 도입 성공으로 착각하는 실수

설치가 된 건 그냥 입장권을 받은 거다.

운영이 시작된 게 아니다.

2. share를 auto로 켜고 나중에 정리하자는 실수

나중에 정리하자는 말은 대체로 나중에 안 정리한다.

초기값부터 보수적으로 가는 게 낫다.

3. 사람마다 다른 설정을 허용하는 실수

자유도는 좋아 보이지만, 운영 단계에선 재현성을 깎는다.

4. 서브에이전트를 많이 돌릴수록 고급이라고 믿는 실수

처음엔 멋있다.

근데 로그 읽는 사람이 지친다.

5. 런북 없이 “잘 되면 문서화하자”라고 미루는 실수

그 상태로 2주 지나면 문서화 비용이 두 배로 뛴다.

FAQ

Q. 팀 도입 초반부터 oh-my-opencode까지 꼭 붙여야 하나?

반드시 그럴 필요는 없다.

다만 역할 분리, 하네스화, 운영 실험까지 보려면 붙여보는 쪽이 배울 건 많다.

대신 그만큼 설정 표면적도 넓어진다.

Q. 세션 공유는 완전히 꺼야 하나?

그건 아니다.

민감하지 않은 repo나 데모/교육용 환경에서는 manual 공유가 꽤 유용하다.

문제는 초반에 기본값을 너무 공격적으로 잡는 경우다.

Q. OpenCode만으로 충분하지 않나?

개인 작업 기준으로는 충분할 수 있다.

팀 운영 관점에서는 추가 레이어가 주는 이점도 있고, 그만큼 복잡도도 올라간다.

그래서 “무조건 붙여라”보다 “왜 붙이는지 명확할 때 붙여라”가 더 맞다.

Q. Claude Code 대체제로 바로 팀 전체 전환해도 되나?

그건 좀 이르다.

보완재로 파일럿부터 돌리는 게 안전하다.

특히 권한과 공유 정책은 파일럿 회고 없이 바로 넓히면 피곤해진다.

다음에 읽을 글

출처