VPS에서 OpenCode 설치 및 실행 가이드

OpenCode란 무엇이며 무엇을 설정하는가

OpenCode는 터미널용으로 제작된 오픈 소스 AI 코딩 에이전트입니다. 프로젝트 디렉터리 내부에서 실행하면 코드를 읽고, 변경 사항을 제안하며, 파일을 수정하고, 명령을 실행하는 모든 작업을 터미널 사용자 인터페이스(TUI)에서 수행합니다. MIT 라이선스를 따르며 75개 이상의 모델 제공업체와 연결할 수 있습니다. 2026년 중반 기준으로 약 165,000개의 GitHub 스타를 기록하고 있으며, 현재 가장 많은 스타를 받은 오픈 소스 코딩 에이전트입니다. VPS에서 OpenCode를 실행하려면 전용 권한 없는(unprivileged) 사용자를 생성하여 설치하고, 모델 API 키를 비공개 파일에 저장한 뒤, 연결이 끊겨도 세션이 유지되도록 tmux 내부에서 실행해야 합니다. 이 가이드는 해당 순서대로 정확히 이 과정을 안내합니다.

명칭과 관련하여 혼동을 방지하기 위한 주의 사항이 있습니다. 표준 저장소는 anomalyco/opencode이며 Anomaly 팀(이전 명칭 SST)에서 유지 관리합니다. 이 프로젝트는 과거에 sst/opencode에 위치했습니다. GitHub에는 opencode-ai/opencode라는 이름의 관련 없는 구형 저장소도 존재하므로, 올바른 프로젝트의 문서를 읽고 있는지 확인하십시오. 공식 사이트는 opencode.ai입니다.

왜 OpenCode를 VPS에서 실행해야 하는가

코딩 에이전트 세션은 길게 유지됩니다. OpenCode는 리팩토링이나 테스트 스위트를 처리하는 데 수 분 이상 소요될 수 있는데, 노트북에서 실행 중이라면 덮개를 닫거나 Wi-Fi 연결이 끊기는 순간 작업 도중 세션이 종료됩니다. tmux를 사용하는 VPS에서는 연결을 끊어도 에이전트가 계속 작업을 수행하며, 나중에 다시 접속하여 작업 결과를 확인할 수 있습니다. 이는 tmux를 사용하여 VPS에서 Claude Code 실행하기와 동일한 패턴이며, 에이전트를 노트북에서 분리했을 때 얻을 수 있는 가장 큰 삶의 질 향상 요소입니다.

두 번째 이유는 배치입니다. VPS는 배포하는 코드와 가깝습니다. 저장소, 빌드 도구, 테스트 데이터베이스, 그리고 스테이징 환경이 이미 그곳이나 그 근처에 존재하기 때문입니다. 코드를 수정하고 테스트를 실행하는 에이전트는 해당 테스트가 실제로 수행되는 머신에서 가장 잘 작동합니다. 또한 서버를 직접 제어하므로 다음 섹션에서 다룰 내용처럼 에이전트에게 의도적으로 격리된 환경을 제공할 수 있습니다.

아직 도구를 선택 중이라면, VPS에서 코딩 AI 에이전트 실행하기를 통해 Aider와 Goose를 포함한 더 넓은 범위의 도구들을 비교해 보십시오.

OpenCode를 위한 전용 사용자 생성

가장 먼저 고려해야 할 현실적인 지점은 다음과 같습니다. 코딩 에이전트는 파일을 수정하고 명령어를 실행합니다. 이것이 에이전트의 역할이자 동시에 위험 요소입니다. OpenCode는 빌드, 테스트, 그리고 작업에 필요하다고 판단되는 모든 셸 명령어를 실행하며, 모델의 판단력은 우수하지만 완벽하지는 않습니다. 에이전트가 실행되는 계정은 잘못된 명령어가 도달할 수 있는 권한의 상한선이 되므로, root 계정으로 실행해서는 안 되며 서버 관리자와 동일한 사용자로 실행해서도 안 됩니다.

백그라운드 에이전트와 달리 OpenCode는 대화형으로 동작하므로, 해당 사용자는 실제 셸과 홈 디렉터리가 필요합니다.

sudo useradd --create-home --shell /bin/bash opencode
sudo -iu opencode

