핵심 요약
- OpenCode에는 Build와 Plan 두 가지 기본(프라이머리) 에이전트가 내장되어 있습니다. Tab으로 순환 전환하고, 상태 표시줄 배지(Plan · Big Pickle, Build · MiMo)가 지금 누가 응답하는지 항상 알려줍니다.
- 플랜 모드는 설계상 읽기 전용입니다. 파일 편집은 기본적으로 거부되거나 승인을 요구하고 bash 명령은 확인을 거치므로, 리포 분석·명확화 질문·계획 문서만 받을 뿐 수정되는 파일은 없습니다.
- /models는 모드별로 실행하세요. 계획에는 강한 모델(영상에서는 GLM-5.2), 빌드에는 저렴한 무료 모델(MiMo V2.5 Free)을. opencode.json의 agent.model로 고정할 수도 있습니다.
- 플랜 모드가 "없다"고요? CLI를 업데이트하고, 메뉴 항목이 아니라 상태 표시줄 배지를 찾고, 터미널이 Tab을 가로챈다면 키를 바꾸세요. 그리고 데스크톱 앱은 아직 베타입니다.
13/13 - OpenCode - Plan mode Implementar funcionalidad
채널: Fernando Herrera10:05
OpenCode Full Tutorial: Free Models, Skills & MCPs
채널: Eric Tech23:11
Opencode Is Probably The Best Coding Agent I've Ever Used
채널: DevOps Toolbox
Agents — official documentation
공식 문서: opencode.ai/docs
모드 동작 — Tab 순환 전환, 에이전트별 모델, Plan의 권한 제한, --agent plan 플래그 — 는 공식 agents 문서로 검증했습니다. 위의 영상들은 시각 자료이자 사실 출처입니다. 기본 영상의 모델 응답은 스페인어라서, UI만으로 흐름이 설명되는 장면을 프레임으로 골랐습니다.
스크린샷의 저작권은 각 제작자에게 있으며 정확한 타임스탬프로 연결되는 딥 링크를 함께 제공합니다. 얼굴이 나오는 프레임은 사용하지 않았습니다.
OpenCode 플랜 모드, 단계별로 사용하기
파트 1 — Plan·Build 에이전트 만나기
- 1
OpenCode를 실행하고 모드 배지 찾기
프로젝트 안에서 opencode를 실행하세요. 터미널 UI가 열리면 프롬프트 아래 상태 표시줄에 Plan 또는 Build와 현재 모델이 표시됩니다 — 영상에서는 Plan · Big Pickle OpenCode Zen. 이 배지가 플랜 모드의 자리입니다. 별도의 플랜 모드 메뉴는 찾을 필요가 없습니다. 하단 힌트(tab agents)가 전환 방법까지 알려줍니다.
OpenCode의 환영 화면 — 모든 것까지 Tab 한 번. 상태 표시줄에는 이미 Plan · Big Pickle OpenCode Zen이 보입니다.0:50에 보기 - 2
플랜 모드가 무엇이고 무엇을 거부하는지 알기
Plan은 OpenCode의 두 기본 에이전트 중 하나입니다. Build는 모든 도구가 활성화된 채로 제공되고, Plan은 제한적입니다 — 기본값으로 파일 편집은 거부되거나 승인을 요구하고, bash 명령도 먼저 확인합니다. 문서는 Plan을 "코드 분석, 변경 제안, 실제 수정 없이 계획 작성"을 위한 에이전트로 설명합니다. 그래도 구현을 요구하면 거절합니다. 이 거부가 기능이 정상 작동 중이라는 증거입니다.
모델을 바꾼 뒤 배지는 Plan · GLM-5.2 OpenCode Go — Plan은 Build와 별개의 자체 모델을 씁니다.1:35에 보기 - 3
Tab으로 에이전트 전환하기
Tab을 누르면 Plan → Build → Plan으로 순환하고, Shift+Tab은 반대 방향입니다. 이것이 agent_cycle 키바인드이자 전환의 전부 — 대화 중간에 에이전트·모델·권한이 함께 바뀝니다. 메뉴가 편하면 ctrl+x a로 에이전트 목록, ctrl+p로 커맨드 팔레트를 열고, opencode --agent plan으로 셸에서 곧바로 플랜 모드로 시작할 수도 있습니다.
파트 2 — 읽기 전용으로 작업 계획하기
- 4
프로바이더를 연결해 모델 목록 채우기
새로 설치하면 프로바이더를 연결하기 전까지 모델 목록이 비어 있습니다. /connect를 실행하거나 모델 피커 하단의 Connect provider를 골라 권장 저가 구독인 OpenCode Zen을 선택하거나, Groq·GitHub Copilot·Anthropic·Google의 API 키를 가져오세요. Big Pickle이나 MiMo V2.5 Free 같은 무료 모델이면 이 가이드를 따라가기 충분합니다.
Connect a provider 대화상자: OpenCode Zen 권장, 아래에 Groq·GitHub Copilot·Anthropic·Google.3:05에 보기 - 5
모드마다 자기 모델 주기
플랜 모드에서 /models를 실행해 계획용 강한 모델을 고르세요 — 계획 품질이 이후 모든 것을 결정합니다. 그다음 Tab을 누르고 /models를 다시 실행해 더 저렴한 빌더를 지정하세요. 영상은 Plan에 GLM-5.2, Build에 MiMo V2.5 Free를 짝지었습니다. 이 조합을 고정하려면 opencode.json에 agent.model을 설정합니다.
Free 태그가 붙은 Zen 모델의 Select model 대화상자 — Recent 목록 덕분에 두 번 전환도 몇 초짜리 일입니다.1:13에 보기 - 6
작업을 보내고 에이전트의 질문에 답하기
플랜 모드에서는 단계가 아니라 결과를 묘사하세요 — 영상은 plain HTML 프로젝트에 Tailwind CSS 설치를 요청합니다. Plan 에이전트는 리포를 읽기 전용으로 조사한 뒤 선택형 대화상자를 돌려줍니다: CDN script 태그, npm 설치, 독립 실행 바이너리, 또는 직접 입력. 화살표 키로 고르고, 마땅한 옵션이 없으면 자유 입력도 됩니다.
Plan 에이전트의 명확화 대화상자 — 네 가지 옵션에 커스텀 답변용 탈출구까지, 그리고 아직 파일은 하나도 안 만졌습니다.3:00에 보기 - 7
계획 읽기: 검증과 트레이드오프
완성된 계획은 diff가 아니라 문서입니다: 현재 상태, 결정 사항, 검증 체크리스트, 트레이드오프 섹션 — 영상의 계획은 Play CDN이 인터넷이 필요하고 프로덕션용이 아니라고 명시합니다. 아직 수정된 것은 없으며, 지금 읽는 항목들은 승인 후 Build가 할 일을 설명합니다.
계획의 검증 체크리스트와 트레이드오프 섹션 — 비용은 솔직하게 적혀 있고, 수정은 여전히 0건.4:58에 보기 - 8
승인하면 OpenCode가 Build에 넘깁니다
계획은 인계 질문으로 끝납니다: 플랜 모드를 나가면 이 계획을 실행할까요, 아니면 먼저 조정할까요? 승인해도 아직 아무것도 편집되지 않습니다 — 에이전트를 바꿀 때까지 Plan은 읽기 전용입니다. 상태 표시줄은 여전히 Plan. Tab을 누르는 순간 같은 대화가 전체 파일 접근 권한과 함께 Build에서 이어집니다.
전체 계획과 그 아래 승인 질문, 그리고 상태 표시줄에 나란히 보이는 Plan·Build 배지.5:10에 보기
파트 3 — Build로 갈아타고 이어가기
- 9
Tab으로 Build로 바꾸고 구현시키기
Tab을 누르면 배지가 Build · MiMo V2.5 Free로 뒤집힙니다. 그리고 "구현해"라고 말하세요. Build에는 모든 도구가 있습니다: index.html을 편집하고, Tailwind 설정을 쓰고, 진행이 눈에 보이는 todo 목록을 하나씩 지워 나갑니다. 같은 명령을 플랜 모드에서 하면 OpenCode는 거절합니다. todo 목록과 편집은 오직 Build 쪽에만 나타납니다.
Tab 이후 배지는 Build · MiMo V2.5 Free, 구현이 시작되자 Todos 목록이 나타납니다.5:20에 보기 - 10
세션 관리하기
ctrl+x l을 누르면 세션 목록이 열립니다: 이름과 날짜가 붙은 대화들, ctrl+r로 이름 바꾸기, 자주 돌아올 것은 고정. 세션은 프로젝트가 아니라 OpenCode의 전역 폴더에 저장되므로 재시작에도 살아남습니다 — 영상에서는 잡담용 채팅과 Tailwind 세션을 오가도 컨텍스트가 하나도 빠지지 않습니다.
Sessions 대화상자 — 이름·날짜가 붙은 대화 목록에 고정·삭제·이름 바꾸기가 키 한 번 거리에.9:05에 보기 - 11
창과 버튼이 좋다면? 데스크톱은 베타
opencode.ai는 터미널과 함께 macOS·Windows·Linux용 데스크톱 앱 베타를 알리고 있습니다. 이 가이드의 Tab·배지 흐름은 TUI의 것이고 데스크톱 베타는 더 어린 소프트웨어입니다. 플랜 모드가 다르게 보이거나 없다면 앱을 업데이트하거나, 동작이 문서화된 터미널에서 opencode를 실행하세요.
opencode.ai의 배너: 데스크톱 앱이 macOS·Windows·Linux용 베타로 제공 — 기준은 여전히 터미널입니다.1:10에 보기
OpenCode 플랜 모드 vs 빌드 모드
둘 다 하나의 대화를 공유하는 기본 에이전트입니다. 달라지는 것은 각자 허용된 행동과 응답하는 모델. 중요한 차이:
- 1수정 권한: Build는 모든 도구를 활성화하고, Plan은 파일 편집이 기본 거부 또는 승인 요구, bash도 먼저 확인합니다. 이는 앱 계층의 권한 강제이지 모델이 스스로 설득해 무시할 수 있는 온정적인 지시가 아닙니다.
- 2모드별 모델: /models는 활성 에이전트에만 적용되므로 Plan에는 강한 추론 모델, Build에는 빠른 무료 모델 — 영상에서는 GLM-5.2와 MiMo V2.5 Free. opencode.json의 agent.model로 고정됩니다.
- 3출력의 형태: Plan은 조사 요약·명확화 질문·검증 단계와 트레이드오프가 담긴 계획 문서로 답하고, Build는 편집·생성된 파일·todo 목록으로 답합니다.
- 4전환 비용: Tab 한 번, 대화 중간에 적용, Shift+Tab으로 되돌림. 상태 표시줄 배지가 항상 활성 에이전트를 알려주므로 "플랜 모드가 안 먹는다"는 순간은 대개 배지가 조용히 Build를 가리키고 있을 때입니다.
- 5실패 동작: Plan에게 구현을 요구하면 거절하고 계획을 다시 제시하고, Build에게 요구하면 즉시 편집합니다. 변경이 필요하면 먼저 Tab — 절차 전체가 그게 다입니다.
- 6확장성: 둘 다 내장 기본 에이전트이며, opencode.json이나 .opencode/agents/*.md에 정의한 커스텀 에이전트도 같은 Tab 순환에 합류하므로 리뷰 전용·계획 전용 변형을 직접 만들 수 있습니다.
Claude Code의 플랜 모드와 비교하면: 발상은 같고 조작이 다릅니다. Claude Code는 Shift+Tab을 plan mode 표시가 나올 때까지 누르고 승인 전까지 편집을 잠급니다. OpenCode의 신호는 상태 표시줄 배지이며, 에이전트별 모델 분리는 부수적이 아니라 명시적인 설정입니다.
OpenCode 플랜 모드가 사라졌거나 안 될 때
"plan mode not working" 검색의 대부분은 다음 중 하나로 귀결됩니다 — 포럼을 헤맬 필요가 없습니다:
- 1CLI가 낡았습니다. 에이전트 순환과 에이전트별 모델은 비교적 최신 기능입니다. Tab을 눌러도 Plan 배지가 안 보이면 opencode --version을 확인하고 curl -fsSL https://opencode.ai/install | bash로 재설치하세요.
- 2메뉴 항목을 찾고 있습니다. 플랜 모드에는 설정 화면이 없습니다 — 상태 표시줄의 배지가 전부입니다. 배지가 Build라면 빌드 모드에 있는 것. Tab 한 번이면 뒤집힙니다.
- 3Tab이 반응 없음. 터미널이 Tab을 삼켰을 수 있습니다. 대신 ctrl+x a(에이전트 목록)나 ctrl+p(커맨드 팔레트)를 쓰고, tui.json의 agent_cycle을 터미널이 가로채지 않는 키로 재설정하세요.
- 4데스크톱 베타를 쓰고 있습니다. 문서화된 Tab 흐름은 터미널 것이고, macOS·Windows·Linux용 데스크톱 앱은 더 어린 베타입니다. 업데이트하거나 터미널에서 opencode를 실행하세요.
- 5커스텀 에이전트가 순환을 바꿨습니다. opencode.json이나 .opencode/agents/에 정의한 에이전트도 기본 에이전트가 되어 Tab 순환에 합류합니다 — Plan이 한 번 더 멀어졌거나 설정이 기본값 이름을 바꿨을 수 있습니다.
- 6재개 후 혼란. opencode -c는 마지막 대화를 다시 열고, 배지는 지금 활성인 에이전트를 보여줍니다. 재개 후 상태 표시줄을 훑어보세요. 의외라면 Tab 한 번으로 해결됩니다.
깨지지 않는 것: 모델 선택. Plan의 읽기 전용 동작은 권한 설정에서 오므로 연결된 어떤 모델로도 안전하게 계획할 수 있습니다 — 약한 모델은 그저 계획을 잘 못할 뿐. 배지가 Plan인데 파일을 고쳤다면 신고할 버그지만, 실제로는 배지를 먼저 보세요. 거의 항상 Build입니다.