OpenCode 설치부터 Gemini·OpenAI API 연결까지: 터미널에서 AI 코딩 에이전트 사용하기

개발을 하다 보면 터미널 환경을 벗어나지 않고 AI의 도움을 받아 코드를 작성하고 수정하고 싶을 때가 많다. 특히 프로젝트 규모가 커질수록 단순한 코드 자동완성보다는 기존 소스코드를 분석하고, 여러 파일을 수정하고, 오류 원인을 찾아 해결하는 AI 코딩 에이전트의 필요성이 커진다. 최근에는 IDE에 내장된 AI 기능뿐 아니라 터미널에서 직접 실행하는 AI 코딩 도구도 주목받고 있다. 그중 하나가 바로 오픈소스 AI 코딩 에이전트인 **OpenCode**다. OpenCode는 터미널(TUI), 데스크톱 앱, 웹 인터페이스 등 다양한 환경을 지원하며, Claude, GPT, Gemini 등 여러 AI 모델을 연결해 사용할 수 있다.

이번 글에서는 OpenCode의 개념부터 npm을 이용한 설치, Google AI Studio에서 Gemini 무료 API 키를 발급받는 방법, 그리고 OpenAI API 키를 발급받아 연결하는 과정까지 단계별로 살펴보겠다. 특히 하나의 AI 모델에 종속되지 않고 Gemini와 OpenAI를 필요에 따라 바꿔 사용할 수 있다는 점에 주목해 보자.

1. OpenCode란 무엇인가?

OpenCode는 개발자가 터미널에서 AI와 대화하며 실제 프로젝트 코드를 분석하고 수정할 수 있도록 지원하는 오픈소스 AI 코딩 에이전트다. 일반적인 AI 챗봇은 개발자가 코드를 복사해서 질문하고, 답변으로 받은 코드를 다시 편집기에 붙여 넣는 방식으로 사용한다. 반면 OpenCode는 프로젝트 디렉터리에서 실행하면 현재 작업 중인 소스코드와 파일 구조를 파악하고, 사용자의 요청에 따라 파일을 읽거나 수정하는 작업을 수행할 수 있다. 예를 들어 다음과 같은 작업을 요청할 수 있다.

현재 프로젝트의 전체 디렉터리 구조와 주요 모듈 분석
특정 함수의 실행 흐름과 코드 동작 설명
반복되는 코드를 공통 함수로 리팩토링
컴파일 오류나 런타임 오류의 원인 분석
기존 코드 스타일을 유지하면서 새로운 기능 추가
테스트 코드 작성 및 수정
여러 파일에 걸친 코드 변경 작업

즉, 단순히 코드를 추천하는 도구가 아니라 개발자의 요청을 이해하고 프로젝트 내부에서 실제 작업을 수행하는 에이전트에 가깝다.

OpenCode의 주요 특징

구분	주요 기능
오픈소스	소스코드가 공개된 오픈소스 프로젝트로 자유롭게 활용 가능
다양한 AI 모델	OpenAI, Google Gemini, Anthropic Claude 등 여러 프로바이더 지원
터미널 인터페이스	개발자가 기존 쉘 환경에서 AI와 대화하며 작업 가능
데스크톱 앱	별도의 데스크톱 인터페이스에서도 사용 가능
프로젝트 분석	현재 작업 디렉터리의 파일과 코드 구조를 분석
에이전트 기능	파일 읽기, 코드 수정, 명령 실행 등 여러 단계의 작업 지원

OpenCode의 또 다른 장점은 특정 AI 모델만 사용하도록 제한되지 않는다는 것이다. 예를 들어 간단한 코드 설명이나 반복적인 작업에는 Gemini를 사용하고, 복잡한 로직 분석이나 리팩토링에는 OpenAI 모델을 선택하는 식으로 활용할 수 있다. 공식 홈페이지: https://opencode.ai/

2. OpenCode 설치하기: npm을 이용한 CLI 설치