에이전트가 작업할 프로젝트는 /home/opencode 하위에 두고, 해당 사용자가 직접 클론하게 하십시오. 이 계정에는 어떠한 sudo 권한도 부여하지 마십시오. 에이전트가 파괴적인 명령어를 실행하더라도 이 계정이 소유한 파일만 삭제할 수 있습니다. 이는 권한이 없는 사용자로 서비스 실행하기와 동일한 논리입니다. 또한 모든 작업은 git 저장소 내부에서 수행하십시오. 저장소를 사용하면 잘못된 수정이 발생하더라도 데이터 손실이 아닌 git revert로 처리할 수 있기 때문입니다.

OpenCode 설치

이 프로젝트는 두 가지 설치 방법을 문서화하고 있습니다. 설치 스크립트를 사용하는 것이 가장 빠르며, opencode 사용자로 실행하면 모든 파일이 해당 사용자의 홈 디렉터리 내에 유지됩니다.

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

다른 모든 경우와 마찬가지로 curl | bash의 일반적인 관례를 따라야 합니다. 운영 중인 서버라면 스크립트를 먼저 다운로드하여 내용을 읽어본 뒤 실행하십시오. 설치가 완료되면 새로운 셸을 시작하여 설치 프로그램이 적용한 PATH 변경 사항이 반영되도록 하고, 바이너리가 응답하는지 확인하십시오.

opencode --version

패키지 관리자를 선호하고 서버에 이미 Node.js가 설치되어 있다면, npm을 통해 시스템 전체에 도구를 설치할 수 있습니다. 이 방법은 모든 사용자의 PATH에 opencode 바이너리를 추가합니다.

sudo npm install -g opencode-ai

어떤 방법을 사용하든 확인 절차는 동일합니다. opencode --version을 실행하면 버전 번호가 출력됩니다. 스크립트 설치 후 command not found가 발생한다면 현재 셸이 업데이트된 PATH를 아직 읽지 못한 상태이므로, 로그아웃한 뒤 opencode 사용자로 다시 로그인하십시오.

API 키를 비공개 파일에 저장하기

OpenCode는 사용하는 모델 제공업체에 따라 키가 필요하며, 이 키는 비용을 발생시킬 수 있으므로 비밀번호처럼 취급해야 합니다. opencode 사용자만 읽을 수 있도록 모드를 600으로 설정한 파일을 생성하고, 셸 기록(shell history)에 남을 수 있는 명령어 입력 대신 해당 파일에 키를 보관하십시오:

install -m 600 /dev/null ~/opencode.env
nano ~/opencode.env

제공업체의 변수를 해당 파일에 넣으십시오. 예를 들어 OpenCode는 표준 제공업체 환경 변수를 인식하므로 ANTHROPIC_API_KEY=... 또는 해당 제공업체에 맞는 변수를 사용합니다. 에이전트를 시작하기 전에 셸에서 해당 파일을 로드하십시오:

set -a; source ~/opencode.env; set +a

OpenCode에는 대화형 방식도 있습니다. TUI 내부의 /connect 명령어를 사용하면 제공업체 추가 과정을 안내받을 수 있으며, 자격 증명은 사용자 홈 디렉터리의 ~/.local/share/opencode/auth.json에 저장됩니다. 이 방식을 선택했다면 chmod 600 ~/.local/share/opencode/auth.json 명령어로 파일이 비공개 상태인지 확인하십시오. 두 방식 모두 명령어 라인에 키가 노출되지 않게 하므로, 하나를 선택하여 일관되게 사용하십시오.

tmux에서 OpenCode 시작하기

tmux는 VPS 설정을 가치 있게 만드는 핵심 도구입니다. SSH 연결이 종료되어도 tmux 세션은 계속 실행되기 때문입니다. 세션을 시작하고 프로젝트 디렉터리로 이동한 뒤 에이전트를 실행하십시오:

tmux new -s opencode
cd ~/my-project
opencode

하단에 프롬프트가 표시되고 인터페이스에 프로젝트 이름이 나타나며 TUI가 열릴 것입니다. 평문으로 작업을 지시하면 에이전트가 파일을 읽고 변경 사항을 제안하기 시작합니다. 작업을 마치고 나가려면 Ctrl-b를 누른 뒤 d를 눌러 세션을 분리(detach)하십시오. 노트북을 닫아도 에이전트는 계속 작동합니다. 나중에 다시 접속하려면 다음 명령을 사용하십시오:

