OpenCode란 무엇인가#
OpenCode가 무엇인지 사용법의 관점에서 다룹니다. "무료"로 시작하는 경로와 모델 키를 붙이는 경로를 나눠 처음 설치할 때 어디서 막히는지 살펴봅니다.
| 단계 | 확인할 내용 |
|---|---|
| 설치 | 운영체제에 맞는 OpenCode V2 공식 설치 방법 |
| 모델 연결 | 제공자의 인증 방식과 선택할 모델의 이용 조건·비용 |
| 첫 작업 | 파일 편집과 셸 실행에 적용되는 권한 규칙 |
- OpenCode V2 공식 설치 안내에서 환경에 맞는 방법을 선택합니다.
- 민감한 정보가 없는 프로젝트 폴더에서 OpenCode를 실행합니다. 대부분의 제공자는
/connect로 연결하지만, 로컬 Ollama는 아래 안내처럼 계정 연결 없이 검색될 수 있습니다. /models에서 모델을 선택하고 해당 제공자의 이용 조건을 확인합니다.- 데이터 이용 조건과 권한 규칙을 확인한 뒤 파일을 수정하지 말고 저장소 구조를 설명해 달라고 요청합니다.
추가 검증 필요: 실제 설치 과정과 제공자 인증·모델 연결, 한국어 입력·IME 및 한글 파일명 처리, 첫 작업과 권한 승인·중단 결과에 대한 기록은 아직 없습니다.
설치 전 확인: 계정·권한·비용#
OpenCode V2 공식 안내에서 지원 환경과 설치 방법을 확인하세요. 모델 제공자에 따라 인증 방식과 사용료가 다르므로 무료 제공 여부와 한도를 해당 제공자에게 확인하세요. 아래 공식 문서 링크는 2026-11-03에 확인했습니다.
OpenCode Console 모델 안내에는 기간 한정 무료 모델과 유료 모델이 함께 나옵니다. 무료 제공과 데이터 처리 조건은 모델마다 다를 수 있습니다. Console의 유료 경로는 계정, 크레딧과 API 키를 사용하며, Console 연결은 선택 사항입니다.
무료 모델 안내를 확인한 뒤 /models에서 현재 선택 가능한 무료 모델을 고르는 방법이 있습니다. 예를 들어 공식 문서는 Big Pickle을 기간 한정 무료로 소개하지만, 무료 기간에 수집한 데이터가 모델 개선에 사용될 수 있다고 밝힙니다. 이용 가능 여부와 제한은 바뀔 수 있으므로 선택한 모델의 현재 비용과 개인정보 조건을 확인하고 민감한 내용은 보내지 마세요.
또 다른 경로는 로컬 Ollama입니다. Ollama 서버를 실행하고 completion을 지원하는 모델을 내려받은 뒤 /models에서 검색된 모델을 선택합니다. 기본 로컬 서버는 계정 연결 없이 검색될 수 있지만, 모델 사용 조건과 로컬 실행에 필요한 자원은 별도로 확인하세요. 원격 Ollama나 다른 제공자로 연결한다면 해당 경로의 데이터 처리 조건도 확인하세요.
설치와 인증#
| 연결 경로 | 먼저 확인할 조건 | 비용·정보 처리 확인 |
|---|---|---|
| Console 무료 모델 | 현재 무료 제공과 선택 가능한 모델 | 기간·한도·모델별 개인정보 조건 |
| 유료 제공자·API | 해당 제공자의 인증과 모델 이용 권한 | 사용량·추가 청구와 제공자별 보존 조건 |
| 로컬 Ollama | 서버 실행과 완료 생성 모델의 검색 여부 | 로컬 자원·모델 라이선스, 원격 호출 여부 |
위에 링크한 V2 문서의 경로를 정리한 표이며, 각 연결을 실행해 얻은 결과가 아닙니다.
OpenCode V2 공식 설치 안내에 따라 설치한 뒤, 프로젝트 폴더에서 실행하세요. 대부분의 제공자는 입력창에서 /connect로 연결하고 /models에서 모델을 선택합니다. 인증 방식은 제공자에 따라 다릅니다. 자세한 내용은 공식 제공자 연결 안내를 참고하세요. Ollama 안내에 따르면 로컬 Ollama 서버를 실행하고 모델을 내려받으면 OpenCode가 완료 생성 모델을 검색해 계정 연결 없이 /models에 추가할 수 있습니다. 별도의 Mirr Code 설치 문서는 OpenCode 설치 안내가 아닙니다.
설치 경로 고르기#
공식 설치 안내는 셸 스크립트, Homebrew 탭, npm·bun·pnpm·yarn·Vite+ 같은 패키지 관리자, AUR, mise를 설치 경로로 나열합니다. 팀이 이미 쓰는 도구를 기준으로 고르면 됩니다. npm 패키지는 설치 후 스크립트로 현재 플랫폼의 실행 파일을 고르며, 공식 bun과 pnpm 명령에는 이 스크립트를 허용하는 옵션이 들어 있습니다. mise로 설치하려면 mise 2026.10.9 이상이 필요하고, 그보다 오래된 mise는 V1을 설치하므로 설치 뒤 버전을 확인하세요.
Windows에서는 패키지 관리자 설치를 지원하지 않는다고 공식 안내가 밝힙니다. 이때는 독립 실행 파일 압축본이나 데스크톱 앱 설치 파일을 내려받으면 됩니다. 브라우저에서 쓰는 웹 인터페이스는 opencode pair 명령이 만든 연결 링크로 열며, 링크는 한 번만 쓸 수 있고 5분 뒤 만료됩니다.
예전 자료를 참고한다면 설정 이름도 확인하세요. V2 권한 설정에서는 permission 대신 permissions, bash 대신 shell, task 대신 subagent를 씁니다.
로컬 모델 서버 연결 세부 설정#
Ollama는 기본적으로 127.0.0.1의 11434 포트를 탐지합니다. 다른 장치나 프록시 뒤의 서버를 쓴다면 제공자 설정의 baseURL에 주소를 적고, 끝에 /v1을 포함해야 합니다. apiKey는 선택 항목이며, 값을 넣으면 탐지 요청과 모델 요청에 베어러 토큰으로 함께 보냅니다. 공식 예시는 키를 환경 변수 참조 형태로 적고 있습니다.
탐지 목록은 주기적으로 갱신되고, 일시적인 장애가 나도 마지막으로 성공한 목록을 유지합니다. 완료 생성 기능이 없는 임베딩 전용 모델은 목록에 나타나지 않습니다. LM Studio와 vLLM도 로컬 탐지를 지원하며 기본 주소는 각각 127.0.0.1의 1234 포트와 8000 포트의 /v1입니다. vLLM에서 발견된 모델은 도구 기능이 꺼진 상태로 시작합니다. OpenRouter는 자체 런타임과 모델 카탈로그를 씁니다. 주소를 바꾸거나 OpenRouter 호환 게이트웨이를 거칠 때도 기본 OpenRouter 패키지를 유지해야 요청과 추론 동작이 보존된다고 공식 안내는 설명합니다.
OpenCode 모델 비교: 연결 경로와 과제 조건으로 고르기#
다음은 런타임 순위표가 아닌 선택 기준입니다. OpenCode 모델 비교에서는 같은 모델 이름이라도 제공자·인증 경로·API 설정과 variant를 구분하세요. V2 모델 문서는 /models에서 현재 프로젝트에 제공되는 항목을 고르도록 안내하며, 세션의 선택이 설정 기본값을 다시 쓰지는 않는다고 설명합니다.
| 비교 기준 | 공식 자료에서 확인할 것 | 같은 과제에서 기록할 것 |
|---|---|---|
| 모델의 정체 | provider/model과 선택한 variant, 별칭의 실제 modelID | 요청을 받은 제공자·모델·버전과 설정 |
| 도구·입력 지원 | 도구 호출, 텍스트·이미지 입력 등 현재 지원 범위 | 필요한 검색·편집·도구 호출이 실제로 가능한지 |
| 맥락·출력 한도 | 모델·제공자에 적용되는 context/input/output 제한 | 같은 입력의 잘림·거부·미완료 여부 |
| 비용·인증 | 구독·API·로컬 중 경로와 포함량·추가 청구 | 실제 사용량·비용과 실패·재시도 |
| 데이터·실행 환경 | 선택한 제공자의 보존·학습 조건, 로컬·원격 경로 | 승인된 데이터 범위와 실제 실행 환경 |
- 과제와 수용 기준, 저장소 버전·입력·도구 권한을 먼저 고정합니다. 예를 들어 같은 오류 수정에 필요한 diff·테스트와 한국어 설명을 평가하되, 비밀정보 없는 승인된 샘플만 사용하세요.
- 필요한 제공자를 연결하고
/models에서 현재 사용 가능한 후보를 확인합니다. 모델 ID나 variant를 추측하지 말고 표시된 항목과 해당 제공자의 공식 지원·요금 문서를 대조합니다. 한 프로젝트의 모델·인증이 다른 프로젝트에도 그대로 적용된다고 가정하지 마세요. - 조건을 맞춘 별도 세션에서 후보별 같은 입력과 완료 기준을 적용하도록 계획합니다. variant·추론 설정·도구 지원이 다르면 차이를 기록하고, 권한이나 데이터 정책을 비교를 위해 임의로 풀지 않습니다.
- 실제로 실행했다면 diff의 요구사항 충족, 테스트·미실행 검사, 한국어 용어 보존, 소요 시간·사용량·비용과 실패를 함께 기록합니다. 한 번의 성공을 일반 성능 순위로 확대하지 말고 원본 결과와 검토 조건을 남기세요.
설정으로 추가한 모델의 기본 capabilities·limit는 실제 탐지값이 아닌 대체 가정일 수 있습니다. 따라서 카탈로그에 표시된 한도나 도구 지원만으로 동작을 보증하지 않습니다. 근거: OpenCode V2 모델·별칭·한도(2026-11-03 확인), 제공자·인증·과금 경로(2026-11-03 확인), Console 모델별 조건(2026-11-03 확인). 후보별 실제 실행 결과, 비용, 순위는 아직 확인되지 않았습니다.
설정 파일 위치와 우선순위#
프로젝트 설정은 루트의 opencode.jsonc에 두는 것이 기본입니다. JSON과 JSONC를 모두 읽으며, JSONC에서는 주석과 끝의 쉼표를 쓸 수 있습니다. 모든 프로젝트에 공통인 값은 ~/.config/opencode/ 아래 설정 파일에 둡니다. OpenCode는 실행한 폴더에서 최상위까지 올라가며 설정을 찾고, .opencode 폴더 안의 설정을 루트에 놓인 설정보다 우선합니다. 하위 패키지에서 실행하면 그 패키지 설정이 저장소 설정을 덮어쓰므로, 실행 위치에 따라 모델이나 권한이 달라지는지 확인하세요. 공식 안내에 따르면 설정 파일은 OpenCode에 요청해 고칠 수도 있습니다. 설정은 필요한 항목만 적으면 됩니다.
우선순위는 낮은 것부터 전역, 프로젝트, 하위 패키지, 시스템 설정 순서입니다. 관리 설정은 가장 높으며 사용자와 프로젝트가 그 값을 바꿀 수 없습니다. 다만 설정만으로는 제공자나 MCP 서버를 추가하는 것을 막을 수 없으므로 제한이 필요하면 관리 정책을 따로 두어야 합니다.
model 항목은 새 작업의 기본 모델입니다. 설정한 모델이 활성화되어 있고 현재 프로젝트에서 제공자를 쓸 수 있을 때만 적용되며, 그렇지 않으면 쓸 수 있는 최신 지원 모델이 대신 쓰입니다. /models에서 고른 모델은 그 세션에만 적용되고 설정 파일을 다시 쓰지 않습니다. 한 번의 실행만 바꾸려면 --model 옵션을 씁니다.
무료 모델의 데이터 조건 세부#
무료 모델은 제공자마다 데이터 조건이 다릅니다. 공식 개인정보 목록에서 NVIDIA 무료 엔드포인트를 쓰는 Nemotron 계열 세 모델은 시험 사용 전용으로 표시되어 있고, 개인정보나 기밀 자료를 보내지 말라고 적혀 있습니다. 이 경로의 사용 기록은 보안과 제품 개선 목적으로 남습니다. Flint 40B Free는 무료 기간의 수집 데이터가 모델 개선에 쓰일 수 있고 30일 보관된다고 나옵니다. Beam Free는 학습에 쓰지 않지만 안전을 위해 30일 보관합니다.
팀에서 무료 모델을 쓰지 않게 하려면 서버 프로세스에 OPENCODE_DISABLE_FREE_MODELS 값을 1로 설정합니다. 그러면 무료 모델은 카탈로그와 기본값에서 빠지고, 직접 고르면 Model unavailable 오류가 납니다.
유료 경로의 청구 방식#
Console의 유료 경로는 요청 단위로 과금되며, 계정에 크레딧을 충전해 씁니다. 잔액이 적어질 때 자동으로 충전하는 설정이 있고, 예산을 정하면 작업 공간과 구성원별 월 지출을 제한할 수 있습니다. 요금과 충전 조건은 바뀔 수 있으므로 결제 화면과 공식 안내에서 현재 값을 확인하세요.
첫 작업: 수정하지 말라고 요청하기#
첫 작업에는 민감한 정보가 없는 저장소를 사용하세요. 읽기 전용은 변경 여부에 관한 표현이지 데이터 기밀성을 보장하지 않습니다. 코드와 요청이 선택한 모델 제공자에게 전달될 수 있으므로 실제 경로와 제공자의 보존·학습·데이터 처리 조건을 확인하세요. OpenCode Console 개인정보 안내는 Console 모델에만 적용되므로 다른 제공자는 해당 제공자의 조건도 확인하세요.
“파일을 수정하지 말고 저장소 구조를 설명해 주세요”는 요청일 뿐, 권한을 제한하지는 않습니다. OpenCode V2 권한 안내에 따르면 Plan 에이전트는 일부 계획 파일을 제외하고 편집을 거부하지만, 셸은 별도로 살펴봐야 합니다. 셸은 사용자 계정의 파일 시스템·프로세스·네트워크 권한으로 실행될 수 있으므로 편집 제한만으로 완전한 읽기 전용 경계가 되지는 않습니다.
권한 승인과 중단#
V2 권한 규칙에서 편집과 셸을 포함한 동작별 allow, ask, deny 및 적용 순서를 확인하세요. 승인 요청이 항상 표시되는 것은 아닙니다. 요청이 나오면 명령과 경로, 한 번만 허용할지 지속적으로 허용할지 검토하고 원하지 않는 작업은 거절하세요.
V2 키 설정 안내에 따르면 세션 중단 키의 기본값은 escape이고, 같은 키는 diff 보기를 닫는 등 화면에 따라 다른 동작에도 쓰입니다. 현재 키 바인딩은 같은 안내에서 확인하세요. 중단이 이미 수행된 변경이나 외부 작업을 자동으로 되돌리는 것은 아닙니다.
권한 규칙이 적용되는 순서#
권한 규칙은 permissions 배열에 action(도구 종류), resource(경로·명령·주소 같은 대상), effect(allow, deny, ask) 세 값을 넣어 씁니다. 여러 규칙이 같은 작업에 걸리면 마지막으로 일치한 규칙이 이깁니다. 그래서 넓은 규칙을 앞에 두고 예외를 뒤에 두어야 합니다. 어떤 규칙에도 걸리지 않으면 ask가 적용됩니다.
패턴의 *는 /를 포함한 임의의 문자열이고 ?는 한 글자입니다. 셸 패턴이 *로 끝나면 인수가 없는 명령도 일치하므로, git status *는 git status와 git status --short를 모두 허용합니다. 한 작업이 여러 대상을 건드리면 하나라도 deny에 걸리면 차단되고, 차단이 없고 ask에 걸리면 승인을 묻습니다.
프로젝트 밖 경로는 external_directory 권한으로 따로 검사하는데, 기본 정책이 이를 허용하므로 별도 규칙이 없으면 묻지 않고 진행됩니다. 밖의 접근을 물어보려면 이 권한을 ask로 바꾸고, 필요한 디렉터리만 뒤에 allow로 여세요. 승인 요청에 답하는 방법은 세 가지입니다. once는 그 요청만 허용하고, always는 도구가 제안한 패턴을 프로젝트 전용 allow 규칙으로 저장하며, reject는 같은 세션의 대기 중인 모든 요청을 거절합니다. 저장된 승인은 설정의 deny를 이기지 못합니다.
계획 에이전트와 셸 명령#
모든 에이전트는 *에 allow를 주는 기본 정책에서 시작합니다. 공식 목록에서 plan 에이전트는 이 정책에 질문 허용을 더하고, ~/.opencode/plan 아래 파일을 제외한 편집을 거부합니다. 셸 명령에 대한 추가 규칙이 없다면 plan 에이전트에서도 셸은 묻지 않고 허용됩니다. 계획 모드에서 명령 실행까지 막으려면 shell 항목에 ask나 deny를 직접 추가해야 합니다.
기본 에이전트마다 추가 정책도 다릅니다. build는 질문만 더 허용하고, general은 질문과 하위 에이전트 실행을 거부합니다. explore는 셸, 읽기, 검색, 웹 조회와 외부 디렉터리 외의 작업을 거부하지만, 셸이 목록에 남아 있으므로 탐색용 에이전트에서도 명령 실행 가능성은 남아 있습니다.
셸 허용 범위는 좁게 잡는 편이 낫습니다. 공식 안내는 명령 문자열에서 작업 디렉터리를 추론하는 기능이 최선 노력 방식이라고 밝히므로, 위험한 명령을 모두 잡으려는 넓은 패턴보다 필요한 명령만 허용하는 목록을 권합니다.
한국어 설정과 한글 파일명#
한국어 입력과 한글 파일명 처리는 사용 중인 환경에서 확인하세요. 실제 화면 증거는 아직 없습니다.
민감정보 없는 파일에 한국어를 입력·저장한 뒤 다시 열고, 한글 경로 검색과 응답의 용어 보존을 따로 확인하세요. 입력 중 조합 문제라면 다른 터미널에서도 같은지 비교하고 운영체제·입력기·터미널 버전을 함께 기록합니다.
자격 증명 저장과 환경 변수#
API 키와 OAuth 토큰은 서버의 SQLite 데이터베이스에 저장됩니다. 일반 릴리스의 경로는 ~/.local/share/opencode/opencode.db이며, opencode debug paths db로 실제 경로를 확인할 수 있습니다. 데이터베이스를 직접 편집하지 말고 /connect나 auth 명령으로 관리하세요. 이전 auth.json의 자격 증명은 V2로 옮길 때 가져오며, 이후 새로 저장되는 값은 데이터베이스에만 기록됩니다.
환경 변수로 연결한 제공자는 auth list에 environment 유형으로 나타나지만 계정이 아니므로 auth logout으로 제거되지 않습니다. 연결을 끊으려면 변수를 지워야 합니다. 같은 제공자에 저장된 계정과 환경 변수가 함께 있으면 저장된 계정이 우선합니다.
오류 문구별로 볼 곳#
No model is available for session은 선택 가능한 모델이 하나도 없다는 뜻입니다. Model unavailable: 제공자/모델은 제공자가 비활성이거나 모델 ID가 없거나 꺼져 있거나, 동적 탐지에서 더 이상 나오지 않는다는 뜻입니다. 사용자 지정 별칭이면 modelID가 아니라 models 항목의 키를 확인하세요. NAME is required가 붙은 해석 오류는 baseURL에 ${NAME} 자리표시자가 남아 있다는 뜻이므로 환경 변수를 설정하거나 완전한 주소로 바꿔야 합니다. Vertex는 ADC만으로 나타나지 않고 프로젝트 설정이 필요하며, Bedrock은 AWS_REGION만으로 자격 증명이 충족되지 않습니다.
자주 막히는 지점#
모델을 선택할 수 없다면 제공자 설정을 마치고 /models를 확인하세요. 로컬 Ollama 모델이 보이지 않을 때는 서버와 모델의 completion 지원 여부를 공식 오류 안내에 따라 확인할 수 있습니다.
모델 연결을 설정할 때는 지원한다고 적힌 경로와 실제로 연결된 경로가 같은지 확인하는 편이 좋습니다. 무료·로컬·권한은 설치 환경과 계정마다 달라지며, 같은 설정이 다른 사람 환경에서 같은 범위로 실행된다고 가정하지 않습니다. 연결 확인과 첫 작업의 실제 출력을 따로 남기면, 다음에 같은 설정으로 재현할 때 비교 기준이 됩니다. 이 기록은 같은 설정이 환경마다 같은 결과를 내는지를 판단할 때의 출발점이 됩니다.
관련#
편집 메모 (2026-11-02): 모델 연결 경로 표와 무료·로컬·권한 FAQ를 보충했습니다. 기존 버전 출력은 유지했으며 실제 설치·인증·모델·첫 작업 검증으로 확대하지 않았습니다.