터미널에서 도는 AI 코딩 에이전트는 이제 흔해졌지만, 그중 특정 회사의 모델에 묶이지 않는 오픈소스 도구를 찾는다면 선택지는 좁아진다. OpenCode는 바로 그 자리를 차지한 도구다. GitHub 스타 20만 개를 넘긴, 오픈소스 터미널 AI 코딩 에이전트 중 가장 널리 쓰이는 프로젝트다. 핵심은 provider 중립성이다. Anthropic·OpenAI·Google은 물론 Ollama로 돌리는 로컬 모델까지 설정 파일 한 줄로 갈아 끼운다. 이번 포스팅에서는 OpenCode 사용법을 설치부터 모델 설정, plan/build 모드, AGENTS.md, MCP·LSP 연결, 그리고 2026년 초 Anthropic이 서드파티 도구의 Claude 접근을 막으면서 생긴 실무 함정과 그 우회까지 실제 opencode.json과 명령어로 정리하고자 한다.
OpenCode가 오픈소스 코딩 에이전트 1위가 된 이유
OpenCode는 터미널 안에서 도는 provider 중립 AI 코딩 에이전트다. 도구 실행 루프, LSP 통합, 세션 관리, plan/build 모드, 서브에이전트를 갖춘 완전한 agent harness이며, 터미널 TUI·데스크톱 앱·IDE 확장으로 제공된다. 다른 도구와 갈리는 결정적 지점은 하나다. Claude Code가 Anthropic 모델에 묶이는 것과 달리, OpenCode는 75개 이상의 LLM provider를 설정 파일 하나로 바꿔 쓴다.
그래서 “특정 벤더에 종속되기 싫다”는 개발자에게 기본값이 된다. 같은 TUI·같은 워크플로를 유지한 채, 오늘은 Claude로 짜다가 내일은 Gemini나 로컬 Ollama 모델로 갈아탈 수 있다. 공식 문서에 따르면 build(전체 접근)와 plan(읽기 전용) 두 내장 에이전트를 기본 제공하고, Tab 키로 둘을 오간다. 이 provider 중립성과 오픈소스라는 조합이 20만 스타의 배경이다.
OpenCode를 한마디로 줄이면 터미널에서 도는, 벤더에 묶이지 않은 오픈소스 에이전트다. 이 글의 나머지는 그걸 실제 명령어로 어떻게 누리는지 다룬다. 터미널에서 여러 에이전트를 병렬로 굴리는 큰 그림이 궁금하다면 cmux 사용법이나 herdr 사용법 글과 함께 보면 맥락이 잡힌다.
설치부터 첫 실행까지 — 문자 그대로 30초
OpenCode 설치는 셸 스크립트 한 줄이면 끝난다. macOS·Linux·Windows 모두 지원하고, 패키지 매니저를 쓰면 업데이트 관리까지 자동이다. 설치 후 프로젝트 디렉터리에서 opencode만 치면 TUI가 뜬다. 첫 실행에서는 모델 provider부터 연결해야 한다.
# 방법 1: 공식 설치 스크립트 (가장 간단)
curl -fsSL https://opencode.ai/install | bash
# 방법 2: npm (Node.js 환경)
npm i -g opencode-ai@latest
# 방법 3: Homebrew (macOS)
brew install anomalyco/tap/opencode세 방법 모두 동일한 단일 바이너리를 설치한다. Node 환경이 이미 있으면 npm i -g opencode-ai@latest가 버전 고정·업데이트에 편하고, 그 외에는 설치 스크립트가 가장 마찰이 적다. Windows는 Scoop·Chocolatey·mise도 지원하므로 평소 쓰던 매니저를 그대로 쓰면 된다. 설치 명령어의 최신 목록은 공식 설치 문서에서 확인할 수 있다.
# 작업할 프로젝트 루트로 이동해서 실행
cd ~/projects/my-app
opencodeopencode를 실행하면 TUI가 뜨는데, 처음이라면 아직 연결된 모델이 없다. 이때 TUI 안에서 /connect를 입력해 provider를 고르고 자격 증명(API 키 등)을 등록한다. 연결이 끝나면 /models로 실제 사용할 모델을 선택한다. 이 두 명령이 OpenCode 사용법의 사실상 첫 관문이다.
/connect # provider 선택 + API 키/자격 증명 등록
/models # 사용할 모델 선택 (provider/model 목록에서 고름)
/init # 프로젝트를 분석해 AGENTS.md 생성 (권장 첫 단계)/init은 현재 프로젝트를 훑어 구조·규칙을 요약한 AGENTS.md를 만든다. 이 파일이 이후 모든 대화의 밑컨텍스트가 되므로, 새 프로젝트에서 OpenCode를 처음 붙일 때 가장 먼저 실행하길 권한다. 생성된 AGENTS.md는 Git에 커밋해 팀이 공유하는 것이 공식 권장 방식이다.
모델을 내 맘대로 — provider 75개를 opencode.json 한 파일로
OpenCode의 진짜 무기는 모델 설정이다. 설정 파일 opencode.json에 model 키를 provider_id/model_id 형식으로 적으면 기본 모델이 정해지고, provider별 세부 옵션까지 같은 파일에서 조정한다. 전역 설정은 ~/.config/opencode/opencode.json, 프로젝트별 설정은 프로젝트 루트의 opencode.json에 둔다. 프로젝트 설정이 전역을 덮어쓰므로 저장소마다 다른 모델을 쓸 수 있다.
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-4-5",
"small_model": "anthropic/claude-haiku-4-5"
}model은 메인 작업에 쓰는 모델, small_model은 제목 생성·요약 같은 가벼운 작업에 쓰는 보조 모델이다. 형식은 항상 provider/model이라, 앞의 provider id만 바꾸면 그대로 다른 회사 모델로 넘어간다. 모델을 코드로 박아두지 않고 TUI에서 즉석으로 바꾸려면 /models를 쓰면 된다. 이 설정 규칙은 공식 모델 문서에 정의돼 있다.
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"openai": {
"models": {
"gpt-5": {
"options": { "reasoningEffort": "high", "textVerbosity": "low" }
}
}
},
"anthropic": {
"models": {
"claude-sonnet-4-5-20250929": {
"options": { "thinking": { "type": "enabled", "budgetTokens": 16000 } }
}
}
}
}
}provider 블록에서는 모델별 세부 옵션을 준다. 위 예시는 OpenAI 모델의 추론 강도(reasoningEffort)와 출력 장황함(textVerbosity)을 조절하고, Anthropic 모델에는 확장 사고(extended thinking)의 토큰 예산(budgetTokens)을 16000으로 켠다. 이렇게 provider마다 다른 다이얼을 한 파일에서 관리한다는 점이 OpenCode를 여러 provider 사이에서 자유롭게 만드는 핵심이다.
특정 provider를 아예 목록에서 숨기거나 제한하고 싶다면 최상위 disabled_providers·enabled_providers 배열을 쓴다. 예컨대 "enabled_providers": ["anthropic"]로 두면 /models 목록이 Anthropic 모델만 남아, 실수로 다른 API에 과금되는 사고를 막는다.
plan과 build — 두 모드로 안전하게 굴리기
OpenCode는 build와 plan 두 모드로 나뉘고, Tab 키로 즉시 전환한다. build는 파일 수정·명령 실행까지 하는 전체 접근 모드, plan은 변경을 막고 “어떻게 구현할지”만 제안하는 읽기 전용 모드다. 낯선 코드베이스나 위험한 리팩터링을 앞두고 plan으로 계획을 먼저 받아본 뒤 build로 넘어가는 흐름이 안전하다.
여기에 더해 permission 설정으로 위험한 동작마다 확인을 받게 만들 수 있다. 아래처럼 파일 편집과 셸 실행을 ask로 두면, 에이전트가 그 동작을 하기 직전에 사람에게 승인을 묻는다.
{
"$schema": "https://opencode.ai/config.json",
"permission": { "edit": "ask", "bash": "ask" },
"default_agent": "plan"
}permission.edit와 permission.bash를 ask로 설정하면 에이전트가 마음대로 파일을 고치거나 명령을 실행하지 못하고 매번 물어본다. default_agent를 plan으로 두면 OpenCode가 처음 뜰 때 항상 읽기 전용으로 시작하므로, “일단 계획부터”라는 습관을 도구 차원에서 강제할 수 있다. 여러 에이전트를 동시에 굴릴수록 이 안전장치가 고마워진다. 병렬 실행 관점의 논의는 Orca vs cmux 비교 글에서 따로 다뤘다.
실무에서는 plan으로 받은 계획을 그대로 build에 넘기기보다, 계획의 위험한 부분(마이그레이션, 대량 삭제)을 사람이 먼저 걸러낸 뒤 build로 실행하는 편이 사고를 줄인다. 모드 전환이 Tab 한 번이라 이 왕복 비용이 거의 없다는 게 OpenCode의 실용적 장점이다.
AGENTS.md와 커스텀 에이전트 — 프로젝트 맥락을 코드처럼 관리
OpenCode에서 프로젝트 맥락은 AGENTS.md 파일로 관리한다. /init이 자동 생성하는 이 파일에는 프로젝트 구조·컨벤션·주의사항이 담기고, 모든 대화에 기본 컨텍스트로 주입된다. Git에 커밋해두면 팀 전체가 같은 규칙 위에서 에이전트를 쓰게 된다. 여기에 더해, 특정 역할에 특화된 커스텀 에이전트를 opencode.json의 agent 블록으로 직접 정의할 수 있다.
{
"$schema": "https://opencode.ai/config.json",
"agent": {
"code-reviewer": {
"description": "PR 코드를 리뷰한다",
"model": "anthropic/claude-sonnet-4-5"
}
},
"subagent_depth": 2,
"instructions": ["AGENTS.md", "CONTRIBUTING.md"]
}agent 아래에 이름을 키로 두고 역할(description)과 사용할 모델을 지정하면, 그 역할만 담당하는 서브에이전트가 만들어진다. 위 예시의 code-reviewer처럼 리뷰 전용 에이전트를 두면, 메인 에이전트가 코드를 짜고 별도 에이전트가 그 결과를 검토하는 분업이 가능하다. subagent_depth는 서브에이전트가 다시 서브에이전트를 부를 수 있는 깊이, instructions는 컨텍스트로 항상 읽을 파일 목록이다.
기본 제공되는 general 서브에이전트는 복잡한 검색을 대신 수행하고, 메인 대화에서 @general 문법으로 호출한다. 규모가 큰 코드베이스에서 “이 함수 어디서 쓰이지” 같은 탐색을 여기에 떼어내면, 메인 대화의 컨텍스트를 깨끗하게 유지할 수 있다.
MCP와 LSP 붙이기 — 에이전트에게 도구와 눈을 달다
OpenCode는 MCP(Model Context Protocol) 서버와 LSP(Language Server Protocol)를 붙여 능력을 확장한다. MCP로는 외부 도구·데이터 소스를 에이전트의 도구로 연결하고, LSP로는 컴파일러 수준의 실시간 진단을 받는다. 둘 다 opencode.json에서 선언한다. MCP 서버는 로컬(stdio)과 원격(HTTP) 두 종류를 지원한다.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-local-mcp-server": {
"type": "local",
"command": ["npx", "-y", "my-mcp-command"],
"enabled": true,
"environment": { "MY_ENV_VAR": "my_env_var_value" }
},
"my-remote-mcp": {
"type": "remote",
"url": "https://my-mcp-server.com",
"enabled": true,
"headers": { "Authorization": "Bearer MY_API_KEY" }
}
},
"lsp": true
}로컬 MCP 서버는 type: "local"에 실행할 명령을 배열(command)로 주고, 필요하면 environment로 환경 변수를 넘긴다. 원격 서버는 type: "remote"에 url과 인증용 headers를 준다. 두 경우 모두 enabled로 개별 on/off가 가능해, 프로젝트마다 필요한 도구만 켤 수 있다. 자세한 스키마는 공식 MCP 문서에 있다. MCP 개념 자체가 낯설다면 MCP 실전 가이드를 먼저 읽는 편이 좋다.
lsp: true는 언어 서버 통합을 켜는 스위치다. 이걸 켜면 에이전트가 코드를 고친 직후 타입 오류·미사용 심볼 같은 진단을 실시간으로 받아, 잘못된 수정을 스스로 알아채고 고친다. “에이전트가 컴파일도 안 되는 코드를 자신 있게 내놓는” 흔한 문제를 줄여주는 장치라, 정적 타입 언어 프로젝트에서 특히 효과가 크다.
되돌리기와 공유 — 에이전트가 저질러도 안전한 곳이 있다
OpenCode는 스냅샷과 undo/redo로 에이전트의 실수를 되돌린다. AI에게 파일을 통째로 맡길 때 가장 무서운 게 잘못 건드린 걸 못 되돌리는 상황인데, OpenCode는 작업 단위마다 스냅샷을 남긴다. TUI에서 /undo로 직전 변경을 되돌리고 /redo로 다시 적용하며, snapshot 설정이 기본으로 켜져 있어 별도 준비 없이 동작한다.
{
"$schema": "https://opencode.ai/config.json",
"snapshot": true,
"share": "manual"
}snapshot: true는 에이전트가 변경을 가할 때마다 되돌아갈 지점을 남긴다. 덕분에 build 모드에서 에이전트가 여러 파일을 한꺼번에 고쳐도, 결과가 마음에 안 들면 /undo로 통째로 물릴 수 있다. Git 커밋과 별개로 도구 자체가 안전망을 제공하는 셈이라, plan으로 계획을 검토하고 build로 실행한 뒤 어긋나면 되돌리는 왕복이 부담 없다.
share는 대화를 링크로 공유하는 기능이다. /share를 입력하면 현재 세션을 공유 가능한 URL로 만들어, 동료에게 이 에이전트가 이렇게 풀었다는 과정을 그대로 보여줄 수 있다. 기본값을 manual로 두면 명시적으로 요청할 때만 공유되므로, 민감한 코드가 실수로 링크화되는 일을 막는다. 대화가 길어져 컨텍스트가 불어나면 OpenCode가 이전 내용을 압축(compaction)해 토큰을 관리하므로, 긴 세션에서도 비용이 무한정 늘지 않는다.
OpenCode vs Claude Code vs aider — 언제 뭘 쓰나
OpenCode·Claude Code·aider는 모두 터미널 AI 코딩 에이전트지만 지향점이 다르다. OpenCode는 provider 중립과 오픈소스, Claude Code는 Anthropic 모델에 최적화된 관리형 경험, aider는 Git 커밋 중심의 가벼운 페어프로그래밍에 강하다. 벤더에 묶이기 싫거나 로컬 모델을 쓸 계획이면 OpenCode 쪽이 맞고, 이미 Claude 구독으로 굴러가는 팀이라면 Claude Code의 통합이 더 손에 붙는다.
| 항목 | OpenCode | Claude Code | aider |
|---|---|---|---|
| 모델 provider | 75개+ (중립) | Anthropic 전용 | 다수 지원 |
| 오픈소스 | 예 | 아니오 | 예 |
| 인터페이스 | TUI·데스크톱·IDE | TUI·IDE | CLI |
| plan/build 모드 | 내장 (Tab 전환) | plan 모드 있음 | 별도 |
| LSP 통합 | 내장 | 제한적 | 없음 |
| Git 통합 | 스냅샷·undo | 있음 | 커밋 중심(강점) |
| 로컬 모델(Ollama) | 설정으로 지원 | 우회 필요 | 지원 |
표에서 보듯 OpenCode의 차별점은 provider 폭과 LSP 내장이다. 반대로 “Git 커밋 단위로 딱딱 끊어 작업”하는 습관에는 aider가 더 잘 맞는다. 세 도구를 꼭 하나만 골라 쓸 필요도 없다. 터미널 계층별 선택은 터미널 도구 비교 가이드에 정리해뒀고, aider의 Git 워크플로는 aider 사용법에서 따로 다뤘다.
실무에서 진짜 막히는 지점 — Anthropic의 Claude 차단과 우회
OpenCode를 Claude로 쓰려다 막히는 사람이 많은데, 이유가 있다. 2026년 1월 Anthropic은 OpenCode를 포함한 서드파티 도구가 구독(OAuth) 방식으로 Claude 모델에 접근하는 것을 차단했고, 4월 4일부터는 Claude Pro·Max·Team 구독이 서드파티 도구 사용을 더 이상 커버하지 않도록 못박았다. “Claude 구독이 있으니 OpenCode에서도 공짜로 되겠지”가 더는 통하지 않는다는 뜻이다.
우회는 세 갈래다. 첫째는 정공법인 Anthropic API 키(종량제)를 직접 발급받아 쓰는 방법이다. 이건 약관에 완전히 부합한다. /connect에서 Anthropic을 고르고 API 키를 등록하면 그대로 Claude 모델이 열린다. 둘째는 구독을 로컬 엔드포인트로 브리지하는 프록시 도구인데, 이는 갱신된 약관 위반이라 계정 정지 위험이 있어 권하지 않는다.
셋째이자 OpenCode의 정체성을 가장 잘 살리는 길은 아예 다른 provider로 갈아타는 것이다. provider 중립 설계 덕에 모델 한 줄만 바꾸면 된다. 비용이 걱정이면 로컬 Ollama 모델이 답이다.
Ollama는 OpenCode가 대신 깔아주지 않는다. ollama/… 모델을 쓰려면 먼저 Ollama를 설치하고, 쓸 모델을 받아(pull) 서버를 띄워둬야 한다. OpenCode는 그 로컬 서버에 연결만 할 뿐이다.
# 1) Ollama 설치 (macOS 예시)
brew install ollama
# 2) 코드 특화 모델 받기 (수 GB 다운로드)
ollama pull qwen2.5-coder:14b
# 3) Ollama 서버 실행 (localhost:11434에서 서빙)
ollama serveOllama를 설치하면 ollama pull로 모델 가중치를 로컬에 내려받고, ollama serve가 localhost:11434에서 그 모델을 서빙한다. 이 서버가 떠 있어야 OpenCode의 ollama/… 설정이 실제로 붙는다. 주의할 점은 하드웨어다. 로컬 모델은 내 컴퓨터 자원으로 추론하므로 14B급이면 대략 10GB 이상의 메모리가 필요하고, 사양이 부족하면 qwen2.5-coder:7b 같은 더 작은 모델을 받아야 한다. 준비가 끝났으면 opencode.json은 이렇게 가리키기만 하면 된다.
{
"$schema": "https://opencode.ai/config.json",
"model": "ollama/qwen2.5-coder:14b"
}위처럼 model을 Ollama가 서빙하는 로컬 모델로 지정하면, 외부 API 없이 완전히 오프라인으로 돈다. 과금도 약관 문제도 없다. 2026년 1월 Ollama가 Anthropic Messages API 호환을 추가하면서 로컬 모델을 코딩 에이전트에 붙이기가 훨씬 쉬워졌다. 성능이 더 필요하면 Gemini나 DeepSeek 같은 저비용 provider로 옮기는 것도 같은 방식이다. provider를 언제든 갈아탈 수 있다는 이 점이, 벤더 정책이 또 한 번 바뀌어도 워크플로가 흔들리지 않게 해주는 가장 큰 보험이다.
OpenAI(Codex)도 같은 함정 — 구독이 아니라 API 키
OpenAI 모델(GPT·Codex)도 사정은 비슷하다. OpenCode 같은 서드파티 도구에서 정식으로 쓰는 길은 OpenAI API 키(종량제)를 /connect로 등록하는 것이다. 헷갈리기 쉬운 건 ChatGPT Plus·Pro 구독과 OpenAI API가 별개의 지갑이라는 점이다. 구독료에는 API 크레딧이 포함되지 않는다.
ChatGPT 구독 로그인은 원래 OpenAI 자기 제품(ChatGPT, 공식 Codex CLI)을 위한 것이다. 그 구독 인증을 OpenCode에 물려 쓰는 커뮤니티 플러그인이 있긴 하지만, 이는 공식 클라이언트의 OAuth를 제3자 도구가 흉내 내는 방식이라 Anthropic이 막은 것과 같은 회색지대다. 언제 막혀도 이상하지 않고 계정 리스크도 있다. 이미 ChatGPT 구독을 쓰고 그걸 그대로 활용하고 싶다면, OpenCode 대신 OpenAI 공식 Codex CLI를 쓰는 편이 정식 경로다.
그래서 이미 특정 벤더의 구독을 쓰고 있다면 한 번 따져볼 게 있다. 그 구독 하나를 그대로 싸게 쓰는 게 목적이라면, OpenCode에서 같은 벤더를 API로 붙이는 건 구독료에 종량 요금을 더 얹는 이중 지출이라 실익이 크지 않다. 그 경우엔 벤더의 1st-party 도구(Claude Code·공식 Codex CLI)가 낫다. OpenCode가 값어치를 하는 지점은 구독 재활용이 아니라 락인 회피, 모델 믹스, 그리고 토큰 비용이 0인 로컬 Ollama다. 구독자가 실제로 돈을 아끼는 길은 루틴한 작업을 로컬 모델에 떠넘겨 구독·API 한도를 어려운 작업에 아끼는 쪽이다.
한 파일로 몰아보기 — opencode.json 총정리
지금까지 흩어져 나온 설정을 하나로 모으면 이렇게 된다. 아래는 모델·provider 옵션·권한·커스텀 에이전트·MCP·LSP·스냅샷까지 이 글에서 다룬 항목을 한 opencode.json에 담은 예시다. 필요 없는 블록은 빼면 된다.
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-4-5",
"small_model": "anthropic/claude-haiku-4-5",
"provider": {
"anthropic": {
"models": {
"claude-sonnet-4-5": {
"options": { "thinking": { "type": "enabled", "budgetTokens": 16000 } }
}
}
}
},
"default_agent": "plan",
"permission": { "edit": "ask", "bash": "ask" },
"agent": {
"code-reviewer": {
"description": "PR 코드를 리뷰한다",
"model": "anthropic/claude-sonnet-4-5"
}
},
"subagent_depth": 2,
"instructions": ["AGENTS.md"],
"mcp": {
"my-tools": {
"type": "local",
"command": ["npx", "-y", "my-mcp-command"],
"enabled": true
}
},
"lsp": true,
"snapshot": true,
"share": "manual",
"enabled_providers": ["anthropic", "ollama"]
}위 설정은 메인 모델과 보조 모델을 Anthropic으로 두되, default_agent를 plan으로 시작하고 편집·셸 실행에 확인을 받도록(permission) 안전장치를 건 구성이다. 리뷰 전용 서브에이전트를 하나 두고, MCP 도구와 LSP·스냅샷·수동 공유를 켰다. 완전히 로컬로 돌리고 싶으면 맨 위 model만 "ollama/qwen2.5-coder:14b"로 바꾸면 된다. 나머지 구조는 그대로다. enabled_providers로 노출 provider를 좁혀두면 실수로 다른 API에 과금되는 것도 막는다.
FAQ
OpenCode는 Claude Code와 뭐가 다른가?
가장 큰 차이는 모델 provider의 폭이다. OpenCode는 75개 이상의 provider를 설정 파일로 바꿔 쓰는 오픈소스 도구이고, Claude Code는 Anthropic 모델에 맞춰 다듬어진 비공개 도구다. 로컬 모델이나 여러 provider를 오갈 일이 있으면 OpenCode가 유리하고, 그럴 일이 없다면 Claude Code도 충분히 편하다.
OpenCode에서 Claude 구독(Pro/Max)을 그대로 쓸 수 있나?
쓸 수 없다. 2026년 1월부터 Anthropic이 서드파티 도구의 구독 기반 Claude 접근을 차단했고 4월에 강제됐다. OpenCode에서 Claude 모델을 쓰려면 Anthropic API 키(종량제)를 발급받아 /connect로 등록해야 하며, 이 방식은 약관에 부합한다. 구독을 우회하는 프록시는 약관 위반이라 권하지 않는다.
로컬 모델만으로 OpenCode를 쓸 수 있나?
가능하다. Ollama로 모델을 서빙하고 opencode.json의 model을 ollama/모델명 형식으로 지정하면 외부 API 없이 오프라인으로 동작한다. 과금과 약관 문제가 없어, 비용이 부담되거나 폐쇄망에서 작업할 때 특히 유용하다. 다만 로컬 모델은 하드웨어 성능에 좌우되므로, 코드 특화 모델(예: qwen2.5-coder 계열)을 고르는 편이 결과가 낫다.
opencode.json은 어디에 둬야 하나?
두 곳에 둘 수 있다. 전역 설정은 ~/.config/opencode/opencode.json, 프로젝트별 설정은 프로젝트 루트의 opencode.json이다. 프로젝트 설정이 전역 설정을 덮어쓰므로, 공통 기본값은 전역에 두고 저장소마다 다른 모델·MCP·권한은 프로젝트 파일에서 조정하는 구성이 깔끔하다.
plan 모드와 build 모드는 어떻게 전환하나?
TUI에서 Tab 키로 즉시 전환한다. plan은 변경을 막고 구현 방법만 제안하는 읽기 전용 모드, build는 파일 수정·명령 실행까지 하는 전체 접근 모드다. opencode.json의 default_agent를 plan으로 두면 항상 계획 모드로 시작하게 만들 수 있어, 위험한 작업 전 습관적으로 계획을 먼저 받게 된다.
마치며
여러 코딩 에이전트를 옮겨 다니며 느낀 건, 결국 발목을 잡는 게 성능이 아니라 벤더 정책이라는 점이었다. 잘 쓰던 도구가 어느 날 모델 접근이 막히면 워크플로 전체가 흔들린다. OpenCode를 곁에 두는 이유가 여기에 있다. 모델이 막히면 그저 model 한 줄을 바꿔 Gemini나 로컬 Ollama로 넘어가면 되고, TUI도 단축키도 그대로다. 화려한 기능보다 이 “갈아탈 수 있음”이 실무에서 가장 오래 남는 가치였다. 처음이라면 /init으로 AGENTS.md부터 만들고, plan 모드로 며칠 써보며 이 도구가 손에 맞는지부터 확인해보길 권한다. 지금까지 OpenCode 사용법을 설치부터 provider 설정, 모드, 확장, 실무 함정까지 정리해 보았다.