7. 첫 실행 성공시키기: 모델 선택과 기본 명령어 실습

인증까지 끝냈다면 이제 진짜 중요한 순간이 왔습니다. 여기서부터는 "로그인 성공"이 목표가 아니라, 내가 원하는 모델을 정확하게 골라 실제 작업에 쓰는 것이 목표입니다.

초보자는 여기서 자주 헷갈립니다. 브라우저 로그인도 됐고, 플러그인도 설치했고, 설정 파일도 넣었는데 막상 실행해 보면 이런 생각이 듭니다.

"그래서 지금 내가 무슨 모델을 쓰고 있는 거지?"

이 장에서는 그 질문에 확실하게 답할 수 있게 만들겠습니다. provider/model 형식을 읽는 법, variant가 왜 중요한지, 범용 모델과 코딩 중심 모델을 어떤 기준으로 고르면 되는지, 그리고 opencode run과 TUI를 어떻게 써야 하는지까지 한 번에 익혀 보겠습니다.¹²³

이번 장의 핵심: 로그인보다 모델 선택이 더 중요하다

OpenCode에서 모델은 보통 provider/model 형식으로 고릅니다. 이 책의 구성에서는 OpenAI OAuth 플러그인을 쓰더라도, 실제로 다루는 provider 이름은 openai입니다. 즉, 모델 문자열은 openai/gpt-5.2처럼 읽으면 됩니다.¹²

여기서 중요한 규칙이 하나 있습니다. 명령줄의 --model 값은 그 실행 한 번에 대해 가장 강한 힌트가 됩니다. 설정 파일에 기본 모델이 적혀 있어도, 지금 실행한 명령에 --model을 붙이면 보통 그 값으로 테스트하는 것이 가장 분명합니다.¹

초반에는 이 규칙이 오히려 편합니다. 설정 파일을 자꾸 고치지 않아도, 실행할 때마다 다른 모델을 시험해 볼 수 있기 때문입니다.

provider/model과 variant를 같이 읽는 법

모델 선택에서 초보자가 가장 먼저 익혀야 할 문법은 아래 두 가지입니다.

첫째는 모델 본체입니다.

openai/gpt-5.2

여기서 openai는 공급자(provider)이고, gpt-5.2는 모델 이름입니다.¹

둘째는 변형값(variant) 입니다.

modern OpenCode에서는 같은 모델에 대해 추론 강도나 성향을 variant로 바꿉니다.

opencode run "hello" --model=openai/gpt-5.2 --variant=medium

반면 legacy 방식에서는 variant가 모델 이름에 붙어 있는 경우가 많습니다.

opencode run "hello" --model=openai/gpt-5.2-medium

겉모습은 다르지만, 본질은 같습니다. 둘 다 "같은 계열 모델을 어느 정도 깊이로 쓰게 할지"를 조절하는 손잡이입니다.²³

초보자 기준에서는 이렇게 기억하면 충분합니다.

• low 쪽은 빠르고 가볍습니다.

• medium은 가장 무난한 기본값에 가깝습니다.

• high 이상은 더 복잡한 작업에 유리하지만 응답이 느려질 수 있습니다.

처음에는 medium으로 시작하는 것이 가장 안전합니다.

범용 모델과 Codex 계열은 어떻게 나눠 생각하면 좋을까

이제 가장 많이 궁금해하는 질문으로 들어가 보겠습니다.

범용 GPT 계열과 codex 계열은 무엇이 다를까요?

이 책의 관점에서 아주 단순하게 나누면 이렇습니다.

• 범용 GPT 계열: 설명, 요약, 구조 파악, 문서화 같은 작업에 무난합니다.

• Codex 계열: 파일 생성, 코드 수정, 여러 단계의 코딩 흐름에 더 잘 맞는 경우가 많습니다.²³

즉, 초보자 기준으로는 이렇게 출발하면 됩니다.

너무 어렵게 생각할 필요는 없습니다. 처음 질문은 범용 모델, 실제 코드 손대기는 codex 계열이라고 기억해도 충분히 쓸 만합니다.

초보자용 첫 선택 규칙

처음 며칠은 아래 규칙으로만 움직여도 실패 확률이 많이 줄어듭니다.

• 그냥 시작할 때는 openai/gpt-5.2 + medium

• 파일을 만들거나 고칠 때는 openai/gpt-5.2-codex + medium

• 여러 파일이 엮인 까다로운 수정은 openai/gpt-5.2-codex + high

이 규칙이 좋은 이유는 단순합니다. 너무 많은 선택지를 한 번에 머리에 넣지 않아도 되기 때문입니다. 초보자에게는 "완벽한 모델 찾기"보다 "실수하지 않는 출발점"이 더 중요합니다.

