AI 코딩 에이전트 OpenCode 설치 및 사용 방법

AI 코딩 도구라고 하면 보통 별도의 편집기나 웹 서비스를 먼저 떠올립니다. 하지만 서버나 원격 개발 환경에서는 터미널을 벗어나지 않고 코드를 살펴보고 수정하는 방식이 더 편할 때가 많습니다.

OpenCode는 터미널에서 자연어로 질문하고, 프로젝트 파일을 분석하거나 코드를 수정할 수 있는 오픈소스 AI 코딩 에이전트입니다. 터미널 인터페이스뿐만 아니라 데스크톱 앱과 IDE 확장도 제공하며, 특정 AI 모델 하나에 묶이지 않고 여러 LLM 제공자를 선택할 수 있습니다.

이번 글에서는 Linux 터미널을 기준으로 OpenCode를 설치하고, AI 모델을 연결한 뒤 사용하는 기본 과정을 알아보겠습니다.

OpenCode란?

OpenCode는 프로젝트 디렉터리 안에서 코드를 읽고, 검색하고, 수정하며 필요한 명령을 실행할 수 있는 AI 코딩 에이전트입니다. 일반적인 챗봇처럼 코드 조각만 답변하는 것이 아니라 현재 프로젝트의 파일과 구조를 문맥으로 사용한다는 점이 특징입니다.

예를 들어 다음과 같은 작업을 자연어로 요청할 수 있습니다.

• 프로젝트 구조와 실행 방법 설명
• 특정 함수나 오류의 원인 분석
• 새로운 기능 구현 및 기존 코드 수정
• 테스트 실행과 실패 원인 확인
• 여러 파일에 걸친 리팩터링
• 변경 사항 검토와 문서 작성

OpenCode는 프로그램 자체가 AI 모델인 것은 아닙니다. OpenAI, Anthropic, OpenRouter, Amazon Bedrock, 로컬 모델 등 사용할 LLM 제공자를 별도로 연결해 사용하는 클라이언트에 가깝습니다.

주요 특징

1. OpenCode 설치

Linux에서는 공식 설치 스크립트를 이용하는 방법이 가장 간단합니다.

curl -fsSL https://opencode.ai/install | bash

설치가 끝나면 새 터미널을 열거나 로그인 셸을 다시 불러옵니다.

exec "$SHELL" -l

다음 명령으로 설치 여부를 확인합니다.

opencode --version

버전 정보가 출력되면 정상적으로 설치된 것입니다.

다른 설치 방법

Node.js가 설치돼 있다면 npm을 이용할 수도 있습니다.

npm install -g opencode-ai

2. OpenCode 실행 및 모델 연결

작업할 프로젝트 디렉터리로 이동한 뒤 OpenCode를 실행합니다.

mkdir opencodetest
cd opencodetest
opencode

OpenCode를 처음 실행했다면 사용할 AI 모델 제공자를 연결해야 합니다. TUI 입력창에서 다음 명령을 실행합니다.

/connect

목록에서 사용할 제공자를 선택한 뒤 화면 안내에 따라 로그인하거나 API 키를 입력합니다. 처음 사용하는 경우 OpenCode에서 안내하는 Zen을 선택할 수 있고, 이미 이용 중인 OpenAI, Anthropic, OpenRouter 등의 제공자가 있다면 해당 항목을 선택하면 됩니다. 저는 사내 LLM API Key를 연결 해보도록 하겠습니다.

provider id : smile serv
API key: 발급받은 사내  LLM API key 입력

커스텀 키를 등록했으므로 직접 사용하는 API 주소와 모델 정보를 opencode.json에 추가해야 합니다.

먼저 오픈코드를 종료한 다음 프로젝트 디렉토리에서 파일을 엽니다

/exit
vi opencode.json

아래 내용을 작성한뒤 저장합니다.

{
"$schema": "https://opencode.ai/config.json",
"provider": {
"smileserv": {
"npm": "@ai-sdk/openai-compatible",
"name": "Smileserv Provider",
"options": {
"baseURL": "https://API-서버-주소"
},
"models": {
"사용할-모델-ID": {
"name": "화면에 표시할 모델 이름"
}
}
}
}
}

저는 gemma4-26b 모델을 사용해보도록 하겠습니다.

저장한뒤에 다시 opencode를 실행하고 다음 명령으로 사용할 모델을 선택합니다.

/models

 3. 프로젝트 초기화

모델 연결을 마쳤다면 프로젝트를 초기화합니다. OpenCode 화면에서 다음 명령을 입력합니다.

/init

OpenCode는 프로젝트의 주요 파일과 구조를 분석한 뒤 루트 디렉터리에 AGENTS.md 파일을 생성하거나 기존 파일을 갱신합니다.

AGENTS.md에는 다음과 같은 프로젝트별 정보를 기록할 수 있습니다.

• 빌드, 실행, 테스트 명령
• 프로젝트 디렉터리 구조
• 코딩 스타일과 이름 규칙
• 수정하면 안 되는 파일이나 디렉터리
• 변경 후 반드시 실행해야 하는 검증 절차

4. 자연어로 명령해보기

초기화가 끝나면 일반적인 채팅처럼 한국어로 질문할 수 있습니다. 

이 프로젝트에 있는 파일들을 확인해줘.@

특정 파일 지정하기

입력창에서 @를 입력하면 현재 프로젝트의 파일을 검색해 대화 문맥에 추가할 수 있습니다.

@opencode.json의 내용을 출력해줘

5. 자주 사용하는 명령

TUI 안에서 셸 명령 실행

메시지 맨 앞에 !를 붙이면 현재 화면에서 셸 명령을 실행하고 결과를 대화에 추가할 수 있습니다.

!git status
!npm test

6. 업데이트 및 제거

OpenCode를 최신 버전으로 업데이트하려면 다음 명령을 사용합니다.

opencode upgrade

삭제 전에 제거될 항목을 확인하려면 --dry-run 옵션을 사용합니다.

opencode uninstall --dry-run

확인 후 제거하려면 다음 명령을 실행합니다.

opencode uninstall

npm이나 Homebrew로 설치했다면 설치에 사용한 패키지 관리자로 제거하는 방법도 있습니다.

마무리

OpenCode는 터미널에서 프로젝트를 분석하고 코드를 수정할 수 있는 오픈소스 AI 코딩 에이전트입니다. 사용하는 모델을 직접 선택할 수 있고, 프로젝트별 규칙과 권한을 설정할 수 있어 로컬 개발 환경뿐만 아니라 원격 서버에서 코드를 살펴볼 때도 활용할 수 있습니다.

AI 코딩 에이전트가 작업을 빠르게 만들어 주는 것은 맞지만, 최종 결과가 항상 올바른 것은 아닙니다. 처음에는 작은 작업부터 맡기고, 수정된 코드와 실행한 명령을 직접 확인하면서 사용하는 것이 좋습니다.

참고 자료

• OpenCode 공식 시작 안내
• OpenCode TUI 사용법
• OpenCode 모델 제공자 설정
• OpenCode 프로젝트 규칙
• OpenCode CLI 명령
• OpenCode GitHub 저장소