OpenCode를 설치하기 전에 먼저 Node.js와 npm이 설치되어 있는지 확인해야 한다. Node.js는 JavaScript 실행 환경이며 npm은 Node.js 패키지를 설치하고 관리하는 도구다.

1) Node.js 및 npm 설치 확인

터미널 또는 명령 프롬프트를 열고 다음 명령어를 입력한다.

node -v
npm -v

각 명령어를 실행했을 때 버전 정보가 출력되면 정상적으로 설치된 것이다. 만약 명령어를 인식하지 못한다면 Node.js 공식 홈페이지에서 LTS 버전을 설치하면 된다.

Node.js 공식 홈페이지 바로가기

2) npm으로 OpenCode 설치

현재 OpenCode V2 공식 설치 문서에서 안내하는 npm 설치 명령어는 다음과 같다.

npm install -g @opencode/cli

여기서 -g 옵션은 Global을 의미한다. 특정 프로젝트 내부에 설치하는 것이 아니라 시스템 전역에 설치하므로 어느 디렉터리에서든 opencode 명령어를 실행할 수 있다. 참고로 이전 OpenCode V1 문서에서는 opencode-ai 패키지를 사용하기도 했다. 설치할 때는 현재 사용하려는 버전의 공식 문서를 확인하는 것이 좋다.

3) 설치 확인

설치가 완료되면 다음 명령어를 입력한다.

opencode --version

버전 정보가 정상적으로 출력되면 CLI 설치가 완료된 것이다. 설치 과정에서 권한 오류가 발생하거나 명령어를 찾지 못한다면 npm의 전역 설치 경로와 PATH 환경변수를 확인해야 한다.

3. Gemini 무료 API 키 발급받기

OpenCode를 설치했다면 이제 AI 모델을 연결해야 한다. 먼저 비교적 부담 없이 시작할 수 있는 Google Gemini API부터 살펴보자. 여기서 한 가지 알아둘 점이 있다. 우리가 일반 웹 브라우저에서 사용하는 Gemini 서비스와 개발자가 프로그램에서 호출하는 Gemini API는 서로 다른 서비스다. OpenCode에서 Gemini를 사용하려면 Google AI Studio에서 개발자용 API 키를 발급받아야 한다.

1) Google AI Studio 접속

아래 주소로 접속한다.

Google AI Studio 바로가기

구글 계정으로 로그인한 뒤 API Keys 메뉴로 이동한다.

2) API 키 생성

API Keys 화면에서 다음 과정을 진행한다.

Google AI Studio에 로그인한다.
API Keys 메뉴로 이동한다.
Create API key를 선택한다.
새 프로젝트를 만들거나 기존 프로젝트를 선택한다.
생성된 API 키를 복사한다.

새로운 사용자는 AI Studio에서 프로젝트와 API 키가 자동으로 준비되는 경우도 있다. API 키는 외부에 공개하면 안 된다. 특히 GitHub 등 공개 저장소에 키가 포함된 코드를 올리지 않도록 주의해야 한다.

3) Gemini API 무료 사용 가능 여부 확인

Gemini API의 장점 중 하나는 무료 티어를 제공한다는 점이다. 무료 티어에서는 지원 대상 모델과 사용량 한도 내에서 API를 무료로 호출할 수 있다. 따라서 처음 AI 코딩 에이전트를 테스트하거나 개인 프로젝트에서 활용하기에 적합하다. 다만 모든 Gemini 모델이 무료로 제공되는 것은 아니며, 모델별로 요청 횟수와 토큰 사용량 제한이 다르다. 또한 계정과 프로젝트의 자격 요건에 따라 무료 티어 이용 가능 여부가 달라질 수 있다. 무료 티어의 구체적인 모델 목록과 사용량은 아래 공식 문서에서 확인할 수 있다.

Gemini API 가격 및 무료 티어 확인하기

4) API 키 보안에 주의하기

API 키는 계정에 연결된 사용 권한이므로 다른 사람에게 노출되지 않도록 관리해야 한다. 특히 다음 사항을 지키는 것이 좋다.

