환경 확인
Node.js LTS, Git, 작업 폴더, Provider 접근 가능한 네트워크를 준비합니다.
2026 실전 가이드
OpenCode 배포 가이드설치, 설정,모델 검증까지
OpenCode를 빠르게 실행하기 위한 정적 가이드입니다. 환경 점검, CLI 설치, Provider 연결, 프로젝트 설정, 검증 작업, 자주 나는 오류를 순서대로 다룹니다.
- 추천 시작점
- CLI 우선
- 핵심 설정
- Provider + 모델
- 대상
- AI 코딩 사용자
Quick Start
7단계 배포 흐름
첫 설치나 새 기기로 이전할 때 쓸 수 있는 순서입니다.
CLI 설치
공식 방식으로 설치하고 opencode 명령이 동작하는지 확인합니다.
Provider 연결
먼저 하나만 연결하고 API Key는 저장소 밖에 둡니다.
모델 선택
안정적인 모델과 실제 모델 ID를 사용합니다.
설정 작성
비밀값을 제외한 프로젝트 설정을 opencode.json에 둡니다.
작은 작업 검증
파일 읽기, 작은 수정, 테스트 실행을 확인합니다.
문제 해결 기록
Node 버전, Provider, 프록시, 모델, 오류를 기록합니다.
Provider
Provider 설정
대부분의 실패는 API Key, Base URL, 모델명, 프록시, 권한에서 발생합니다.
| 항목 | 권장 작업 | 흔한 실수 |
|---|---|---|
| API Key | 저장소 밖에 보관합니다. | Git에 비밀값 커밋. |
| Base URL | 공식 엔드포인트를 사용합니다. | 잘못된 경로 사용. |
| 모델명 | 실제 모델 ID를 복사합니다. | 마케팅 이름 사용. |
| 권한 | 처음에는 보수적으로 둡니다. | 검증 전 모든 명령 허용. |
Project config example
Use this as a non-secret configuration shape. Confirm exact fields with your OpenCode version.
{
"model": "provider/model-id",
"permission": { "edit": "ask", "bash": "ask" },
"ignore": ["node_modules", ".env", "dist"]
}Platform Notes
플랫폼 메모
Windows
간단한 프로젝트는 PowerShell, Linux 의존이 크면 WSL.
macOS
터미널이 사용하는 Node를 확인합니다.
Linux
root 상시 사용을 피하고 키를 보호합니다.
Troubleshooting
문제 해결 순서
- 명령이 없으면 PATH 확인.
- 모델이 비면 Provider와 Key 확인.
- Timeout은 네트워크와 프록시 분리.
- 권한 오류는 폴더와 정책 확인.
- 품질 문제는 안정 모델로 검증.
FAQ
FAQ
무엇을 먼저 설치해야 하나요?
Node.js LTS, Git, 터미널, Provider API Key가 필요합니다.
opencode.json은 어디에 두나요?
보통 저장소 루트에 둡니다. 비밀값은 제외합니다.
검증은 어떻게 하나요?
읽기, 작은 편집, 테스트 실행을 확인합니다.