먼저 가능한 모델 이름부터 확인하자

실행 전에 가장 안전한 습관은 실제로 OpenCode가 인식하는 모델 이름을 먼저 보는 것입니다. CLI에는 이를 위한 명령이 있습니다.¹

opencode models openai

필요하면 캐시를 새로고침할 수도 있습니다.

opencode models --refresh

이 명령은 지금 구성된 provider에서 사용 가능한 모델을 provider/model 형식으로 보여 줍니다. 설정 파일이나 문서에서 본 이름을 내 기억만 믿고 입력하기보다, 이 명령으로 한 번 확인하는 습관이 훨씬 안전합니다.

여기서 중요한 점이 하나 더 있습니다. 화면에 친절한 표시 이름이 보여도, 실제로 CLI에서 중요한 것은 내가 지정하는 모델 키입니다. TUI는 사람이 읽기 쉬운 이름을 보여 줄 수 있지만, 내부적으로 중요한 것은 실제 식별자입니다.²

실습 1: opencode run으로 가장 빠르게 성공하기

첫 실습은 비대화형 실행입니다. opencode run은 TUI를 열지 않고도 바로 한 번 실행해 볼 수 있어서, "연결이 실제로 되는지" 확인할 때 아주 좋습니다.¹

먼저 연습용 폴더를 만듭니다.

mkdir -p ~/opencode-first-run
cd ~/opencode-first-run

1단계: 말만 시켜 보기

가장 먼저는 파일 수정 없이 정말 간단한 응답만 받아 봅시다.

modern 기준 예시입니다.

opencode run "Say exactly: OpenCode 연결 성공" --model=openai/gpt-5.2 --variant=medium

legacy 방식이라면 보통 이렇게 씁니다.

opencode run "Say exactly: OpenCode 연결 성공" --model=openai/gpt-5.2-medium

이 단계의 목적은 거창하지 않습니다. 모델 호출 자체가 되는지 확인하는 것입니다. 여기서 응답이 오면, 인증과 모델 연결은 최소한 한 번은 성공한 셈입니다.¹³

2단계: 파일 하나 만들게 해 보기

이제 진짜로 작은 코딩 작업을 시켜 보겠습니다.

opencode run "Create a file named hello.js that contains a minimal Node.js program printing Hello, OpenCode!" --model=openai/gpt-5.2-codex --variant=medium

실행 뒤 파일이 생겼는지 확인합니다.

ls -l
cat hello.js

보통은 이런 형태의 파일이 만들어집니다.

console.log("Hello, OpenCode!");

이제 직접 실행해 봅니다.

node hello.js

정상이라면 터미널에 아래 문장이 찍힙니다.

Hello, OpenCode!

이 순간이 꽤 중요합니다. 로그인 성공보다 훨씬 의미가 큽니다. 모델이 실제로 파일을 만들고, 그 코드가 실행까지 되는지 확인했기 때문입니다.

3단계: 같은 작업을 다른 모델로 비교해 보기

이번에는 같은 요청을 범용 모델과 codex 계열에 각각 시켜 봅니다.

opencode run "Rewrite hello.js to also print Welcome, beginner! on the next line." --model=openai/gpt-5.2 --variant=medium

opencode run "Rewrite hello.js to also print Welcome, beginner! on the next line." --model=openai/gpt-5.2-codex --variant=medium

둘 다 결과는 비슷할 수 있습니다. 하지만 실제로 여러 파일을 수정하거나 도구 호출이 많아질수록 codex 계열이 더 자연스럽게 느껴질 수 있습니다. 이렇게 같은 작업을 모델만 바꿔 비교해 보는 습관이 생기면, 나중에 어떤 모델이 내 작업 스타일에 맞는지 빨리 감이 옵니다.

실습 2: TUI에서 모델 고르고 대화해 보기

이제 OpenCode의 본진이라고 할 수 있는 TUI로 들어가 보겠습니다. OpenCode는 인수 없이 실행하면 기본적으로 TUI를 시작합니다.¹⁴

opencode

또는 현재 폴더를 명확히 지정해서 이렇게 열어도 됩니다.

opencode ~/opencode-first-run

TUI에 들어갔다면 먼저 /models를 실행해 사용 가능한 모델 목록을 열어 보세요. 여기서 현재 프로젝트에 쓸 모델을 고를 수 있습니다.⁴

/models

모델을 고른 뒤에는 아래 순서로 가볍게 연습하면 좋습니다.

첫 번째 프롬프트:

Read @hello.js and explain this file for a beginner.

여기서 @hello.js는 파일 참조입니다. OpenCode는 @를 사용해 현재 작업 디렉터리의 파일을 찾아 대화 맥락에 넣을 수 있습니다.⁴

두 번째 프롬프트:

Modify @hello.js so it prints the current date after the greeting.

세 번째 프롬프트:

!node hello.js

여기서 !는 셸 명령 실행입니다. 즉, LLM에게 설명만 시키는 것이 아니라 실제로 명령을 돌려 결과를 확인할 수 있습니다.⁴

이 흐름이 중요한 이유는 분명합니다. TUI에서는 단순 채팅이 아니라, 파일 읽기 → 수정 → 실행 확인이 한 자리에서 이어집니다. OpenCode를 그냥 "똑똑한 채팅창"으로 쓰는 것과 "코드 작업 도구"로 쓰는 것의 차이가 여기서 생깁니다.

TUI에서 자주 쓰는 기본 명령어

처음부터 모든 명령을 외울 필요는 없습니다. 하지만 아래 다섯 가지는 금방 손에 익히는 편이 좋습니다.⁴

여기에 @파일명, !명령어까지 익히면 초반 생산성이 꽤 빠르게 올라갑니다.

modern과 legacy에서 모델 고르는 법을 헷갈리지 말자

이번 장에서 제일 흔한 실수가 바로 이것입니다.

최신 방식에서는 아래처럼 모델과 variant를 분리하는 경우가 많습니다.

opencode run "hello" --model=openai/gpt-5.2-codex --variant=high

반대로 legacy에서는 보통 모델 이름 자체에 수준이 붙습니다.

opencode run "hello" --model=openai/gpt-5.2-codex-high

둘을 섞으면 당연히 헷갈립니다. modern 환경인데 legacy 이름으로 입력하거나, legacy 환경인데 --variant가 당연히 먹을 거라고 생각하면 모델 선택에서 삐끗할 수 있습니다.²³

가장 안전한 방법은 간단합니다.

문서 기억보다 opencode models openai 결과를 믿으세요.

실제로 보이는 이름을 쓰는 편이 항상 더 안전합니다.

모델이 안 바뀐 것처럼 보일 때 확인할 것

초보자가 실제로 자주 겪는 상황을 하나 보겠습니다.

설정 파일에는 기본 모델이 적혀 있는데, 나는 다른 모델을 시험하려고 실행할 때 --model을 붙였습니다. 그런데도 헷갈립니다. 지금 뭐가 적용된 걸까요?

이럴 때는 복잡하게 생각하지 말고, 명령줄에서 명시한 값을 우선해서 테스트한다는 원칙을 기억하면 됩니다. 그래서 확실히 구분하고 싶을 때는 --model을 붙여 실행해 보는 편이 좋습니다.¹

또 하나는 TUI의 표시 이름 문제입니다. 화면에서 보이는 이름이 길고 친절하더라도, 내부적으로 중요한 것은 실제 모델 식별자입니다. 그러니 "화면에 보이는 이름"과 "CLI에 넣는 이름"을 혼동하지 않는 것이 좋습니다.²

초보자에게 추천하는 첫 주 모델 운용법

처음 일주일은 욕심내지 말고 아래처럼만 써도 충분합니다.

이 표를 볼 때 중요한 점은 하나뿐입니다. 좋은 모델 하나를 절대 기준으로 찾으려 하지 말고, 작업 종류에 맞는 모델을 찾는 것이 훨씬 현실적이라는 점입니다.

이번 장에서 꼭 기억할 것

이번 장의 핵심은 아주 명확합니다.

OpenCode에 OpenAI OAuth를 연동하는 목적은 로그인 자체가 아닙니다. 내가 원하는 모델을, 원하는 세기로, 원하는 작업에 맞게 고르는 것이 진짜 목적입니다.¹²

모델 문자열은 provider/model 형식으로 읽고, modern 환경에서는 variant를 추가해 조절합니다.¹³ 범용 모델은 설명과 구조 파악에 좋고, codex 계열은 코드 수정과 긴 작업 흐름에서 더 잘 맞는 경우가 많습니다.²³

그리고 가장 실전적인 습관은 두 가지입니다. 먼저 opencode models openai로 실제 모델 이름을 확인하고, 그다음 opencode run으로 가장 작은 성공부터 만들어 보는 것입니다.¹ 거기까지 되면 TUI에서 /models, @파일, !명령어를 사용해 본격적인 작업 흐름으로 넘어갈 수 있습니다.⁴

이제 우리는 "연결됐다"를 넘어서, "제대로 쓸 수 있다"에 도달했습니다. 다음 장에서는 이 감각을 이어서, 정말 초보자다운 작은 실습부터 차근차근 자동화의 재미를 붙여 보겠습니다.

참고

¹OpenCode CLI 문서

²OpenCode Codex Auth Plugin 설정 흐름 문서

³opencode-openai-codex-auth GitHub 저장소

⁴OpenCode TUI 문서