API 키가 포함된 파일을 GitHub에 업로드하지 않는다.
공개된 코드나 블로그에 실제 API 키를 붙여 넣지 않는다.
키가 노출되었다면 기존 키를 폐기하고 새로 발급받는다.
사용량과 요청 한도를 주기적으로 확인한다.

4. OpenAI API 키 발급받기

이번에는 OpenAI API를 연결하는 방법이다. Gemini와 달리 OpenAI API는 ChatGPT 구독과 별도의 결제 체계를 사용한다는 점을 먼저 이해해야 한다. 예를 들어 ChatGPT Plus 또는 Pro를 구독하고 있더라도 해당 구독료에 OpenAI API 사용료가 포함되는 것은 아니다. ChatGPT는 웹이나 앱에서 대화하는 서비스이고, OpenAI API는 개발자가 자신의 프로그램이나 외부 도구에서 GPT 모델을 호출할 수 있도록 제공하는 개발자용 인터페이스다.

1) OpenAI Platform 접속

아래 주소로 접속한다.

OpenAI API Platform 바로가기

ChatGPT에서 사용하던 계정으로 로그인할 수 있다.

2) API 프로젝트 확인 및 생성

로그인한 뒤 API Platform의 프로젝트 관리 화면으로 이동한다. 프로젝트는 API 키와 사용 권한, 모델 접근, 사용량 및 비용 등을 관리하는 단위다. 기존 Default 프로젝트를 사용해도 되고, OpenCode 전용 프로젝트를 별도로 생성해도 된다. 별도의 프로젝트를 만들면 OpenCode 사용량을 다른 개발 작업과 구분해서 관리하기 편리하다.

3) API Key 생성

프로젝트 설정에서 API Keys 메뉴로 이동한다. 다음 순서로 진행하면 된다.

OpenAI Platform에 로그인한다.
사용할 프로젝트를 선택한다.
API Keys 메뉴로 이동한다.
Create new secret key를 클릭한다.
키 이름을 입력하고 필요한 권한을 설정한다.
생성된 Secret Key를 복사해 안전한 곳에 보관한다.

API 키는 생성 직후 안전하게 복사해 두는 것이 좋다. 키가 노출되거나 분실되었다면 새 키를 발급받고 기존 키를 폐기하는 방식으로 관리한다. API 키 생성 페이지: OpenAI API Keys

4) OpenAI API 결제 설정

OpenAI API를 사용하려면 API Platform에서 별도로 결제 설정을 확인해야 한다. ChatGPT Plus나 Pro를 사용하고 있더라도 API 사용료는 별도다. API 사용량은 선택한 모델과 입력·출력 토큰 수 등에 따라 달라진다. 따라서 사용하기 전에 가격표를 확인하고, 필요하다면 프로젝트별 사용 한도와 비용 알림 등을 설정하는 것이 좋다.

OpenAI API 결제 설정

OpenAI API 모델별 가격 확인

중요한 점은 ChatGPT 구독료와 API 사용료가 완전히 별개라는 것이다. ChatGPT Plus를 결제했다고 해서 OpenCode에서 OpenAI API를 무제한으로 사용할 수 있는 것은 아니다. 다만 OpenCode의 OpenAI 연결 화면에서 ChatGPT 계정 인증 방식을 지원하는 경우에는 API 키 대신 ChatGPT 계정으로 로그인하는 방법도 선택할 수 있다. 이 방식은 API 사용량이 아니라 해당 ChatGPT 요금제의 사용 정책을 따른다. 이번 글에서는 개발자용 API 키를 직접 발급받아 연결하는 방식을 기준으로 진행한다.

5. OpenCode에 Gemini API 연결하기

이제 발급받은 Gemini API 키를 OpenCode에 연결해 보자.

1) 프로젝트 디렉터리로 이동

터미널에서 작업하려는 프로젝트 폴더로 이동한다.

cd 프로젝트경로

