opencode 로 오프라인 사용방법

opencode 로 오프라인 사용방법

작성자:

OpenCode는 로컬 LLM(예: Ollama, gpt-oss 등)을 붙이면 완전 오프라인에서도 사용할 수 있고, 최소한 모델 응답 캐시를 활용하는 반오프라인 모드도 지원합니다. 인터넷 없이 쓰려면 “모델을 내 PC에 깔아서 OpenCode에 연결하는 것”이 핵심입니다.​

전제: 무엇이 필요한가

  • OpenCode CLI 설치 (npm, brew 등으로 설치).​

  • 로컬 LLM 런타임(예: Ollama)과 오프라인 모델 다운로드.​

  • OpenCode 설정에서 모델 프로바이더를 “로컬 엔드포인트”로 지정.​

1. OpenCode 설치

예시는 macOS/Linux 기준입니다.

  • Node 기반 설치 예:

    • npm install -g opencode 형태로 설치 (실제 명령은 GitHub README 참고 필요).​

  • 설치 후 동작 확인:

    • 프로젝트 폴더에서 opencode 실행 → TUI 에이전트 화면이 뜨는지 확인.​

2. 로컬 모델 준비 (완전 오프라인용)

가장 흔한 방식은 Ollama + gpt-oss 같은 모델입니다.​

  1. Ollama 설치 후 실행

  • Ollama 공식 사이트에서 OS에 맞는 설치파일 다운로드 → 설치 후 ollama serve.​

  1. 모델 다운로드

  • 예: ollama pull gpt-oss (또는 사용하려는 다른 코드 특화 모델).​

  1. 로컬 API 엔드포인트

  • Ollama는 기본적으로 http://localhost:11434에서 OpenAI 호환 스타일 또는 자체 API를 제공합니다.​

3. OpenCode를 로컬 모델에 붙이기

OpenCode는 “어떤 HTTP LLM 백엔드든 붙일 수 있는” 구조라, 원격 대신 로컬 엔드포인트로 설정하면 됩니다.​

  • 설정 파일/명령 사용:

    • opencode config 또는 유사 명령으로 모델 프로바이더 설정.​

    • base URL을 http://localhost:11434 등 로컬로 지정.​

    • 모델 이름을 gpt-oss 등 로컬에 내려받은 이름으로 지정.​

  • API 키가 필요 없는 구조라면 key 필드를 비워두거나 dummy 값으로 채워도 됩니다.​

4. 오프라인에서 실제 사용 흐름

인터넷을 끈 상태에서:

  • 프로젝트 디렉터리로 이동 후 opencode 실행.​

  • /init 로 프로젝트 컨텍스트를 스캔 (언어, 프레임워크, 구조 파악).​​

  • Plan/Build 모드:

    • 프롬프트 입력 후 Tab → Plan 모드에서 단계 설계, 다시 Tab → Build 모드에서 파일 수정 적용.​​

  • 모든 LLM 호출은 로컬 Ollama 서버로만 가므로 네트워크 연결이 필요 없음.​

5. 반오프라인(캐시 활용) 모드

GitHub 문서 기준으로 OpenCode는 로컬 캐시나 로컬 모델을 옵션으로 두어 원격 의존도를 줄이는 오프라인 모드 옵션을 언급합니다.​

  • 이전 응답을 디스크에 캐시하여 같은 요청은 네트워크 없이 재사용 가능.​

  • 일부 작업은 로컬 모델로 돌리고, 복잡한 것은 온라인 모델에 보내는 하이브리드 구성도 가능.

opencode 로 오프라인 사용방법

Windows에서 Ollama + OpenCode 조합으로 완전 오프라인 세팅하려면, 아래 순서대로 한 번만 세팅하면 됩니다.​

1. Ollama 설치 및 모델 다운로드

powershell

# PowerShell 관리자 권한 실행 권장

# 1) Ollama 설치 (공식 사이트에서 수동 다운로드)
# https://ollama.com/download/windows 접속 후 OllamaSetup.exe 내려받아 실행
# 설치 후 버전 확인
ollama —version

powershell
# 2) 사용할 로컬 모델 다운로드 (예: qwen3:8b 또는 llama3.1:8b 등)
ollama pull qwen3:8b
# 또는
ollama pull llama3.1:8b
powershell
# 3) Ollama 서버 실행 (기본: http://localhost:11434)
ollama serve

2. OpenCode 설치 (Windows)

Go 바이너리 직접 빌드 방식 예시입니다.​

powershell

# 1) Git, Go 설치 (이미 있다면 생략)

# 2) OpenCode 소스 클론
git clone https://github.com/opencode-ai/opencode.git
cd opencode

# 3) 빌드 (opencode.exe 생성)
go build –o opencode.exe . 