tmux attach -t opencode

세션, 대화 내용, 실행 중인 작업은 모두 이전 상태 그대로 유지됩니다. 이 상태는 네트워크 연결이 끊겨도 유지되지만, 서버가 재부팅되면 초기화되므로 재부팅 후에는 동일한 방식으로 새로운 tmux 세션을 시작해야 합니다. 두 번째 tmux 창을 열어 첫 번째 에이전트와 별도로 다른 에이전트를 실행하는 것도 가능합니다. OpenCode 세션은 서로 독립적으로 동작하지만, 같은 서버의 Claude Code 세션끼리는 서로 메시지를 주고받을 수 있으며, 이는 작업을 분할하는 또 다른 방식입니다.

모델 지정하기

OpenCode는 특정 제공업체에 종속되지 않습니다. AI SDK와 Models.dev 카탈로그를 사용하여 75개 이상의 제공업체를 지원하므로, 동일한 도구로 Anthropic, OpenAI, Google을 비롯한 수십 개의 업체와 로컬 서버까지 모두 사용할 수 있습니다. 가장 빠른 방법은 TUI 내에서 /connect 명령을 사용하는 것입니다. 이 명령은 제공업체 목록을 표시하고 자격 증명을 처리합니다. 커밋하여 재현 가능한 설정을 만들려면 프로젝트 루트에 opencode.json 파일을 생성하고 모델을 provider/model-id로 설정하십시오.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514"
}

로컬 모델도 동일한 파일을 통해 작동합니다. OpenAI 호환 서버라면 무엇이든 제공업체로 선언할 수 있기 때문입니다. 동일한 VPS에서 Ollama를 사용하여 모델을 서비스하는 경우, 설정 파일에서 로컬 API를 가리키도록 하고 모델 이름은 사용자의 환경에서 ollama list 명령으로 확인되는 값을 입력하십시오.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://127.0.0.1:11434/v1" },
      "models": { "your-model-name": { "name": "Local coding model" } }
    }
  }
}

첫날부터 익혀두면 좋은 내장 습관이 하나 있습니다. OpenCode는 Tab 키로 전환할 수 있는 두 가지 에이전트를 제공합니다. 하나는 모든 권한을 가진 기본 에이전트인 Build이고, 다른 하나는 변경 기능을 비활성화한 Plan입니다. 새로운 작업을 시작할 때는 Plan 모드에서 코드를 읽고 접근 방식을 제안받은 뒤, 계획에 동의할 때만 Build로 전환하십시오. 서버 환경에서 읽기 전용으로 먼저 확인하는 것은 저렴한 비용으로 큰 위험을 방지하는 방법입니다. Claude Code는 이를 에이전트가 아닌 권한 모드로 구분합니다. 두 도구를 모두 사용한다면 자동 모드를 기본값으로 설정하는 방식에 관한 문서를 읽어보는 것이 좋습니다. 세션 시작 시 설정된 모드에 따라 감시받지 않는 에이전트가 변경할 수 있는 범위가 결정되기 때문입니다.

영향 범위에 대하여

코딩 에이전트는 수동적인 도구가 아니므로, 이 설정이 무엇을 포함하고 무엇을 포함하지 않는지 명확히 밝힙니다. 이 설정은 파일 손상 가능성을 포함합니다. opencode 사용자는 자신의 홈 디렉터리만 소유하므로, 수정이나 삭제 작업은 해당 경계 내에서 멈춥니다. 또한 자격 증명 노출 가능성도 포함합니다. 암호화 키는 모드 600으로 설정된 단일 파일에 저장되며, 특정 계정 내에 존재합니다. 이 설정은 해당 계정이 합법적으로 수행할 수 있는 작업까지는 제한하지 않습니다. 따라서 프로젝트 디렉터리에 운영 환경 배포용 자격 증명이 있다면 에이전트가 이를 사용할 수 있습니다. 이러한 정보는 에이전트 계정에서 완전히 분리하십시오.

OpenClaw와 같은 게이트웨이 에이전트와 달리, OpenCode는 데몬이 아닌 대화형 터미널 프로그램입니다. 수신 대기 포트를 열지 않으며 장기 실행 서비스도 없으므로, 작성해야 할 systemd 유닛이나 에이전트 자체를 위해 방화벽에서 열어야 할 포트는 없습니다. 격리는 사용자 계정과 프로젝트 디렉터리를 통해 이루어지며, 이것이 본 가이드의 첫 번째 섹션이 가장 중요한 이유입니다.