예를 들어 다음과 같이 입력할 수 있다.

cd my-project

프로젝트가 없는 상태라면 테스트용 디렉터리를 만들어도 된다.

mkdir opencode-test
cd opencode-test

2) OpenCode 실행

다음 명령어를 입력한다.

opencode

정상적으로 실행되면 터미널 안에 OpenCode의 TUI(Terminal User Interface)가 나타난다. TUI는 일반적인 명령 프롬프트와 달리 터미널 안에서 대화형 화면을 제공하는 인터페이스다.

3) /connect 명령어로 Gemini 연결

OpenCode 화면 하단의 입력창에 다음 명령어를 입력한다.

/connect

연결 가능한 AI 프로바이더 목록이 나타난다. 목록에서 Google 또는 Google Gemini 항목을 선택한다. 이후 인증 방법을 선택하고 Google AI Studio에서 발급받은 API 키를 입력한다. 연결이 완료되면 Gemini 프로바이더를 사용할 수 있는 상태가 된다.

4) /models 명령어로 모델 선택

API 연결이 완료되었다고 바로 원하는 모델이 자동으로 선택되는 것은 아니다. 다음 명령어를 입력한다.

/models

현재 연결된 프로바이더에서 사용할 수 있는 모델 목록이 표시된다. 여기서 사용하려는 Gemini 모델을 선택한다. 모델 목록과 제공 여부는 OpenCode의 모델 카탈로그 및 API 계정의 접근 권한에 따라 달라질 수 있다.

6. OpenCode에 OpenAI API 연결하기

Gemini 연결을 완료했다면 이번에는 OpenAI API를 추가해 보자. OpenCode는 여러 프로바이더를 연결할 수 있기 때문에 Gemini를 연결한 상태에서 OpenAI를 추가해도 된다.

1) /connect 명령어 실행

OpenCode 입력창에 다시 다음 명령어를 입력한다.

/connect

프로바이더 목록에서 OpenAI를 선택한다.

2) 인증 방식 선택

OpenAI를 선택하면 사용 가능한 인증 방식이 표시될 수 있다. 여기서는 API 키를 직접 입력하는 방식을 선택한다. 인증 방식에서 Manually enter API Key 또는 API Key 입력 항목을 선택한다. 이후 앞에서 OpenAI Platform에서 생성한 Secret Key를 붙여 넣는다.

sk-발급받은_API_KEY

위 코드는 입력 형태를 보여주는 예시일 뿐 실제 API 키가 아니다. 키 입력이 완료되면 OpenCode가 해당 계정의 인증 정보를 저장한다.

3) OpenAI 모델 선택하기

연결이 완료되면 다음 명령어를 실행한다.

/models

목록에서 OpenAI 프로바이더를 선택한 뒤 사용할 수 있는 모델을 확인한다. OpenAI는 모델별로 성능과 가격, 지원 기능이 다르다. 복잡한 코드 분석이나 여러 파일을 수정하는 작업에서는 추론 능력과 코딩 성능을 고려하고, 단순한 코드 설명이나 반복적인 작업에서는 비용 효율성을 함께 고려하는 것이 좋다. 모델 이름은 시간이 지나면서 변경되거나 사용 가능 목록이 달라질 수 있으므로 특정 모델명을 고정하기보다는 현재 OpenCode에 표시되는 목록을 기준으로 선택하는 편이 안전하다.

4) Gemini와 OpenAI 모델 전환하기

두 프로바이더를 모두 연결했다면 작업에 따라 모델을 바꿔 사용할 수 있다.

/models

모델 선택 화면에서 Google 또는 OpenAI 프로바이더를 선택하고 원하는 모델을 지정하면 된다. 이렇게 하면 하나의 코딩 환경에서 여러 AI 모델을 비교하고 활용할 수 있다. 예를 들어 다음과 같은 방식으로 작업을 분리할 수 있다.

