opencode CLI 실무 명령어 정리 — 세션·서버·MCP·플러그인
opencode CLI의 실행 모드, 세션 관리, 헤드리스 서버, MCP·ACP 연동, 운영 명령을 실전 예제로 정리한 레퍼런스
2026-08-12 · 최초 발행 2026-04-26
opencode는 터미널에서 AI 에이전트를 돌리는 CLI다. 버전과 도움말부터 확인한다.
# 버전 확인
opencode --version
# 도움말
opencode --help
opencode <command> --help기본 실행: TUI와 run
인자 없이 실행하면 현재 디렉토리를 기준으로 TUI 인터랙티브 모드가 뜬다. 경로를 지정하면 그 프로젝트를 대상으로 열린다.
# 현재 디렉토리에서 실행 (기본)
opencode
# 특정 프로젝트 경로 지정
opencode /path/to/project
opencode ~/Work/my-projectTUI를 거치지 않고 한 번에 메시지를 던지고 싶으면 run을 쓴다. 모델이나 에이전트를 지정해 실행할 수도 있다.
# 단일 메시지 전달
opencode run "이 코드의 버그를 찾아줘"
# 여러 단어 메시지
opencode run 리팩토링 계획 세워줘
# 특정 모델로 실행
opencode run --model anthropic/claude-opus-4-7 "아키텍처 리뷰해줘"
# 특정 에이전트로 실행
opencode run --agent code-reviewer "PR 리뷰해줘"이전 세션을 이어가거나 분기하는 것도 명령행 옵션 하나로 끝난다.
# 마지막 세션 계속
opencode --continue
opencode -c
# 특정 세션 계속
opencode --session <sessionID>
opencode -s abc123
# 세션 포크 (기존 세션 유지하며 새 분기 생성)
opencode --continue --fork
opencode -s abc123 --fork서버 모드: 헤드리스·웹 UI·원격 연결
opencode serve는 CI/CD 파이프라인이나 API 통합에 맞춘 백그라운드 헤드리스 서버다. mDNS를 켜면 로컬 네트워크에서 서비스가 자동으로 검색된다.
# 기본 헤드리스 서버 시작
opencode serve
# 포트 지정
opencode serve --port 3000
# 외부 접근 허용
opencode serve --hostname 0.0.0.0 --port 3000
# mDNS 서비스 디스커버리 활성화 (로컬 네트워크 자동 검색)
opencode serve --mdns
# 커스텀 mDNS 도메인
opencode serve --mdns --mdns-domain myteam.local브라우저 UI가 필요하면 web을 쓴다.
# 서버 시작 후 브라우저 자동 열기
opencode web
# 포트 지정
opencode web --port 8080이미 떠 있는 서버에는 attach로 URL을 지정해 붙는다.
# URL로 서버에 연결 (Attach 모드)
opencode attach http://localhost:3000
opencode attach http://192.168.1.100:3000세션 관리: 조회·백업·복원·통계
세션 서브커맨드로 목록을 보거나 특정 세션을 들여다볼 수 있다.
# 세션 관리 명령어 (서브커맨드 포함)
opencode session
# 세션 목록 보기
opencode session list
# 특정 세션 상세 보기
opencode session show <sessionID>세션은 JSON으로 내보내고 파일이나 URL에서 다시 불러올 수 있다.
# 현재(마지막) 세션 JSON으로 내보내기
opencode export
# 특정 세션 내보내기
opencode export <sessionID>
# 파일로 저장
opencode export <sessionID> > session-backup.json
# JSON 파일에서 가져오기
opencode import session-backup.json
# URL에서 직접 가져오기
opencode import https://example.com/session.json토큰 사용량과 비용은 stats로 확인한다.
# 전체 사용량 통계 (토큰 수, 비용)
opencode statsAI 프로바이더와 모델 관리
프로바이더 인증은 providers(별칭 auth)로 관리한다.
# 프로바이더 관리 (aliases: auth)
opencode providers
opencode auth
# 특정 프로바이더 인증 설정
opencode providers add anthropic
opencode providers add openai사용 가능한 모델은 models로 조회하고, 프로바이더별로 필터링할 수 있다.
# 전체 모델 목록
opencode models
# 특정 프로바이더 모델만
opencode models anthropic
opencode models openai
opencode models google실행 시점에 모델을 지정할 때는 provider/model 형식을 그대로 쓴다.
# provider/model 형식
opencode -m anthropic/claude-sonnet-4-6
opencode -m openai/gpt-4o
opencode -m google/gemini-2.0-flash
# run 명령어와 함께
opencode run -m anthropic/claude-opus-4-7 "복잡한 아키텍처 분석해줘"에이전트와 플러그인
등록된 에이전트 목록을 보고 특정 에이전트로 실행을 지정할 수 있다.
# 에이전트 목록 조회
opencode agent
# 에이전트 목록 보기
opencode agent list
# 특정 에이전트로 실행
opencode --agent <agent-name>
opencode run --agent code-reviewer "코드 리뷰해줘"플러그인은 npm 패키지 형식이나 로컬 모듈 경로로 설치한다.
# 플러그인 설치 (aliases: plug)
opencode plugin <module>
opencode plug <module>
# npm 패키지 형식
opencode plugin @opencode/plugin-name
# 로컬 모듈
opencode plugin ./my-plugin외부 플러그인의 영향을 배제하고 순수 환경에서 실행하려면 --pure를 붙인다.
# Pure 모드 (플러그인 비활성화)
opencode --pure
opencode run --pure "순수 환경에서 실행"GitHub 연동
github 서브커맨드로 GitHub 에이전트를 관리한다.
# GitHub 에이전트 관리
opencode githubopencode pr <번호>는 GitHub에서 PR 정보를 가져와 해당 브랜치를 로컬에 체크아웃한 뒤, 그 컨텍스트로 opencode를 실행하는 흐름을 한 번에 처리한다.
# PR 번호로 브랜치 체크아웃 후 opencode 실행
opencode pr 42
opencode pr 123
# 내부적으로 수행하는 작업:
# 1. GitHub에서 PR 정보 가져오기
# 2. PR 브랜치 로컬 체크아웃
# 3. 해당 브랜치 컨텍스트로 opencode 실행MCP 서버 관리
MCP(Model Context Protocol) 서버는 외부 도구를 에이전트에 연결하는 통로다.
# MCP 서버 관리
opencode mcp
# MCP 서버 목록
opencode mcp list
# MCP 서버 추가
opencode mcp add <name> <command>
# MCP 서버 제거
opencode mcp remove <name>ACP 서버
Agent Client Protocol 서버는 외부 클라이언트가 opencode 에이전트에 연결할 때 띄운다.
opencode acp
# 포트 지정
opencode acp --port 4000운영과 유지보수
버전 업그레이드는 최신 또는 특정 버전을 지정해서 할 수 있다.
# 최신 버전으로 업그레이드
opencode upgrade
# 특정 버전으로 업그레이드
opencode upgrade 1.2.3
opencode upgrade latest쉘 자동완성 스크립트는 셸별로 생성해 각 설정 파일에 붙인다.
# bash 자동완성 스크립트 생성
opencode completion bash >> ~/.bashrc
# zsh 자동완성
opencode completion zsh >> ~/.zshrc
# fish
opencode completion fish >> ~/.config/fish/completions/opencode.fish디버깅은 전용 도구와 로그 옵션으로 처리한다.
# 디버그 도구
opencode debug
# 로그 출력 활성화
opencode --print-logs
# 로그 레벨 설정
opencode --log-level DEBUG
opencode --log-level INFO
opencode --log-level WARN
opencode --log-level ERROR데이터베이스 관련 도구는 db 서브커맨드로 들어간다.
opencode db설정 파일까지 포함해 완전히 제거하려면 uninstall을 쓴다.
# opencode 완전 제거 (설정 파일 포함)
opencode uninstall전역 옵션 레퍼런스
| 옵션 | 단축키 | 기본값 | 설명 |
|---|---|---|---|
--help |
-h |
— | 도움말 표시 |
--version |
-v |
— | 버전 표시 |
--model |
-m |
— | 사용할 모델 (provider/model) |
--continue |
-c |
— | 마지막 세션 이어서 실행 |
--session |
-s |
— | 특정 세션 ID로 이어서 실행 |
--fork |
— | — | 세션 포크 (--continue / -s와 함께) |
--agent |
— | — | 사용할 에이전트 이름 |
--prompt |
— | — | 사용할 프롬프트 |
--pure |
— | false |
외부 플러그인 없이 실행 |
--port |
— | 0 (자동) |
리스닝 포트 |
--hostname |
— | 127.0.0.1 |
리스닝 호스트명 |
--mdns |
— | false |
mDNS 서비스 디스커버리 활성화 |
--mdns-domain |
— | opencode.local |
mDNS 커스텀 도메인 |
--cors |
— | [] |
CORS 허용 추가 도메인 |
--print-logs |
— | — | 로그를 stderr로 출력 |
--log-level |
— | — | 로그 레벨 (DEBUG/INFO/WARN/ERROR) |
실전 레시피
CI 파이프라인에서 PR 머지 전 코드 리뷰를 자동화하려면 run에 모델과 에이전트를 함께 지정한다.
#!/bin/bash
# PR 머지 전 자동 코드 리뷰
opencode run \
--model anthropic/claude-sonnet-4-6 \
--agent code-reviewer \
"변경된 파일들의 보안 취약점과 코드 품질을 검토해줘"팀 내부 네트워크에서는 mDNS와 CORS 설정을 함께 걸어 서버를 공유한다.
# 팀 내부 네트워크에서 mDNS로 서버 공유
opencode serve \
--mdns \
--mdns-domain myteam.local \
--cors http://team-dashboard.local
# 팀원 접속
opencode attach http://opencode.myteam.local중요 세션은 날짜를 붙여 백업해두면 복원이 간단하다.
# 중요 세션 백업
opencode export $(opencode session list | head -1 | awk '{print $1}') \
> backup-$(date +%Y%m%d).json
# 복원
opencode import backup-20260423.json같은 작업을 두 모델로 각각 포크해서 비교하는 것도 세션 포크로 처리한다.
# 같은 작업을 두 모델로 포크 비교
SESSION_ID=$(opencode session list | head -1 | awk '{print $1}')
opencode run -s $SESSION_ID --fork \
-m anthropic/claude-opus-4-7 "이 알고리즘의 시간복잡도를 최적화해줘"
opencode run -s $SESSION_ID --fork \
-m anthropic/claude-sonnet-4-6 "이 알고리즘의 시간복잡도를 최적화해줘"문제가 재현될 때는 디버그 로그를 파일로 캡처해두면 나중에 추적하기 쉽다.
# 문제 재현 시 전체 로그 캡처
opencode --print-logs --log-level DEBUG run "문제가 발생하는 작업 실행" \
2> opencode-debug-$(date +%Y%m%d-%H%M%S).logopencode <command> --help로 각 서브커맨드의 세부 옵션을 바로 확인할 수 있다.