OpenCode CLI 실전 활용: 워크플로, 자동화, 함정
명령줄에서 OpenCode를 사용하는 실제 가이드
OpenCode의 명령줄 인터페이스는 스크립팅, CI 파이프라인, 그리고 무인 에이전트 실행을 위해 구축되었습니다. 이 글은 일상 업무에서 OpenCode를 사용하는 실전 가이드입니다.
CLI 뒤에는 모델, 도구, 권한, 에이전트, 스킬, 명령어, 세션, MCP 서버, 그리고 클라이언트/서버 아키텍처로 이루어진 시스템이 존재합니다. 에이전트는 프로젝트 파일을 읽고 편집하며, 저장소를 검색하고, 셸 명령을 실행하고, 외부 도구를 호출하며, 작업을 서브 에이전트로 위임할 수 있습니다. 동일한 환경은 TUI에서 인터랙티브하게 또는 스크립트에서 비인터랙티브하게 실행됩니다.
작은 작업의 경우, 수 분 안에 설치하고 모델을 연결하여 질문을 시작할 수 있습니다. 본격적인 작업을 위해서는 경험의 질이 모델 선택, 저장소 지침, 권한 경계, 컨텍스트 관리, 그리고 에이전트의 작동 허용 범위에 크게 좌우됩니다. 이 글은 두 번째 단계인 명령줄에서의 경험, 즉 어떤 사용 사례가 가치를 발휘하는지, 어떤 자동화 워크플로가 일상 사용에서 견고한지, 그리고 AI 기반 터미널의 신선함이 사라진 후에 어떤 문제들이 발생하는지에 초점을 맞춥니다. 이 글은 이 사이트의 AI 개발자 도구 섹션의 일부입니다.
여기서의 관찰 사항은 2026년 8월 기준 OpenCode 1.18.9 및 현재 문서와 대조하여 확인했습니다. OpenCode는 빠르게 변하므로, 장수하는 팀 세팅에 설정 예시를 복사하기 전에 간단한 문서 확인이 필요합니다. 아직 OpenCode를 설치하지 않았다면, OpenCode 빠른 시작에 설치, 검증, 그리고 제공자 연결 방법이 다뤄집니다.
OpenCode의 실제 정체: 채팅 박스가 아닌 에이전트 환경
OpenCode는 터미널 중심으로 설계된 오픈소스 AI 코딩 에이전트입니다. OpenCode가 함께 작동시키는 요소들의 단순화된 구조는 다음과 같습니다:
가장 중요한 부분은 모델의 의도와 OpenCode가 수행할 수 있는 행동 사이의 권한 레이어입니다. 훌륭한 모델이지만 권한 설정이 나쁘다면 위험할 수 있습니다. 약한 모델이지만 권한이 완벽하다면 그저 느리고 귀찮을 뿐입니다. 생산적인 OpenCode 사용을 위해서는 양쪽 측면을 모두 합리적으로 올바르게 설정해야 합니다.
동일한 환경은 인터랙티브 TUI와 비인터랙티브 명령줄, 두 가지 표면 모두를 제공합니다. 이것이 OpenCode를 순수한 채팅 인터페이스가 할 수 없는 방식으로 스크립팅 가능하게 만들어 줍니다. 동일한 터미널 에이전트 아이디어에 대한 고의적으로 최소한의 접근 방식을 원한다면 — 네 개의 기본 도구, 내장 샌드박스 없음, 기타 모든 것은 확장으로 — Pi 코딩 에이전트 리뷰는 유용한 대비가 됩니다.
설정: 설치, 연결, 그리고 왜 제공자 독립성이 중요한가
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."
또는 컨텍스트를 실행으로 직접 파이프할 수 있습니다:
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.
훌륭한 에이전트는 진입점을 검색하고, 참조를 따라가고, 테스트를 검사하고, 단순한 텍스트 검색보다 아키텍처 walkthrough에 가까운 무언가를 반환합니다. 에이전트가 코드를 작성하지 않고도 가치를 제공할 수 있기 때문에, 이는 기존 코드베이스에 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."
그런 다음 편집을 허용하기 전에 계획을 검사합니다. 에이전트에게 즉시 “구현해"라고 말하는 것보다 느리게 느껴지지만, 에이전틱 코딩의 비용이 큰 실패는 보통 첫 번째 편집 전에 이루어진 잘못된 가정에서 비롯됩니다.
이는 스펙 기반 개발 이면에 있는 동일한 직관의 가볍고 작업 단위 버전입니다: 에이전트가 편집을 시작하기 전에 계획에 합의한다. 여러 파일, 세션, 또는 기여자를 가로지르는 작업의 경우, 하나의 investigate-first 프롬프트가 할 수 없는 방식으로 문서화된 스펙은 오버헤드를 정당화하며, GitHub Spec Kit vs Kiro vs Claude Code 비교는 단일 프롬프트보다 더 깊이 나아가는 구조화된 SDD 워크플로를 다룹니다.
서브 에이전트는 유용하지만, 위임에는 비용이 발생
OpenCode는 자동적으로 또는 명시적 언급을 통해 전문화된 서브 에이전트를 호출할 수 있습니다. 예를 들어:
@general find where retry behavior is implemented
보안 리뷰, 의존성 분석, 프론트엔드 테스트, 또는 문서화와 같은 작업을 위해 전용 서브 에이전트를 정의할 수도 있습니다. 동일한 패턴은 다른 하네스에서도 작동하며, Claude Code 서브 에이전트 가이드는 Anthropic 측의 유사한 설계를 다룹니다.
이는 강력합니다. 서브 에이전트의 작업은 주요 대화의 즉각적인 추론 경로 밖에서 머물 수 있기 때문입니다. 주요 에이전트는 저장소 탐색을 위임하고, 모든 중간 검색으로 자신의 컨텍스트를 채우는 대신 결과를 소비할 수 있습니다. 하지만 서브 에이전트는 세 가지 덜 명백한 비용을 생성합니다:
- 토큰을 소비합니다. 각각 저장소를 다시 읽는 에이전트의 나무는 의외로 비싸질 수 있습니다 — 제 Oh My Opencode 경험 리포트는 그 오버헤드가 극단으로 나아갈 때 무슨 일이 일어나는지를 문서화합니다.
- 정책 복잡성을 생성합니다. 권한은 부모 에이전트뿐만 아니라 위임된 에이전트에 대해서도 고려해야 합니다.
- 위임은 추론을 숨길 수 있습니다. 주요 에이전트가 “서브 에이전트가 X를 찾았다"고 말할 때, 그 결론이 실제로 얼마나 신뢰할 만한지 이해하려면 자녀 세션을 검사할 필요가 있을 수 있습니다.
대부분의 코딩 작업에 대해서는, 터미널 안에 사는 정교한 가상의 소프트웨어 회사가 아니라 두세 개의 목적 지향 에이전트가 더 유용합니다.
작업이 실제로 고정된 전문가 로스터에 위임하는 전체 오케스트레이터를 필요로 한다면 — 병렬 배경 실행, 계획 및 연구 단계, 역할별 모델 라우팅 — 이는 더 큰 프롬프트가 아니라, 이러한 원시 요소 위에 구축된 별개의 제품입니다. Oh My Opencode 빠른 시작에서 해당 하네스를 다룹니다.
사용자 정의 에이전트를 권한 경계로 사용하기
OpenCode 에이전트는 별도의 프롬프트, 모델, 권한을 가질 수 있습니다. 이는 에이전트가 단순히 다른 성격이 아니라 보안 및 워크플로 경계로서 유용하게 만듭니다. 예를 들어, 프로젝트 로컬 리뷰 에이전트는 마크다운 파일로 정의할 수 있습니다:
---
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.
이는 산문으로 “무엇을 편집하지 말아 주세요"라고 쓰는 것보다 훨씬 낫습니다. 지침은 모델을 영향시키고, 권한은 도구를 제한합니다.它们是 equivalent controls이 아닙니다.
첫 날에 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가 허용된 셸 명령을 실행할 권한이 있다면, 그 프로세스는 환경에서 사용 가능한 액세스를 가지고 실행됩니다. 코딩 에이전트는 잠재적으로 파일, 네트워크 서비스, 환경 변수, 자격 증명, 소켓, 패키지 매니저, 기타 개발 도구와 상호작용할 수 있습니다. OpenHands CLI 빠른 시작는 샌드박스화된 대응물입니다: Docker 워크스페이스, 항상 승인하는 헤드리스 모드, 그리고 OpenHands 프로젝트가 현재 문서화하는 Agent Canvas 핸드오프.
민감한 저장소나 무인 실행의 경우, 더 강한 격리를 고려할 가치가 있습니다:
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는 남용하기 쉬운 기능 중 하나입니다. 에이전트가 이해해야 하는 모든 도구는 주의를 소비하고 자주 컨텍스트 토큰도 소비합니다. MCP 서버 15개가 있는 구성은 구성 스크린샷에서 강력해 보일 수 있지만, 실제 모델 동작을 더 느리고, 더 비싸고, 덜 예측 가능하게 만들 수 있습니다.
제 규칙은 간단합니다: 일주일간의正常工作에서 유용하지 않는 도구는 전역적으로 활성화하지 말아야 할 가능성이 높습니다. 통합이 존재하기 때문에가 아니라 워크플로가 필요로 하기 때문에 도구를 로드하십시오.
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
아직도 에이전트 생성 변경 사항 후 인터랙티브 스테이징을 선호합니다. 이는 저장소 히스토리의 일부가 되는 모든 hunk에 걸쳐 마지막 인간 패스를 강제합니다.
OpenCode가 좌절스럽게 만드는 곳: 일반적인 함정
흥미로운 한계는 보통 “AI가 문법 오류를 만들었다"가 아닙니다. 컴파일러는 그것을 찾는 데 좋습니다. 어려운 문제는 자율성, 컨텍스트, 숨겨진 가정, 구성에서 비롯됩니다.
과제 1: 모델 품질이 경험을 지배
동일한 OpenCode 워크플로는 한 모델에서는 훌륭하게 느껴지고 다른 모델에서는 거의 쓸모없게 느껴질 수 있습니다. 이는 사용자가 종종 모델 동작을 에이전트 하네스에 귀인하기 때문에 제품 리뷰를 어렵게 만듭니다.
OpenCode가 반복적으로:
- 지침을 무시하고;
- 너무 많은 코드를 다시 쓰고;
- 도구를 올바르게 호출하지 않고;
- 같은 실패한 동작에 루프하고;
- 제약을 추적하지 못하고;
- API를 발명하면;
전체 OpenCode 구성을 재설계하기 전에 다른 모델을 시도하십시오. 터미널이 갑자기 똑똑해진 것은 아닙니다. 모델이 그렇습니다.
과제 2: 긴 세션은 나쁜 컨텍스트를 축적
코딩 에이전트 세션은 잘못된 가정이 축적될수록 신뢰할 수 없게 됩니다. “이 서비스는 상태가 없다"와 같은 초기 실수는 관련 파일이 변경된 후에도 수십 개의 후기 결정에 영향을 미칠 수 있습니다.
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는 놀라운 속도로 출하되어 왔습니다. 기능에는 좋지만, 문서의 장수에는 덜 menyenangkan입니다. 2026년의 특히 쉬운 함정은 다른 OpenCode 세대의 설정 예시를 찾는 것입니다. 현재 문서에는 확립된 1.x 구문과 구성 스키마가 다른 별개의 V2 자료도 포함합니다. 예를 들어, 권한 개념은 V2 문서에서 다른 필드 이름 아래로 나타날 수 있습니다.
다음의 예시를 결합하지 마십시오:
/docs/
그리고:
/v2/docs/
실제로 사용하는 런타임을 확인하지 않고. 블로그 게시물에서 복사한 구성을 문제 해결할 때, OpenCode가壊れた다고 가정하기 전에 그 발행 날짜를 확인하십시오.
과제 5: TUI는 규모를 숨길 수 있음
대화형 인터페이스는 10개 파일 변경이 10개 파일 변경보다 작게 느끼게 합니다. 에이전트는 다음을 보고할 수 있습니다:
Implemented the new validation and updated the relevant tests.
그 문장은 세 줄 또는 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 and 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는 규율적인 코딩 환경을 생성할 수 있는 충분한 통제를 제공하지만, 명확한 검증 경계 없이 20개의 MCP 서버와 함께 복잡하고 비싸고 격리가 poorly된 에이전트 무리를 생성할 수 있는 충분한 통제도 제공합니다.
OpenCode를 최대 자율성을 위해 최적화하지 않겠습니다. 짧은 피드백 루프를 위해 최적화하겠습니다. 경계가 있는 문제, 그 문제를 이해할 충분한 컨텍스트, 필요한 행동만 수행할 권한, 그리고 결과가 작동하는지 입증할 수 있는 결정론적 명령을 부여하십시오. 에이전트가 당신이 자는 동안 전체 애플리케이션을 구축하도록 요청하는 것보다 덜 마법적입니다. 그것은 또한 OpenCode가 진정으로 유용해지기에 훨씬 더 가깝습니다.
참고 자료
- OpenCode 문서: https://opencode.ai/docs/
- OpenCode 변경 로그: https://opencode.ai/changelog
- OpenCode GitHub 저장소: https://github.com/anomalyco/opencode
- Models.dev 제공자 카탈로그: https://models.dev