작업 유형	활용 모델 예시	선택 기준
간단한 코드 설명	Gemini	빠른 응답과 비용 효율성
프로젝트 구조 분석	Gemini 또는 OpenAI	컨텍스트 처리 능력
복잡한 로직 리팩토링	OpenAI 또는 Gemini	추론 및 코드 수정 능력
반복적인 코드 작업	비용 효율적인 모델	요청량과 API 가격

이는 고정된 성능 순위가 아니라 작업 목적에 따라 모델을 선택하는 예시다. 실제 결과는 모델 버전과 프롬프트, 프로젝트 구조에 따라 달라진다.

7. OpenCode에서 자주 사용하는 명령어

OpenCode를 설치하고 API 연결까지 완료했다면 자주 사용하는 명령어를 알아두면 편리하다.

명령어	기능
`/connect`	AI 프로바이더 및 인증 정보 연결
`/models`	사용 가능한 AI 모델 확인 및 선택
`/init`	프로젝트 분석 및 AGENTS.md 초기화 지원
`/new`	새로운 대화 세션 시작
`/help`	사용 가능한 명령어와 도움말 확인

/init으로 프로젝트 분석하기

개인적으로 가장 먼저 활용해 볼 만한 명령어는 /init이다. 프로젝트 디렉터리에서 OpenCode를 실행한 다음 다음 명령어를 입력한다.

/init

OpenCode는 현재 프로젝트의 구조와 코드 등을 살펴보고, AI가 프로젝트를 이해하는 데 필요한 AGENTS.md 파일을 생성하거나 초기화하는 작업을 지원한다. AGENTS.md는 프로젝트의 개발 규칙과 구조, 코드 작성 시 지켜야 할 사항 등을 AI에게 전달하는 문서다. 예를 들어 다음과 같은 내용을 정리할 수 있다.

프로젝트에서 사용하는 프레임워크와 라이브러리
폴더별 역할과 주요 컴포넌트
코드 작성 및 네이밍 규칙
빌드 및 테스트 방법
수정하면 안 되는 설정이나 주의해야 할 사항

프로젝트에 대한 기본적인 맥락이 정리되면 이후 AI에게 코드를 수정하거나 기능을 추가하도록 요청할 때 더욱 일관된 결과를 얻는 데 도움이 된다.

8. OpenCode를 실제 개발에 활용하는 방법

설치와 모델 연결이 끝났다면 실제 개발 작업에 적용해 보자. OpenCode의 장점은 단순히 질문에 답하는 것이 아니라 프로젝트 내부의 코드를 직접 살펴보고 작업할 수 있다는 점이다.

1) 기존 코드 분석 요청

예를 들어 React 프로젝트에서 다음과 같이 요청할 수 있다.

현재 프로젝트의 전체 구조를 분석해 줘.
각 폴더와 주요 컴포넌트가 어떤 역할을 하는지 설명하고
데이터가 화면에 전달되는 흐름을 정리해 줘.

AI가 프로젝트 파일을 확인하고 주요 구성 요소를 설명하도록 요청하는 방식이다.

2) 코드 리팩토링 요청

다음과 같이 특정 파일의 개선을 요청할 수도 있다.

현재 프로젝트의 Chart 컴포넌트를 분석해 줘.
불필요한 React 리렌더링이 발생하는 부분을 찾아서
useMemo와 useCallback을 활용해 개선해 줘.

기존 기능은 유지하고 수정한 부분을 설명해 줘.

이처럼 변경 범위와 유지해야 할 조건을 구체적으로 전달하는 것이 좋다.

3) 오류 원인 분석

오류가 발생했을 때도 활용할 수 있다.

현재 프로젝트에서 발생하는 오류의 원인을 분석해 줘.
관련 파일과 함수의 호출 흐름을 확인하고
오류가 발생하는 근본적인 원인과 해결 방법을 설명해 줘.

수정하기 전에 먼저 문제 원인을 정리해 줘.

코드를 무조건 수정하도록 요청하기보다 먼저 분석을 요청하면 예상하지 못한 코드 변경을 줄이는 데 도움이 된다.

