OpenCode Desktop과 CLI, 어떤 작업에 무엇을 쓰면 좋을까?
OpenCode Desktop과 CLI를 작업 방식, 제공업체 연결, 세션 전환 기준으로 비교합니다. 버전별 오류 점검 방법과 직접 실행할 수 있는 Python 연습도 제공합니다.
세션과 코드 변경 내용을 시각적으로 검토하려면 OpenCode Desktop부터, 터미널·원격 셸·반복 실행하는 스크립트에서 작업을 시작한다면 CLI부터 사용하세요. 둘을 함께 쓸 수도 있습니다. 다만 두 번 로그인하는 것보다 프로젝트 폴더, 서버, 모델이 같은지 확인하는 것이 중요합니다.
이 글은 OpenCode의 두 인터페이스를 비교합니다. OpenAI Codex와 비교하려는 경우에는 OpenCode와 Codex CLI 비교(영문)를 참고하세요.
2026년 11월 17일 기준 문서를 확인하고, 별도 디렉터리에 OpenCode CLI 2.3.0을 설치해 버전과 도움말 출력을 검증했습니다. 다운로드할 수 있는 연습 과제의 Python 테스트도 로컬에서 실행했습니다. 유료 모델 비교나 Desktop에서의 과제 수행은 하지 않았습니다. 아래 인터페이스 동작은 문서에 근거한 설명이며, 어느 쪽이 더 좋은 코드를 생성하는지 측정한 결과가 아닙니다. 이 글은 API 연결 서비스를 제공하는 Ofox가 발행합니다.
끝내야 할 작업을 기준으로 선택하기
| 다음에 할 작업 | 시작할 인터페이스 | 선택 이유 | 확인할 사항 |
|---|---|---|---|
| 로컬 저장소를 살펴보고 여러 변경 사항 검토 | Desktop | 세션과 변경 내용을 시각적으로 보는 방식이 검토 중심 작업에 적합 | 올바른 폴더를 열고 변경을 수락하기 전에 파일 확인 |
| SSH로 개발 머신에서 작업 | CLI | 이미 사용 중인 원격 셸에서 바로 시작 가능 | 자격 증명, 파일, 도구가 해당 머신에 있어야 함 |
| 스크립트나 CI 작업에서 프롬프트 반복 실행 | CLI | opencode run은 대화형 화면을 열 필요가 없음 | 모델, 권한, 출력 처리와 실패 상태 |
| 키보드 조작을 선호하면서 대화도 사용 | CLI TUI | CLI는 스크립트 명령뿐 아니라 대화형 앱이기도 함 | 터미널 표시와 선택한 프로젝트 |
| 하나의 로컬 작업 도중 인터페이스 전환 | 둘 다 가능하되 명확한 인계 필요 | 현재 V2는 공유 로컬 서버 지원 | 실제로 같은 서버와 프로젝트를 사용하는지 확인 |
| 인증 또는 제공업체 오류 해결 | 연결부터 진단 | 화면을 바꿔도 잘못된 키나 지원하지 않는 요청은 해결되지 않음 | 정확한 제공업체, 모델, 엔드포인트와 오류 |
OpenCode 제품 페이지(영문)는 Desktop을 세션·탭·변경 내용 비교가 있는 작업 공간으로, Terminal을 셸이나 원격 서버에서 사용하는 인터페이스로 소개합니다. 이는 유용한 작업 방식의 차이지만, 기반 모델의 능력이 다르다는 증거는 아닙니다.
예를 들어 SSH에서 실패한 테스트를 이미 살펴보고 있다면, 파일 시스템이 다른 로컬 GUI로 옮겨도 큰 도움이 되지 않을 수 있습니다. 반대로 여러 로컬 수정을 검토하는 사람은 대화와 변경 내용을 한 화면에서 보고 싶을 수 있습니다. 어느 쪽을 선택해도 프로젝트 테스트는 실행해야 합니다.
설정 가이드를 따라 하기 전에 버전 확인하기
“Desktop인가 CLI인가”와 “OpenCode 1인가 OpenCode 2인가”는 서로 다른 비교입니다. 버전 불일치가 인터페이스의 한계처럼 보일 수 있습니다.
터미널에서 다음을 실행하세요.
opencode --version
opencode --help
opencode run --help
별도 설치에서는 opencode v2.3.0이 반환됐습니다. 도움말에는 run, session, service, models, auth, debug가 나옵니다. 특히 이 버전의 opencode models에는 제공업체 이름을 받는 위치 인수가 없습니다. 오래된 가이드에서 복사한 명령이 현재 실행 파일에서도 동작한다고 가정하지 마세요.
macOS 또는 Linux에서 npm으로 V2를 새로 설치할 경우, 현재 설치 문서(영문)는 다음 명령을 안내합니다.
npm install -g @opencode/cli
opencode --version
V1을 이미 사용 중이라면 공식 마이그레이션 가이드(영문)를 먼저 읽으세요. 두 세대 모두 opencode 명령을 쓰므로 다른 패키지를 바로 설치하면 기존 명령을 덮어쓰거나 충돌을 일으킬 수 있습니다. Windows에서는 패키지 관리자 명령을 그대로 적용하지 말고 OpenCode가 안내하는 독립 실행형 CLI 다운로드를 사용하세요. Desktop도 macOS, Windows, Linux용으로 제공됩니다.
V2는 지원 대상 V1 설정을 계속 처리하므로 도입 과정에서 모든 파일을 다시 쓸 필요는 없습니다. 다만 플러그인과 서버 통합에는 호환성을 깨는 변경 사항이 있습니다. V2 기본 형식의 제공업체 항목은 providers, package, settings를, 기존 항목은 provider, npm, options를 사용합니다. 검색 결과의 일부를 섞지 말고 중첩된 각 제공업체 항목을 하나의 완전한 형식으로 유지하세요. 작동하는 설정을 변환하기 전에는 백업을 남기세요.
제공업체에 연결한 뒤 모델 선택하기
제공업체가 연결됐는지, 모델이 보이는지, 실제 요청이 성공하는지는 별개의 확인 항목입니다. 첫 단계가 성공했다고 나머지 두 단계까지 확인된 것은 아닙니다.
Ofox에서는 두 인터페이스의 경로를 설명하는 OpenCode 연결 문서부터 시작하세요. API Key 인증 안내에 따라 키를 발급받고, 커밋할 프로젝트 파일이나 스크린샷, 복사해서 공유할 진단 로그에는 넣지 마세요.
Desktop에서 연결하는 경로
Ofox 문서에 나온 순서는 다음과 같습니다.
- Settings → Providers를 열고 Show more providers를 선택합니다.
- Ofox를 검색하고 연결한 뒤 키를 입력합니다.
- Settings → Models에서 Ofox를 검색하고 원하는 모델을 활성화합니다.
- 올바른 프로젝트에 세션을 만들고 세션의 모델 선택 메뉴에서 해당 모델을 고릅니다.
화면이 다르면 계정에 문제가 있다고 판단하기 전에 설치한 릴리스와 현재 제공업체 설정을 확인하세요. 아래 이미지는 영어 Ofox 문서 화면이며, 이번에 Desktop에서 추론을 실행한 화면이 아닙니다.