# 4) PATH에 추가 (예시: C:\tools\opencode 로 이동)
mkdir C:\tools\opencode
move opencode.exe C:\tools\opencode\

# PowerShell 프로필 또는 세션에 PATH 추가
$env:Path = “C:\tools\opencode;” + $env:Path

3. OpenCode에 Ollama(로컬) 연결 설정

글로벌 설정 파일 위치 예시: C:\Users\<USER>\.config\opencode\opencode.json.​

powershell
# 1) 설정 디렉터리 생성
mkdir $env:USERPROFILE\.config\opencode# 2) opencode.json 생성
notepad $env:USERPROFILE\.config\opencode\opencode.json

opencode.json 내용 예시 (Ollama를 로컬 OpenAI 호환 프로바이더로 등록):​

json
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama (local)",
"options": {
"baseURL": "http://localhost:11434/v1"
},
"models": {
"qwen3:8b": {
"name": "qwen3:8b"
}
}
}
},
"agents": {
"coder": {
"model": "ollama.qwen3:8b",
"reasoningEffort": "high"
}
}
}

  • baseURL는 Ollama의 OpenAI 호환 엔드포인트 (/v1)를 사용.​

  • 다른 모델을 쓰려면 qwen3:8b 부분만 llama3.1:8b 등으로 교체.​

또는 환경변수 방식(단일 로컬 엔드포인트)도 가능:​

powershell
# 세션에서만 유효
$env:LOCAL_ENDPOINT = "http://localhost:11434/v1"

4. 프로젝트에서 OpenCode 사용 (오프라인 모드)

powershell
# 1) 작업할 프로젝트로 이동
cd C:\path\to\your\project# 2) OpenCode 실행
opencode.exe# 3) TUI 안에서:
# – /init : 프로젝트 스캔 및 컨텍스트 로딩
# – /models : 로컬 모델(ollama.qwen3:8b 등) 선택
# – 평소처럼 프롬프트 입력 후 Plan/Build 사용

이후에는 인터넷을 끄고 ollama serve + opencode.exe만 켜면 완전 오프라인 코드 에이전트 환경이 동작합니다.

 

oh-my-opencode는 bun 기반 CLI로 설치·제거하며, OpenCode 쪽에서는 플러그인 목록에 이름을 넣고 빼는 것만 해주면 됩니다. 아래 순서대로 쓰면 됩니다.​

설치 절차

  1. 사전 준비

    • OpenCode 최신 버전 설치 및 opencode 명령 동작 확인.​

    • Node/Bun 환경 준비 (oh-my-opencode는 bunx로 실행).​

  2. oh-my-opencode 설치 명령

    • 프로젝트 루트(또는 전역 설정만 쓰고 싶으면 아무 디렉터리)에서 실행:

    bash
    bunx oh-my-opencode install

    • 이 명령이 하는 일(요약):

      • oh-my-opencode 패키지를 내려받고.​

      • ~/.config/opencode/opencode.json 또는 해당 프로젝트의 .opencode/opencode.json에 플러그인 항목을 추가합니다.​

  3. 설치 확인

    bash
    opencode --version # 1.0.150 이상 권장
    cat ~/.config/opencode/opencode.json

    • 설정 파일의 plugin 배열 안에 "oh-my-opencode"가 포함되어 있으면 정상 설치입니다.​

삭제(제거) 절차

  1. OpenCode 설정에서 플러그인 제거

    • 글로벌 설정 예시: ~/.config/opencode/opencode.json 또는 opencode.jsonc 열기.​

    • plugin 배열에서 "oh-my-opencode" 항목만 삭제한 뒤 저장.

    • 프로젝트 단위로만 끄고 싶다면 해당 프로젝트 안의 .opencode/opencode.json에서도 같은 작업 수행.​

  2. 패키지 정리(선택 사항)

    • Bun이 설정 디렉터리의 package.json 기준으로 의존성을 설치하므로, 완전히 흔적을 지우고 싶다면:

    bash
    cd ~/.config/opencode
    rm -rf node_modules bun.lockb
    # 필요하다면 package.json에서 oh-my-opencode 관련 의존성 제거

    • 프로젝트 로컬에 설치했다면 그 프로젝트 디렉터리에서도 동일하게 정리합니다.​

  3. 제거 확인

    bash
    cat ~/.config/opencode/opencode.json
    # "oh-my-opencode" 문자열이 더 이상 나오지 않아야 함    opencode
    # 실행 후 로그/상단 배너 등에 oh-my-opencode 관련 문구가 없는지 확인

    • 플러그인 배열과 의존성이 모두 제거되면 oh-my-opencode는 더 이상 로드되지 않습니다.​

​