코딩용 VPS는 여전히 공개 서버이므로, VPS의 SSH 강화에서 설명한 것처럼 루트 로그인 비활성화 및 키 기반 SSH 접속, 기본 거부(default-deny) 방화벽 설정, 정기적인 업데이트와 같은 표준적인 보안 관리가 필요합니다. 또한 에이전트가 생성한 결과물을 검토하십시오. 새로운 기여자가 보낸 풀 리퀘스트를 검토하는 것과 마찬가지로, 변경 사항(diff)을 읽고 나서 푸시하십시오. 최종 결과물을 배포하는 주체는 사용자 본인이기 때문입니다.

마지막으로 도구 자체를 최신 상태로 유지하십시오. OpenCode는 자주 릴리스되며, 서버에서 명령을 실행하는 프로그램인 만큼 업데이트에는 중요한 수정 사항이 포함됩니다. 업데이트는 설치 시와 동일한 경로를 사용합니다. opencode 사용자로 설치 스크립트를 다시 실행하거나, npm을 통해 설치했다면 sudo npm update -g opencode-ai를 실행한 뒤 opencode --version으로 새 버전을 확인하십시오. 가끔 수행하는 1분간의 유지보수가 몇 달 된 빌드에서 이미 해결된 문제를 디버깅하는 것보다 훨씬 경제적입니다.

FAQ

OpenCode에서 유료 API 대신 로컬 모델을 사용할 수 있습니까?

네, 가능합니다. OpenCode는 OpenAI와 호환되는 모든 서버를 공급자로 인식하므로, 같은 VPS에서 Ollama로 구동하는 모델을 사용할 수 있습니다. opencode.json에 로컬 baseURL와 Ollama가 보고하는 모델 이름을 지정하면 됩니다. 다만 하드웨어 사양을 고려해야 합니다. 실제 코딩 작업에 적합한 모델은 상당한 메모리를 요구하므로, 모델을 다운로드하기 전에 서버 사양이 충분한지 확인하십시오.

노트북을 닫은 후에도 OpenCode가 계속 실행되게 하려면 어떻게 해야 합니까?

VPS의 tmux 내에서 실행하십시오. tmux new -s opencode으로 명명된 세션에서 에이전트를 시작한 뒤 Ctrl-b를 누르고 d를 눌러 세션을 분리(detach)하면, SSH 연결이 종료되어도 서버에서 세션이 계속 유지됩니다. 언제든지 tmux attach -t opencode로 다시 연결하면 대화 내용과 실행 중인 작업이 그대로 남아 있습니다. 서버를 재부팅하면 세션이 종료되므로, 재부팅 후에는 새로운 세션을 시작하십시오.

OpenCode가 VPS에서 명령어를 실행하도록 허용해도 안전합니까?

제한된 환경에서 운영한다면 관리 가능합니다. OpenCode를 위해 sudo 권한이 없는 전용 일반 사용자 계정을 생성하고, 모든 수정 사항을 되돌릴 수 있도록 프로젝트를 git으로 관리하십시오. API 키는 모드 600으로 설정된 파일에 저장하고, Build 에이전트가 변경 작업을 수행하기 전에 Plan 에이전트를 사용하여 읽기 전용으로 먼저 검토하십시오. 이렇게 하면 에이전트는 해당 계정이 소유한 파일만 수정할 수 있으며, 서버의 나머지 부분은 안전하게 보호됩니다.

OpenCode와 Claude Code의 차이점은 무엇입니까?

OpenCode는 오픈 소스(MIT)이며 특정 공급자에 종속되지 않습니다. 단일 인터페이스를 통해 로컬 모델을 포함한 75개 이상의 모델 공급자에 연결할 수 있습니다. Claude Code는 Anthropic의 모델을 중심으로 구축된 Anthropic 전용 터미널 에이전트입니다. 여러 공급자를 아우르는 도구가 필요하거나 로컬 모델을 포함한 완전한 자체 호스팅 스택을 원한다면 OpenCode가 적합합니다. 두 도구 모두 동일한 일반 사용자 설정으로 VPS의 tmux 내에서 원활하게 실행됩니다.