2026년 11월 17일에 캡처한 문서 화면입니다. 문서 안의 UI는 예시이며 사용자의 컴퓨터에 설치된 버전을 증명하지 않습니다.
CLI에서 연결하는 경로
프로젝트 디렉터리를 열고 opencode를 시작한 다음 /connect로 제공업체를, /models로 모델을 선택합니다. 슬래시 명령은 대화형 인터페이스 안에서 입력해야 하며 일반 셸 프롬프트에 입력하는 명령이 아닙니다.
스크립트에서는 opencode models로 목록을 확인하고 반환된 정확한 식별자를 사용하세요.
opencode run --model 'PROVIDER/MODEL' "Explain the files in this project. Do not edit them."
PROVIDER/MODEL은 실제 모델이 아닌 자리표시자이므로 바꿔야 합니다. 영문 프롬프트는 프로젝트 파일을 설명하되 수정하지 말라는 뜻입니다. 이 명령은 모델 요청을 보내므로 제공업체 요금이 발생할 수 있습니다. 이번에는 로컬 도움말로 옵션만 확인했으며 요청 자체는 실행하지 않았습니다.
요구 사항에 맞으면 내장 Ofox 제공업체를 사용하세요. 사용자 지정 제공업체는 특정 프로토콜이나 엔드포인트를 쓰는 별도 경로이지, Desktop 사용의 필수 조건이 아닙니다. 내장 제공업체와 사용자 지정 제공업체 설명에서 차이를 확인할 수 있습니다. 사용자 지정 경로가 필요하면 현재 OpenCode 제공업체 참조(영문)를 Ofox 문서의 정확한 엔드포인트 및 지원 프로토콜과 대조하세요. 사용자 지정 API 설정 가이드(영문)는 제공업체 등록과 모델 등록의 관계를 설명하지만, 날짜가 있는 버전 예시는 실제 설치 버전에 맞춰 확인해야 합니다.
인터페이스를 전환하면 무엇이 공유될까?
현재 CLI 문서(영문)는 로컬 사용자가 공유하는 백그라운드 서버를 설명합니다. 서버가 세션, 설정, 권한, 통합 기능과 도구 실행을 관리합니다. CLI는 --standalone으로 전용 서버를 쓰거나 --server로 지정한 서버에 연결할 수도 있습니다.
따라서 “같은 노트북을 사용한다”는 것만으로는 인계를 확인하기에 부족합니다. 전용 서버, 다른 계정, 원격 호스트나 다른 프로젝트 경로는 서로 다른 작업 맥락을 가질 수 있습니다.
| 항목 | 전환 시 확인 | 확인하는 이유 |
|---|---|---|
| 파일 | 프로젝트 절대 경로와 현재 파일 내용이 같은지 확인 | 이름이 같은 폴더에도 다른 작업이 들어 있을 수 있음 |
| 서버 | 두 클라이언트가 원하는 서비스에 연결되는지 확인 | 전용 또는 원격 서비스가 자동으로 로컬 공유 서비스가 되지는 않음 |
| 세션 | 가장 최근 항목이 아니라 이어갈 세션 선택 | 최근 기록은 다른 작업일 수 있음 |
| 모델 | 정확한 제공업체와 모델 선택 비교 | 익숙한 표시 이름만으로 같은 경로임을 보장할 수 없음 |
| 권한 | 읽기·수정·실행이 허용된 범위 검토 | 인터페이스 변경은 접근 권한 확대의 허가가 아님 |
| 도구와 환경 | 실제 실행이 이루어지는 머신의 도구 확인 | 로컬 Python이 원격 호스트에도 있다는 뜻은 아님 |
진행 중인 작업을 재시작하지 않고 서비스 상태를 보려면 다음을 사용합니다.
opencode service status
opencode session list
이어갈 프로젝트 디렉터리에서 세션 명령을 실행하세요. CLI 2.3.0의 로컬 도움말은 이를 현재 프로젝트의 최상위 세션 목록을 보여 주는 명령으로 설명합니다. 확인한 것은 명령 정의이며, 인터페이스 간 세션 이전을 직접 검증한 것은 아닙니다.
설정이 서로 다르면 설정 참조(영문)에 따라 관련 프로젝트 및 사용자 설정 위치를 확인하세요. 관리자가 지정한 설정이 우선할 수 있습니다. 두 화면의 동작을 같게 만들려고 관리 정책을 끄지 마세요.
별도 작업 복사본에서 같은 작은 과제 실행하기
비교 연습 파일을 다운로드하세요. 일부러 미완성으로 만든 Python 함수, 테스트 4개, 프롬프트와 편집자가 작성한 참고 풀이가 들어 있습니다. 안내와 프롬프트는 영어입니다. 테스트 자체를 실행할 때는 API Key나 의존성 설치가 필요하지 않습니다.
과제는 대소문자에 관계없이 .csv로 끝나는 파일 이름을 허용하고 .csv.tmp 같은 접미사는 거부하는 것입니다. 범위를 좁힌 코딩 연습이지 소프트웨어 개발 능력 전체를 평가하는 벤치마크가 아닙니다.
- 압축 파일을 두 번 풀어
desktop-check,cli-check처럼 별도의 폴더에 둡니다. - 각 폴더에서
python3 -m unittest -v를 실행합니다. Python 3을python으로 실행하는 시스템이라면 해당 명령을 사용합니다. - 시작 버전에서는 테스트 4개 중 2개가 실패해야 합니다. 에이전트를 사용하기 전에 이 기준을 기록합니다.
- Desktop에서
desktop-check를 열고cli-check에서 CLI를 시작합니다. 같은 제공업체·모델과 동등한 권한을 사용합니다. - 양쪽에 같은 프롬프트를 줍니다. 아래는 다운로드 파일과 같은 영문 원문으로, 함수만 고치고 테스트는 유지하며 실제 결과를 보고하도록 요청합니다.
Read app.py and test_app.py. Update only accepts_csv in app.py so filenames
ending in .csv are accepted case-insensitively. Reject .csv.tmp and names
with no .csv suffix. Do not modify the tests or install dependencies.
Run python3 -m unittest -v and report the result. If Python is unavailable,
say so rather than claiming the tests passed. Explain the exact code change.
각 실행이 끝나면 app.py를 살펴보고 test_app.py가 바뀌지 않았는지 확인하세요. 직접 테스트를 다시 실행했을 때 4개 모두 통과해야 합니다. “수정했습니다”라는 답변만으로 검증이 끝나지는 않습니다. 참고 풀이는 의도한 규칙을 확인하기 위한 것으로, 어느 OpenCode 인터페이스가 생성한 출력도 아닙니다.
로컬에서는 시작 버전의 실패 2개와 참고 풀이의 통과 4개를 확인했습니다. Desktop과 CLI의 소요 시간, 비용, 모델 성공률은 수집하지 않았습니다. 직접 과제를 수행하더라도 그런 관찰값은 결정론적 테스트 결과와 따로 기록하세요. 작은 과제로 작업 방식이 자신에게 맞는지는 알 수 있지만, 한 인터페이스가 언제나 더 빠르거나 정확하다고 증명할 수는 없습니다.
전환을 시험하려면 먼저 진행 중인 작업을 멈추고 인터페이스를 바꾼 다음 앞 표의 6개 항목을 확인하고 이어가세요. 비교 중 두 에이전트가 같은 작업 복사본을 동시에 수정하면 변경 내용이 섞여 결과를 해석하기 어려워집니다.
실패한 계층부터 문제 해결하기
| 증상 | 먼저 확인할 사항 | 다음 조치 |
|---|---|---|
opencode를 찾을 수 없음 | 설치와 셸 PATH | 해당 버전의 설치 방법을 확인하고 PATH가 바뀌었다면 셸을 다시 열기 |
| 복사한 명령이 인수를 거부함 | opencode --version과 해당 명령의 --help | 자격 증명을 교체하기 전에 설치된 세대에 맞는 문법 사용 |
| 제공업체는 연결됐지만 모델이 없음 | 모델 표시 여부, 제공업체 ID와 모델 ID | Desktop 활성화와 CLI 목록 확인, 사용자 지정 등록을 썼다면 등록도 검증 |
| Desktop에는 세션이 있는데 CLI에는 없음 | 프로젝트 경로, 계정과 서버 | 올바른 프로젝트에서 세션 목록을 보고 서비스 상태 확인 |
| 요청이 401을 반환함 | 자격 증명 출처와 대상 엔드포인트 | Ofox 인증 및 요청 오류 안내에 따라 확인하고 오류 보고에 비밀 정보 넣지 않기 |
| 요청이 429를 반환함 | 호출 제한과 응답의 재시도 정보 | 429 재시도 문제 해결 안내(영문) 확인, 화면을 바꿔도 제한은 사라지지 않음 |
| 채팅은 되지만 에이전트 도구가 실패함 | 모델 기능, 프로토콜과 도구 결과 형식 | OpenAI 호환 API 확인 방법으로 일반 채팅과 도구 호출 호환성을 구분 |
업그레이드와 관련된 문제라면 이전 버전, 새 버전, 처음 실패한 작업을 기록하세요. 한 번에 변수 하나씩만 바꾸는 것이 좋습니다. 앱 재설치, 키 교체, 제공업체 설정 변경을 동시에 하면 어떤 조치가 효과가 있었는지 알기 어렵습니다.
로컬 변경을 시각적으로 검토하려면 Desktop, 터미널과 스크립트 중심이라면 CLI부터 시작하세요. 전환이 실제로 도움이 될 때 둘을 함께 유지하면 됩니다. 성공의 기준은 인터페이스가 더 강력해 보이는지가 아니라, 올바른 파일·모델·권한으로 스스로 검증할 수 있는 결과를 얻었는지입니다.


