실전 OpenCode CLI: 워크플로, 자동화 및 주의사항
명령줄에서 OpenCode를 실제로 사용해 보기
OpenCode의 커맨드 라인 인터페이스(CLI)는 스크립팅, CI 파이프라인, 그리고 무인 에이전트 실행을 위해 설계되었습니다. 이 글은 일상 업무에서 CLI를 활용하는 실무 가이드입니다.
CLI의 뒤에는 모델, 도구, 권한, 에이전트, 스킬, 커맨드, 세션, MCP 서버, 그리고 클라이언트/서버 아키텍처로 이루어진 시스템이 존재합니다. 에이전트는 프로젝트 파일을 읽고 수정할 수 있으며, 저장소를 검색하고, 셸 명령을 실행하고, 외부 도구를 호출하며, 작업을 서브에이전트에 위임할 수 있습니다. 동일한 환경은 TUI를 통해 인터랙티브하게 작동하거나, 스크립트를 통해 비인터랙티브하게 작동할 수 있습니다.
작은 작업을 수행하려면 몇 분 내에 설치하고, 모델을 연결한 후 질문을 시작할 수 있습니다. 하지만 진지한 작업을 수행할 때 경험의 질은 모델 선택, 저장소 지시사항, 권한 경계, 컨텍스트 관리, 그리고 에이전트가 얼마나 공격적으로 작동하도록 허용하느냐에 따라 크게 달라집니다. 이 글은 후자의 단계, 즉 커맨드 라인에서의 작업에 초점을 맞춥니다. 어떤 사용 사례가 수익을 가져오는지, 어떤 자동화 워크플로가 일상 사용에서 견디는지, 그리고 AI 기반 터미널의 신기함이 사라진 후에 어떤 문제가 나타나는지 살펴봅니다. 이 글은 이 사이트의 AI 개발 도구 섹션의 일부입니다.
여기서 언급된 관찰 사항들은 2026년 8월 OpenCode 1.18.9 버전과 최신 문서를 기준으로 확인되었습니다. OpenCode는 빠르게 변하므로, 장기간 유지되는 팀 설정에 예제를 복사하기 전에 간단한 문서 확인이 필요합니다. 아직 OpenCode를 설치하지 않았다면, OpenCode 빠른 시작에서 설치, 검증, 프로바이더 연결을 다룹니다.
OpenCode가 실제로 무엇인가: 에이전트 환경, 채팅 박스가 아님
OpenCode는 터미널을 중심으로 설계된 오픈소스 AI 코딩 에이전트입니다. OpenCode가 통합하는 것들의 단순화된 모습은 다음과 같습니다:
중요한 부분은 모델의 의도와 OpenCode가 수행할 수 있는 행동 사이의 권한 레이어입니다. 훌륭한 모델이라도 권한 설정이 나쁘면 위험할 수 있습니다. 약한 모델이라도 권한 설정이 완벽하면 단지 느리고 귀찮을 뿐입니다. 생산적인 OpenCode 사용은 양쪽 모두를 적절히 설정하는 것을 요구합니다.
동일한 환경은 인터랙티브 TUI와 비인터랙티브 커맨드 라인 모두를 지원합니다. 이것이 OpenCode를 순수한 채팅 인터페이스와 달리 스크립팅이 가능하게 만드는 이유입니다. 동일한 터미널 에이전트 아이디어에 대한 의도적으로 최소한의 접근 방식(기본 도구 4개, 내장 샌드박스 없음, 나머지는 확장으로)을 원한다면, Pi Coding Agent 리뷰가 유용한 대비가 됩니다.
설정: 설치, 연결, 그리고 프로바이더 독립성이 중요한 이유
OpenCode는 한 줄로 설치됩니다(공식 설치 스크립트, npm, 또는 Homebrew) — 저장소 디렉토리에서 opencode 명령으로 시작합니다. OpenCode 빠른 시작에서는 전체 설치 매트릭스(Arch, Windows, Docker), 검증, 프로바이더 연결(/connect 및 /models)을 다루므로, 이 글에서는 이를 반복하지 않습니다.
OpenCode 자체의 모델 서비스를 사용하거나 지원되는 외부 프로바이더를 연결할 수 있습니다. OpenCode는 현재 Models.dev를 사용하여 프로바이더 카탈로그의 대부분을 구성하며, 다양한 상업용 및 로컬 모델 구성을 지원합니다.
프로바이더 독립성은 OpenCode의 가장 유용한 아키텍처 결정 중 하나입니다. 코딩 워크플로가 하나의 모델 벤더에 영구적으로 결합될 필요가 없습니다. 어려운 아키텍처 작업에는 한 모델을, 저렴한 구현 작업에는 다른 모델을, 그리고 환경을 떠나서는 안 되는 코드에는 로컬 모델을 사용할 수 있습니다.
이러한 유연성은 실재하지만, 관리해야 할 또 다른 변수를 생성합니다. OpenCode가 잘 작동하지 않을 때, 문제는 하네스, 프롬프트, 사용 가능한 컨텍스트, 선택된 모델, 또는 이 네 가지 사이의 상호작용일 수 있습니다.
코드 요청 전에 AGENTS.md로 저장소 초기화하기
새 저장소에서 실행할 가치가 있는 첫 번째 명령 중 하나는 다음과 같습니다:
/init
OpenCode는 프로젝트를 분석하고 AGENTS.md 파일을 생성합니다. 이 파일을 커밋하세요.
AGENTS.md는 수동으로 반복하는 대신, 인터랙티브든 스크립트든 모든 대화에서 저장소特定的 제약 조건을 내구성 있는 컨텍스트로 만들 수 있는 곳입니다. 유용한 파일은 관련성을 유지할 만큼 짧으면서도 예측 가능한 실수를 방지할 만큼 구체적이어야 합니다. 예를 들어:
# Repository Instructions
## Architecture
- API handlers live under src/api.
- Business logic belongs under src/services.
- Database access belongs under src/repositories.
- Do not call database clients directly from HTTP handlers.
## Validation
After TypeScript changes run:
```bash
npm run typecheck
npm test
```
After frontend changes also run:
```bash
npm run lint
```
## Constraints
- Do not modify generated files.
- Do not change public API contracts without asking first.
- Do not create database migrations unless explicitly requested.
- Never run deployment commands.
또 다른 MCP 서버를 설치하는 것보다 덜 흥미진진해 보일 수 있지만, 보통 더 많은 가치를 제공합니다. 코딩 에이전트는 어떤 제약 조건이 중요한지 몰라서 놀라울 정도로 자주 실패합니다. 짧은 저장소 계약은 첫 번째 도구 호출 전에 이러한 모호성을 일부 제거합니다.
opencode run으로 커맨드 라인에서 작업하기
인터랙티브 인터페이스가 대부분의 관심을 받지만, OpenCode의 비인터랙티브 모드 유용한 워크플로의 범위를 상당히 변경합니다:
opencode run "Explain the error handling strategy in this package"
매번 TUI에 수동으로 입력하지 않고 셸 스크립트, CI 잡, Makefile, 태스크 러너, 또는 로컬 자동화를 통해 OpenCode를 사용할 수 있습니다. 예를 들어, 원샷 커맨드로 diff 리뷰를 수행하는 경우:
opencode run \
"Review the current git diff for correctness and missing tests. Do not edit files."
또는 컨텍스트를 run으로 직접 파이프할 수 있습니다:
git diff --name-only HEAD~1 |
opencode run "Inspect the changed files and identify risky behavior changes."
Makefile에서는 동일한 호출이 타겟이 됩니다:
.PHONY: review
review:
opencode run "Review the current git diff for correctness and missing tests. Do not edit files."
스크립트된 실행에는 프롬프트 앞에 사람이 없으므로, 구성한 권한 정책이 모델과 환경 사이에 서 있는 유일한 안전장치입니다. 이것이 자동화에서 인터랙티브 사용보다 아래 권한 섹션이 더 중요한 이유입니다.
여기서 흥미로운 방향은 결정론적 스크립트를 LLM으로 대체하는 것이 아닙니다. 전통적인 셸 로직이 어색해지는 곳에 모델 추론을 삽입하되, 그 주위에 결정론적 검증을 유지하는 것입니다.
최고의 OpenCode CLI 사용 사례
OpenCode는 거의 모든 프로그래밍 작업을 시도할 수 있지만, 그렇다고 모든 작업을 동일한 방식으로 위임해야 한다는 의미는 아닙니다. 가장 가치 높은 워크플로는 보통 세 가지 특성을 가집니다: 원하는 결과가 테스트 가능하고, 관련 저장소 컨텍스트를 발견할 수 있으며, 잘못된 변경 사항을 검사하거나 되돌리는 것이 비용이 적게 듭니다. 아래 각 프롬프트는 TUI에서나 opencode run의 인수로 작동합니다.
1. 저장소 탐색
OpenCode는 grep, 에디터 검색, 파일 점프, git log 명령의 시퀀스가 필요했던 질문을 답하는 데 탁월합니다. 예를 들어:
Explain how authentication works in this repository.
Trace a request from the HTTP middleware through token validation,
user loading, authorization, and the final handler.
Do not modify anything.
훌륭한 에이전트는 진입점을 검색하고, 참조를 추적하고, 테스트를 검사하여, 단순한 텍스트 검색보다 아키텍처 워크스루에 가까운 것을 반환합니다. 이는 에이전트가 코드를 작성하지 않아도 가치를 제공할 수 있으므로 기존 코드베이스에 OpenCode를 도입하는 가장 안전한 방법 중 하나입니다.
2. 작고 잘 정의된 수정
좁은 범위의 버그는 이상적인 코딩 에이전트 작업에 가깝습니다. 예를 들어:
The CLI exits with status 0 when config validation fails.
Find the code path responsible, add a regression test, implement
the smallest fix, and run the relevant tests.
Do not refactor unrelated code.
핵심 구절은 “버그를 고친다"가 아닙니다. 작업 주변의 제약 조건입니다. OpenCode는 테스트, 컴파일러, 또는 관찰 가능한 명령으로 성공을 입증할 수 있을 때 더 잘 작동합니다. 모호한 요구 사항은 모델이 입증 가능한 올바른 코드보다는 그럴듯한 코드를 생성할 공간을 제공합니다.
3. 구현 후 테스트 생성
테스트는 기존 구현이 OpenCode에게 추론할 수 있는 구체적인 것을 제공하기 때문에 유용한 에이전트 작업입니다. 생산적인 프롬프트는 다음과 같을 수 있습니다:
Review src/parser.ts and its existing tests.
Identify important edge cases that are currently uncovered.
Add tests only. Do not modify the implementation.
Run the parser test suite when finished.
테스트 생성을 구현과 분리하는 것은 중요합니다. 동일한 에이전트가 제약 조건 없이 한 번에 기능과 테스트를 모두 작성하면, 의도된 동작이 아니라 자신의 해석을 검증하는 테스트를 우연히 생성할 수 있습니다.
4. 기계적 리팩토링
OpenCode는 원하는 최종 상태가 명확한 반복적 변환에 매우 좋습니다. 예시는 다음과 같습니다:
- 저장소 전체에서 비추천되는 API 대체;
- 반복되는 코드를 공유 헬퍼로 변환;
- 설정 필드 이름 변경;
- 테스트를 하나의 어서션 패턴에서 다른 패턴으로 마이그레이션;
- 패키지 이동 후 import 업데이트;
- 구식 로깅 추상화 대체.
저장소의 컴파일러와 테스트가 에이전트의 피드백 루프가 됩니다. 유용한 패턴은 다음과 같습니다:
Replace uses of LegacyResult<T> with Result<T, AppError> in
packages/api only.
Preserve runtime behavior.
Work in small batches. After each batch run the package typecheck.
At the end run the package test suite and show me the final git diff
summary.
이것은 거대한 한 단계에서 전체 마이그레이션을 요청하는 것보다 종종 더 신뢰할 수 있습니다.
5. 코드 리뷰
리뷰를 동일한 편집 컨텍스트에 보내는 또 다른 프롬프트가 아니라, 별도의 에이전트 역할로 취급할 때 OpenCode는 훨씬 더 유용해집니다. 파일을 수정할 수 없는 리뷰 중심 에이전트를 생성할 수 있습니다. 그런 다음 다음과 같은 지시를 부여합니다:
Review the current git diff.
Focus on:
- correctness;
- security;
- concurrency;
- missing tests;
- error handling;
- accidental API changes.
Do not summarize files that are unchanged.
Rank findings by severity.
읽기 전용 리뷰어는 변경 사항을 생성한 다른 코딩 에이전트가 있더라도 유용합니다. 이러한 분리에는 가치가 있습니다. 구현과 비판은 다른 작업이기 때문입니다: 최근 수천 토큰을 사용하여 하나의 접근 방식을 방어해 온 에이전트는 새로운 리뷰어보다 그 접근 방식에 대해 덜 회의적일 가능성이 높습니다.
Plan 모드와 Build 모드를 다른 정신적 모드로 사용하기
OpenCode는 내장 워크플로에 계획 및 구현 중심의 동작을 포함하는 기본 에이전트와 서브에이전트를 제공합니다. 정확한 에이전트 구성이 시간에 따라 변하더라도, 개념적 분리는 여전히 유용합니다.
계획은 다음과 같은 질문에 답해야 합니다:
- 어떤 파일이 중요합니까?
- 어떤 기존 패턴을 따르야 합니까?
- 무엇이 깨질 수 있습니까?
- 변경 사항을 어떻게 검증할 것입니까?
- 요청된 변경 사항이 실제로 로컬입니까?
구현은 이러한 질문에 합리적인 답이 나온 후에만 이루어져야 합니다. 상당한 작업을 위한 경우, 다음과 같은 프롬프트 시퀀스를 선호합니다:
First investigate the request.
Do not edit files yet.
Return:
1. the relevant files;
2. the current behavior;
3. the proposed change;
4. risks;
5. the exact verification commands.
동일한 시퀀스는 원샷 커맨드로도 작동합니다:
opencode run "First investigate the request. Do not edit files yet. Return: the relevant files; the current behavior; the proposed change; risks; the exact verification commands."
그런 다음 편집을 허용하기 전에 계획을 검사합니다. 에이전트에게 즉시 “구현하라"고 말하는 것보다 느리게 느껴질 수 있지만, 에이전틱 코딩에서 비용이 높은 실패는 보통 첫 번째 편집 전에 yapılan 잘못된 가정에서 비롯됩니다.
이것은 spec-driven development 뒤에 있는 동일한 직관의 경량, 태스크별 버전입니다. 에이전트가 편집을 시작하기 전에 계획에 합의하는 것입니다. 여러 파일, 세션, 또는 기여자에 걸쳐 작업을 수행하는 경우, 작성된 스펙은 단일 investigate-first 프롬프트가 할 수 없는 방식으로 오버헤드를 정당화합니다. GitHub Spec Kit vs Kiro vs Claude Code 비교는 단일 프롬프트보다 더 나아가는 구조화된 SDD 워크플로를 다룹니다.
서브에이전트는 유용하지만, 위임은 무료가 아님
OpenCode는 자동으로 또는 명시적인 언급을 통해 전문 서브에이전트를 호출할 수 있습니다. 예를 들어:
@general find where retry behavior is implemented
보안 리뷰, 의존성 분석, 프론트엔드 테스트, 또는 문서화와 같은 작업을 위한 전용 서브에이전트를 정의할 수도 있습니다. 동일한 패턴은 다른 하네스에서도 작동하며, Claude Code subagents 가이드는 Anthropic 측면의 유사한 디자인을 다룹니다.
서브에이전트 작업이 기본 대화의 즉각적인 추론 경로 밖에 머물 수 있기 때문에 이것은 강력합니다. 기본 에이전트는 저장소 탐색을 위임하고, 자신의 컨텍스트를 모든 중간 검색으로 채우지 않고 결과를 소비할 수 있습니다. 하지만 서브에이전트는 세 가지 덜 눈에 띄는 비용을 생성합니다:
- 토큰을 소비합니다. 각자가 저장소를 다시 읽는 에이전트 트리는 놀라울 정도로 비싸질 수 있습니다 — 저의 Oh My Opencode 경험 보고서는 이러한 오버헤드가 극단으로 밀어붙여졌을 때 일어나는 일을 문서화합니다.
- 정책 복잡성을 생성합니다. 권한은 부모뿐 아니라 위임된 에이전트에 대해서도 고려되어야 합니다.
- 위임은 추론을 숨길 수 있습니다. 기본 에이전트가 “서브에이전트가 X를 찾았다"고 말할 때, 그 결론이 실제로 얼마나 신뢰할 수 있는지 이해하려면 자식 세션을 검사해야 할 수 있습니다.
대부분의 코딩 작업에서, 정교한 가상의 소프트웨어 회사가 터미널 안에 사는 것보다 두세 개의 목적 있는 에이전트가 더 유용합니다.
작업이 실제로 고정된 전문가 명단에 위임하는 전체 오케스트레이터가 필요하다면 — 병렬 백그라운드 실행, 계획 및 연구 단계, 역할별 모델 라우팅 — 그것은 더 큰 프롬프트가 아니라, 이러한 원시 요소 위에 구축된 다른 제품입니다. Oh My Opencode 빠른 시작은 해당 하네스를 다룹니다.
커스텀 에이전트를 권한 경계로 사용하기
OpenCode 에이전트는 개별 프롬프트, 모델, 권한을 가질 수 있습니다. 이것은 에이전트를 단순히 다른 성격이 아니라 보안 및 워크플로 경계로 유용하게 만듭니다. 예를 들어, 프로젝트 로컬 리뷰 에이전트는 Markdown 파일로 정의될 수 있습니다:
---
description: Reviews code without modifying the repository
mode: subagent
permission:
edit: deny
bash:
"*": ask
"git diff *": allow
"git status *": allow
"git log *": allow
webfetch: deny
---
Review code for correctness, security, maintainability,
unexpected behavior changes, and missing tests.
Do not modify files.
산문으로 “제발 아무것도 수정하지 마세요"라고 작성하는 것보다 훨씬 좋습니다. 지시는 모델을 영향시키고, 권한은 도구를 제약합니다. 그것들은 동등한 제어 수단이 아닙니다.
첫날부터 OpenCode 권한 설정하기
OpenCode의 가장 중요한 실용적 특성 중 하나는 그 기본값이 관대하다는 것입니다. 이는 데모 중에 편리하지만, SSH 키, 프로덕션 자격 증명, 패키지 게시 토큰, Kubernetes 컨텍스트, 여러 클라우드 계정 접근 권한이 포함된 워크스테이션에서 제가 원하는 것은 반드시 아닙니다. 무인 opencode run 잡의 경우, 베팅은 더 높습니다: 구성한 정책 외에 실행을 막는 것은 아무것도 없습니다.
OpenCode의 현재 권한 모델은 다음을 지원합니다:
allow
ask
deny
규칙은 파일 접근, 편집, 셸 명령, 웹 작업, 서브에이전트, 스킬, 외부 디렉토리, 기타 도구 범주에 적용될 수 있습니다. 보수적인 시작점은 다음과 같을 수 있습니다:
{
"$schema": "https://opencode.ai/config.json",
"permission": {
"*": "ask",
"read": "allow",
"grep": "allow",
"glob": "allow",
"edit": "ask",
"bash": {
"*": "ask",
"git status *": "allow",
"git diff *": "allow",
"git log *": "allow",
"git push *": "deny",
"rm *": "deny"
}
}
}
정확한 규칙은 환경에 맞춰야 합니다. 중요한 것은 정책가 의도적인지, 아니면 에이전트가 이미 놀라운 무언가를 실행한 후에 기본값을 발견하는지입니다.
승인 프롬프트를 샌드박싱과 혼동하지 마세요
권한 규칙은 유용하지만, 운영 체제 격리와 같은 것은 아닙니다. OpenCode가 허용된 셸 명령을 실행할 권한이 있다면, 그 프로세스는 환경에서 사용 가능한 접근 권한으로 실행됩니다. 코딩 에이전트는 파일, 네트워크 서비스, 환경 변수, 자격 증명, 소켓, 패키지 매니저, 기타 개발 도구를 잠재적으로 상호작용할 수 있습니다.
민감한 저장소나 무인 실행의 경우, 더 강한 격리를 고려할 가치가 있습니다:
Git은 롤백입니다. 권한은 정책입니다. 컨테이너나 VM은 격리입니다. 그것들은 세 가지 다른 레이어입니다.
반복적인 프롬프트를 커스텀 커맨드로 전환하기
동일한 지시를 반복적으로 입력하고 있다면, 그것은 채팅 히스토리가 아니라 구성이 되어야 합니다. OpenCode는 인터랙티브 인터페이스를 위한 프로젝트 및 글로벌 커스텀 슬래시 커맨드를 지원합니다. 예를 들어, 다음을 생성합니다:
.opencode/commands/review.md
내용은 다음과 같습니다:
---
description: Review the current changes
agent: plan
---
Review the current git diff.
Look for:
- bugs;
- security issues;
- incomplete error handling;
- missing tests;
- accidental API changes.
Do not modify files.
그런 다음 사용합니다:
/review
이것은 불균형한 가치를 가진 작은 기능입니다. 신뢰할 수 있는 코딩 에이전트 워크플로는 좋은 프롬프트가 개인 클립보드 스니펫이 아니라 공유 프로젝트 인프라가 될 때 나타납니다. 다른 유용한 프로젝트 커맨드는 다음과 같을 수 있습니다:
/test-changes
/review
/prepare-pr
/check-migration
/update-docs
/release-check
재사용 가능한 워크플로를 위한 스킬 사용하기
OpenCode는 SKILL.md 파일도 지원합니다. 스킬은 워크플로가 단일 프롬프트보다 더 많은 것을 필요로 할 때 유용합니다. 스킬은 에이전트가 실제로 필요로 할 때까지 로드되지 않은 상태에서 상세한 운영 가이드라인과 지원 파일을 포함할 수 있습니다. 유용한 후보는 다음과 같습니다:
- 데이터베이스 마이그레이션 절차;
- 릴리스 워크플로;
- 인시던트 조사;
- API 호환성 리뷰;
- 패키지 게시;
- 인프라 검증;
- 내부 아키텍처 규약.
예를 들어:
.opencode/skills/database-migration/SKILL.md
스킬 설명은 절차가 적용되는 시점을 OpenCode에게 알려줄 수 있고, 본문은 스키마를 검사하고, 마이그레이션을 생성하고, 롤백 동작을 검증하고, 통합 테스트를 실행하는 방법을 설명합니다. 이미 다른 하네스에서 동일한 개념을 사용하고 있다면, Claude Skills 개발자 가이드는 동일한 디자인 결정을 매핑합니다.
장점은 컨텍스트 규율입니다. 모든 조직 규칙을 AGENTS.md에 덤프하면 결국 모델이 무시하기 쉽고 비용이 많이 드는 거대한 시스템 프롬프트가 생성됩니다. 스킬은 전문 지시가 필요할 때만 컨텍스트에 들어오게 합니다.
MCP: 도구 카탈로그가 문제가 될 때까지 유용함
OpenCode는 로컬 및 원격 MCP 서버를 지원합니다. 이는 이슈 트래커, 문서 시스템, 브라우저, 관측 가능성 플랫폼, 데이터베이스, API, 기타 도구를 코딩 에이전트에 노출할 수 있습니다. 일반적인 구성은 문서 서버를 제공할 수 있습니다:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"context7": {
"type": "remote",
"url": "https://mcp.context7.com/mcp"
}
}
}
MCP는 과사용하기 쉬운 기능 중 하나입니다. 에이전트가 이해해야 할 모든 도구는 주의력과 자주 컨텍스트 토큰을 소비합니다. 15개의 MCP 서버가 있는 설정은 구성 스크린샷에서 강력해 보일 수 있지만, 실제 모델 동작을 더 느리고, 더 비싸고, 더 예측 불가능하게 만들 수 있습니다.
제 규칙은 간단합니다: 일반적인 일주일의 업무에서 유용하지 않은 도구는 전역적으로 활성화되지 않아야 합니다. 통합이 존재하기 때문이 아니라, 워크플로가 필요하기 때문에 도구를 로드하세요.
OpenCode의 로컬 모델: 마법 같은 해결책이 아닌 실제 옵션
OpenCode의 가장 강력한 사용 사례 중 하나는 로컬 또는 셀프호스티드 OpenAI 호환 모델 엔드포인트와 작동할 수 있는 능력입니다. 이는 다음 경우에 매력적입니다:
- 소스 코드가 로컬에 남아야 할 때;
- API 비용이 상당할 때;
- 이미 GPU 인프라를 운영할 때;
- 오픈 모델로 실험하고 싶을 때;
- 인터넷 연결이 불안정할 때;
- 모델 라우팅이 플랫폼의 일부일 때.
커스텀 프로바이더는 LM Studio, llama.cpp를 통한 llama-server, vLLM, Ollama 호환 인프라, 또는 다른 OpenAI 호환 서버와 같은 로컬 엔드포인트로 OpenCode를 가리킬 수 있습니다.
여기서는 기대치가 중요합니다. 좋은 코딩 하네스는 도구 사용, 장기 계획, 코드 추론, 또는 지시 유지가 약한 모델을 완전히 보상할 수 없습니다. 로컬 OpenCode 설정에 대한 커뮤니티 토론은 반복적으로 동일한 관찰로 수렴합니다: 로컬 모델은 제한된 작업에 우수할 수 있지만, 더 작은 모델은 종종 더 많은 감독이 필요합니다. 특정 모델이 OpenCode 안에서 실제로 어떻게 작동하는지에 대한 측정된 숫자는 저의 OpenCode를 위한 실전 LLM 비교를 참조하세요.
실용적인 해결책은 작업 복잡성별 모델 라우팅입니다. 더 저렴하거나 로컬 모델을 다음에 사용하세요:
- 저장소 검색;
- 문서화;
- 간단한 테스트;
- 반복적 편집;
- 포맷 변경;
- 단순한 버그 수정.
더 강한 모델을 다음에 사용하세요:
- 아키텍처 변경;
- 모호한 버그;
- 크로스 패키지 리팩토링;
- 동시성;
- 보안 민감 코드;
- 어려운 마이그레이션.
프로바이더 독립성은 이 전략을 가능하게 합니다. 모델의 질이 무관하게 만들지는 않습니다.
OpenCode를 이용한 실용적인 일상 워크플로
제가 선호하는 워크플로는 의도적으로 보수적입니다. TUI에서든 opencode run을 통해든 동일하게 작동합니다. 단계가 프롬프트인 경우, 커맨드 라인 변형이 함께 표시됩니다.
단계 1: 깨끗한 Git 상태에서 시작
git status
기존 변경 사항을 커밋하거나 이미 수정된 것을 의도적으로 기록하세요. AI 코딩 에이전트가 더러운 워킹 트리 안에서 작동하면, 사람의 변경 사항과 에이전트의 변경 사항이 섞이므로 리뷰가 훨씬 어려워집니다.
단계 2: 먼저 조사 요청
Investigate issue #482.
Do not modify files.
Explain:
- the current behavior;
- likely root cause;
- relevant files;
- existing tests;
- proposed fix;
- verification commands.
동일한 프롬프트를 원샷 커맨드로:
opencode run "Investigate issue #482. Do not modify files. Explain the current behavior, likely root cause, relevant files, existing tests, proposed fix, and verification commands."
조사가 틀렸다면, 그것을 수정하는 것은 비용이 적게 듭니다.
단계 3: 구현 좁히기
Implement the proposed fix only.
Do not refactor unrelated code.
Add the regression test first.
Run the smallest relevant test suite after the change.
또는 비인터랙티브로:
opencode run "Implement the proposed fix only. Do not refactor unrelated code. Add the regression test first. Run the smallest relevant test suite after the change."
이제 에이전트는 더 작은 결정 공간을 가집니다.
단계 4: diff를 직접 검사
git diff --stat
git diff
이 단계를 완전히 다른 모델에 외주화하지 마세요. 코드가 그럴듯해 보이는지뿐만 아니라, 에이전트가 건드리지 않아도 되는 파일을 변경했는지 확인하는 것입니다.
단계 5: 결정론적 검증 실행
npm run typecheck
npm test
npm run lint
실제 프로젝트 명령을 사용하세요. “OpenCode가 테스트가 통과한다고 합니다"는 터미널이 성공적인 테스트 프로세스를 표시하는 것보다 더 강한 증거가 아닙니다.
단계 6: 독립적인 리뷰 실행
읽기 전용 에이전트에게 요청하세요:
Review the uncommitted diff as if it were a pull request written
by another engineer.
Try to find reasons this implementation is wrong.
Do not edit files.
커맨드 라인 변형:
opencode run "Review the uncommitted diff as if it were a pull request written by another engineer. Try to find reasons this implementation is wrong. Do not edit files."
“이 구현이 왜 틀렸는지 이유를 찾아보세요"라는 구절은 의도적인 것입니다. 모델들은 그럴듯한 작업을 정중하게 확인하는 데 매우 좋습니다. 리뷰 프롬프트는 박수보다는 반증을 장려해야 합니다.
단계 7: diff가 합리적일 때만 커밋
git add -p
git commit
에이전트가 생성한 변경 사항 후에도 여전히 인터랙티브 스테이징을 선호합니다. 이는 저장소 히스토리의 일부가 되는 모든 헹크에 대해 마지막 인간 통과를 강제합니다.
OpenCode가 좌절스럽게 느껴지는 곳: 일반적인 함정
흥미로운 한계는 보통 “AI가 문법 오류를 만들었다"가 아닙니다. 컴파일러는 그것을 잡아내는 데 능숙합니다. 어려운 문제는 자율성, 컨텍스트, 숨겨진 가정, 구성에서 비롯됩니다.
도전 1: 모델의 질이 경험을 지배함
동일한 OpenCode 워크플로는 하나의 모델로는 훌륭하게 느껴질 수 있고, 다른 모델로는 거의 사용할 수 없을 수 있습니다. 이는 사용자가 모델 동작을 에이전트 하네스에게 속성짓기 때문에 제품 리뷰를 어렵게 만듭니다.
OpenCode가 반복적으로:
- 지시를 무시하고;
- 너무 많은 코드를 다시 작성하고;
- 도구를 잘못 호출하고;
- 동일한 실패한 동작에 루프하고;
- 제약을 추적하지 못하고;
- API를 발명한다면;
OpenCode 구성 전체를 재설계하기 전에 다른 모델을 시도해 보세요. 터미널이 갑자기 더 똑똑해진 것이 아닙니다. 모델이 그랬습니다.
도전 2: 긴 세션은 나쁜 컨텍스트를 축적함
코딩 에이전트 세션은 잘못된 가정이 축적됨에 따라 신뢰성이 떨어집니다. “이 서비스는 무상태(stateless)이다"와 같은 초기 실수는 관련 파일이 변경된 후에도 수십 개의 후속 결정에 영향을 미칠 수 있습니다.
OpenCode는 컨텍스트 한계를 관리하기 위한 컴팩션을 지원하지만, 압축은 자신의 트레이드오프를 생성합니다. 요약은 필연적으로 어떤 세부 사항이 생존할지 결정합니다. 주요 작업 전환 시, 영웅적인 80,000 토큰 대화는 계속하는 것보다 새로운 세션을 시작하는 것이 종종 더 깨끗합니다. 스크립트된 실행의 경우 답은 더 간단합니다: 새로운 opencode run은 항상 깨끗한 컨텍스트로 시작하므로, 장기간 유지되는 상태는 대화가 아니라 AGENTS.md와 같은 파일에 있어야 합니다.
컨텍스트는 무료 메모리가 아닙니다. 그것은 작업 상태이고, 작업 상태는 오래됩니다.
도전 3: 권한은 속임수를 쓰는 것처럼 복잡해질 수 있음
단순한 규칙은 쉽습니다:
read -> allow
edit -> ask
git push -> deny
복잡한 에이전트 계층 구조는 더 어렵습니다. 기본 에이전트가 서브에이전트, 커스텀 도구, MCP 서버, 셸 명령을 호출할 수 있게 되면, 하나의 구성 라인이 아니라 전체 워크플로의 유효한 능력을 추론해야 합니다.
또한 서브에이전트 권한 동작과 권한 상속에 대한 실제 커뮤니티 및 GitHub 토론이 있었습니다. 교훈은 어떤 하나의 버그보다 더 광범위합니다: 보안 가정을 실제 일회용 저장소로 테스트하세요 — 예를 들어, git init /tmp/opencode-perm-test를 실행하고 거기에 금지한 명령을 에이전트가 실행하도록 시도해 보세요. 어떤 동작이 절대 발생해서는 안 되는 경우, 산문 지시에만 의존하지 마세요.
도전 4: OpenCode는 빠르게 변함
OpenCode는 놀라운 속도로 출하되어 왔습니다. 이는 기능에는 좋지만 문서 수명에는 덜 기쁩니다. 2026년에 특히 쉬운 함정은 다른 OpenCode 세대의 구성 예제를 찾는 것입니다. 현재 문서에는 또한 확립된 1.x 문법과 구성 스키마가 다른 별도의 V2 자료도 포함되어 있습니다. 예를 들어, 권한 개념은 V2 문서에서 다른 필드 이름 아래에 나타날 수 있습니다.
다음에서 가져온 예제를 가볍게 조합하지 마세요:
/docs/
그리고:
/v2/docs/
실제로 어떤 런타임을 사용 중인지 확인하지 않고. 블로그 게시물에서 복사한 구성을 문제 해결할 때, OpenCode가 깨졌다고 가정하기 전에 게시 날짜를 확인하세요.
도전 5: TUI는 규모를 숨길 수 있음
대화형 인터페이스는 10개 파일의 변경을 10개 파일의 변경보다 작게 느끼게 만듭니다. 에이전트는 다음과 같이 보고할 수 있습니다:
Implemented the new validation and updated the relevant tests.
그 문장은 3줄이든 600줄이든 나타낼 수 있습니다. 독립적인 셸 도구를 가까이 두세요:
git status --short
git diff --stat
git diff --name-only
git diff
코딩 에이전트는 코딩 에이전트를 관찰하는 유일한 인터페이스가 되어서는 안 됩니다.
도전 6: MCP는 컨텍스트 효율성을 파괴할 수 있음
더 많은 통합이 자동으로 더 나은 코딩 에이전트를 생성하는 것은 아닙니다. 큰 MCP 서버는 많은 도구 스키마를 노출할 수 있고, 각자는 모델 컨텍스트를 소비하고 도구 선택 복잡성을 증가시킵니다. MCP 생태계의 절반을 설치한 후 OpenCode가 이상할 정도로 결정하지 못한다면, 대부분을 비활성화하고 비교해 보세요. 더 작은 도구 표면은 종종 더 나은 에이전트 동작을 생성합니다.
도전 7: 로컬 프라이버시는 전체 경로를 검증해야 함
로컬 모델을 실행한다고 해서 툴체인 전체가 로컬이라는 것을 자동으로 보장하지는 않습니다. 2026년 초 커뮤니티 토론은 OpenCode의 보조 모델 동작과 웹 인터페이스 아키텍처에 대한 프라이버시 문제를 제기했습니다. 그 주장 중 일부는 이전 버전을 언급했고, 일부는 논쟁의 여지가 있었으며, 일부 코드 경로는 이후 변경되었습니다.
지속적인 교훈은 “OpenCode가 모든 것을 어딘가로 전송한다"가 아닙니다. 지속적인 교훈은: 로컬 전용 운영이 하드 요구사항이라면, 그것을 검증하세요. 네트워크 검사, 현재 구성 읽기, 사용 중인 인터페이스 이해, 불필요한 원격 통합 비활성화, 배포하려는 정확한 버전 테스트를 사용하세요. 보안 요구사항은 추론되는 것이 아니라 검증되어야 합니다.
OpenCode vs Claude Code 및 Codex CLI
OpenCode의 가장 강력한 차별점은 반드시 코딩 품질이 아닙니다. 기반 모델이 여전히 코딩 품질에 크게 기여합니다. 그 차별점은 하네스에 대한 제어입니다.
OpenCode는 다음을 가치 있게 여기는 경우 매력적입니다:
- 오픈소스 구현;
- 프로바이더 유연성;
- 터미널 우선 워크플로;
- 구성 가능한 에이전트;
- 세밀한 권한;
- 로컬 모델 지원;
- MCP;
- 재사용 가능한 커맨드 및 스킬;
- 클라이언트/서버 아키텍처.
Claude Code는 강력한 1차 모델 동작과 점점 더 정교해진 내장 에이전트 워크플로를 가진 긴밀하게 통합된 Anthropic 경험을 원하는 경우 매력적입니다. Codex CLI는 선호하는 모델과 워크플로가 이미 OpenAI의 코딩 스택에 중심을 두고 있는 경우 매력적입니다.
기능을 세어 그들 사이에서 선택하지 않겠습니다. 소유하고 싶은 레이어에 기반하여 선택하세요. 벤더가 대부분의 워크플로 결정을 내리기를 원한다면, 1차 코딩 에이전트가 매력적일 수 있습니다. 프로바이더와 에이전트 구성을 실험하면서 하네스가 교체 가능하게 유지하기를 원한다면, OpenCode가 더 강한 논리를 제공합니다.
Reddit과 Hacker News가 OpenCode에 대해 옳게 보는 점
OpenCode에 대한 커뮤니티 토론은 이례적으로 극단적입니다. 일부 개발자는 특히 Codex 모델, 로컬 모델, 또는 커스텀 에이전트 설정과 결합할 때 이를 가장 좋아하는 코딩 하네스로 묘사합니다. 다른 사람들은 리소스 사용량, 권한 동작, 프라이버시 문제, 프로바이더 인증 변경, 또는 단순해 보이는 터미널 애플리케이션이 인프라가 될 때 나타나는 복잡성에 초점을 맞춥니다. 양쪽 관점 모두 합리적입니다.
OpenCode가 어려운 이유는 커맨드 라인이 어렵기 때문이 아닙니다. 자율적인 코딩 환경이 개발자가 이전에 명시적으로 답할 필요가 없었던 질문들을 노출시키기 때문입니다:
- 어떤 모델이 이 결정을 내려야 합니까?
- 어떤 파일을 읽을 수 있습니까?
- 어떤 명령을 실행할 수 있습니까?
- 프로세스가 어떤 자격 증명을 볼 수 있습니까?
- 어떤 작업이 서브에이전트가 되어야 합니까?
- 얼마나 많은 컨텍스트가 생존해야 합니까?
- 어떤 도구가 영구적인 컨텍스트를 받을 가치가 있습니까?
- 어떤 결과를 인간이 검증해야 합니까?
정교한 폐쇄형 제품은 이러한 결정 중 많은 것을 대신해 줄 수 있습니다. OpenCode는 그 중 더 많은 것을 당신의 것으로 만듭니다. 이것이 바로 고급 사용자가 그것을 좋아하는 이유입니다.
제가 권장하는 시작 구성
즉시 정교한 설정을 구축하는 것을抵制하겠습니다. 다음으로 시작하세요:
- 강력한 기본 모델 하나;
AGENTS.md하나;- 보수적인 셸 및 편집 권한;
- 읽기 전용 리뷰 에이전트;
- 두세 개의 커스텀 커맨드;
- 실제 필요성이 나타날 때까지 MCP 서버 없음.
단순한 환경은 디버깅하기가 더 쉽습니다. 워크플로가 반복적이 되면, 그것을 커맨드, 스킬, 또는 에이전트로 승격하세요. 기능이 위험해지면, 권한으로 제한하세요. 컨텍스트가 부풀어 오르면, 단순히 더 큰 컨텍스트 윈도우를 사는 것이 아니라 워크플로를 분할하세요. 이 점진적인 접근 방식은 스크린샷에서 덜 인상적일 수 있지만, 유지보수하기에는 훨씬 더 기쁩니다.
누가 OpenCode를 사용해야 하는가
OpenCode는 이미 터미널에서 살고 있으며 코딩 에이전트가 다른 프로그래머블 개발 도구처럼 작동하기를 원하는 개발자에게 특히 적합합니다. 다음에 해당한다면 강력하게 고려할 것입니다:
- 여러 LLM 프로바이더에 걸쳐 작업;
- 로컬 모델 지원;
- 하나의 AI 벤더에 잠금 걸리는 것을 싫어함;
- 프로젝트 특정 에이전트 필요;
- 셸 스크립트에서 개발 작업 자동화;
- 코딩 하네스 검사 또는 수정;
- 이미 Git과 일반적인 CLI 도구 이해.
주로 IDE 안의 보이지 않는 AI 레이어를 원한다면 덜 매력적입니다. OpenCode는 전통적인 오토완성 도구보다 더 많은 운영 판단을 기대합니다. diff를 검토하고, 셸 명령을 이해하고, Git 분기를 관리하는 것이 이미 불편하게 느껴진다면, 자율적인 프로세스에那些 도구에 대한 접근 권한을 부여하는 것은 근본적인 복잡성을 사라지게 하지 않을 것입니다.
최종 판정
OpenCode는 AI 코딩 도구가 단순히 채팅 인터페이스가 아니라 개발자 인프라가 되는 더 설득력 있는 예시 중 하나입니다. 그 최고의 기능들은 화려하지 않습니다. 프로바이더 독립성, 명시적 권한, 재사용 가능한 에이전트, 비인터랙티브 실행, 저장소 지시사항, 커맨드, 스킬, 구성 가능한 도구는 에이전트를 실제 엔지니어링 워크플로에 맞춰 형성할 수 있게 합니다.
약점은 그 강점의 거울 이미지입니다. OpenCode는isciplined한 코딩 환경을 만들기에 충분한 제어를 제공하지만, 20개의 MCP 서버와 명확한 검증 경계 없이 복잡하고, 비싸고, poorly isolated한 에이전트 무리를 만들기에 충분한 제어도 제공합니다.
OpenCode를 최대 자율성을 위해 최적화하지 않겠습니다. 짧은 피드백 루프를 위해 최적화하겠습니다. 제한된 문제, 문제를 이해할 충분한 컨텍스트, 필요한 동작만 수행할 권한, 그리고 결과가 작동하는지 증명할 수 있는 결정론적 명령을 제공하세요. 이는 에이전트가 자는 동안 전체 애플리케이션을 빌드하도록 요청하는 것보다 덜 마법스럽습니다. 또한 OpenCode가 진정으로 유용해지도록 하는 데 훨씬 더 가깝습니다.
참고 문헌
- OpenCode 문서: https://opencode.ai/docs/
- OpenCode 변경 로그: https://opencode.ai/changelog
- OpenCode GitHub 저장소: https://github.com/anomalyco/opencode
- Models.dev 프로바이더 카탈로그: https://models.dev