4) 새로운 기능 추가

기존 프로젝트에 새로운 기능을 추가하는 작업도 가능하다.

현재 프로젝트의 구조와 코딩 스타일을 유지하면서
사용자 검색 기능을 추가해 줘.

기존 API 호출 방식을 재사용하고
검색어가 변경될 때 불필요한 요청이 발생하지 않도록 처리해 줘.

AI가 여러 파일을 수정하는 경우 변경된 파일과 수정 내용을 확인하고 테스트하는 과정이 필요하다.

9. OpenCode 사용 시 주의할 점

AI 코딩 에이전트는 개발 시간을 줄여주는 유용한 도구지만, 모든 작업을 무조건 맡기는 것은 위험할 수 있다. 특히 실제 프로젝트에서 사용할 때는 다음 사항을 주의해야 한다.

1) API 사용료 확인

Gemini 무료 티어는 모델별 사용량 제한이 있으며 OpenAI API는 별도 사용료가 발생할 수 있다. 프로젝트 전체를 반복적으로 분석하거나 많은 파일을 읽게 하면 입력 토큰이 빠르게 증가할 수 있다. 따라서 사용량과 모델별 가격을 확인하면서 활용하는 것이 좋다.

2) 코드 변경 전 Git 커밋

AI가 여러 파일을 수정할 수 있으므로 중요한 작업을 시작하기 전에 Git 커밋을 남겨두는 것을 추천한다.

git status
git add .
git commit -m "before opencode changes"

이렇게 하면 AI의 수정 결과가 마음에 들지 않거나 예상하지 못한 변경이 발생했을 때 이전 상태를 확인하고 복구하기가 쉬워진다.

3) 민감한 정보와 API 키 보호

프로젝트 안에 데이터베이스 비밀번호, 인증 토큰, 개인정보 등이 포함되어 있다면 AI 도구가 해당 파일에 접근할 수 있는지 확인해야 한다. API 키를 소스코드에 직접 입력하거나 공개 저장소에 올리는 것은 피해야 한다.

4) AI가 수정한 코드는 반드시 검증

AI가 제안하거나 수정한 코드가 항상 올바른 것은 아니다. 특히 데이터베이스 변경, 인증·인가, 결제, 운영 서버 설정 등 중요한 영역은 개발자가 직접 검토해야 한다. 파일을 수정하거나 터미널 명령을 실행하기 전에 변경 내용을 확인하고, 테스트와 빌드까지 완료한 뒤 반영하는 것이 안전하다.

마치며: 하나의 터미널에서 여러 AI 모델을 활용하는 개발 환경

OpenCode는 기존 개발 환경을 크게 바꾸지 않고도 AI 코딩 에이전트를 활용할 수 있다는 점에서 매력적인 도구다. 특히 Gemini와 OpenAI API를 각각 연결해 두면 특정 서비스에 종속되지 않고 작업의 성격에 따라 적절한 모델을 선택할 수 있다. 처음 시작한다면 Google AI Studio의 Gemini 무료 티어로 기본적인 사용법을 익히고, 이후 더 다양한 모델을 비교하거나 복잡한 코드 분석이 필요할 때 OpenAI API를 추가하는 방식도 괜찮다. 무엇보다 OpenCode를 단순한 코드 자동완성 도구로 생각하기보다는 프로젝트의 구조를 이해하고, 개발자의 지시에 따라 여러 작업을 수행하는 AI 개발 파트너로 활용하는 것이 중요하다. 터미널 중심의 개발 환경을 선호하거나 기존 IDE에 종속되지 않는 AI 코딩 도구를 찾고 있다면 OpenCode를 직접 설치해 경험해 볼 만하다.

참고 공식 문서

Embedding이란? AI가 텍스트의 의미를 벡터로 이해하는 방법

핵심 키워드: OpenCode, AI 코딩 에이전트, OpenCode 설치, Gemini API, OpenAI API, Google AI Studio, npm 설치, 터미널 AI, AI 개발 도구