AI 튜토리얼

opencode-rust 시작하기: Rust 기반 AI 코딩 에이전트

opencode-rust 설치, 공급자 구성, TUI 및 실행 모드 사용, 에이전트 관리, MCP 도구 연결 방법과 백그라운드 작업 정리 및 프록시 순환과 같은 고급 기능을 알아봅니다.

2026년 10월 14일약 12분 소요

opencode-rust란 무엇인가요?

opencode-rust는 Rust로 구현된 오픈 소스 AI 코딩 에이전트입니다. 터미널 사용자 인터페이스, 단일 명령 실행, HTTP 서버, 웹 지원, 로컬 AI 에이전트 워크플로를 위한 ACP 통합을 제공합니다.

이 엔진은 세션, 도구 실행, MCP, LSP, 프로바이더 라우팅, SQLite 저장소, TypeScript 플러그인 브리지를 결합합니다. Docker나 다른 컨테이너 런타임 없이 실행됩니다. Rust를 사용해 스트리밍 요청 본문, SQLite 기반 대화 기록, 캐시된 도구 스키마, LRU 및 TTL 축출 기능이 있는 디렉터리별 상태 풀을 통해 리소스 사용량을 제한합니다.

설치 방법 선택

지원되는 모든 설치 방법은 opr 명령을 제공하지만, 설치 방식에 따라 명령의 동작이 달라집니다.

npm으로 설치

npm은 Linux, macOS, Windows를 지원하며 현재 플랫폼에 맞는 미리 빌드된 바이너리 패키지를 다운로드합니다. 설치 중에 프로젝트를 컴파일하지 않습니다.

npm install -g opencode-rust

npm 런처는 명령을 엔진으로 전달하는 Node 스크립트입니다. 사용 가능한 플랫폼 패키지에는 macOS ARM64 및 x64, Linux x64 및 ARM64 GNU 빌드, Linux x64 musl, Windows x64 MSVC가 포함됩니다.

Homebrew로 설치

macOS 또는 Linux에서는 다음 명령으로 Homebrew 수식을 설치합니다.

brew install vakandi/tap/opencode-rust

이 방식은 Homebrew 접두사에 opencode 바이너리를 배치하지 않고 opr을 설치하므로, 업스트림 OpenCode CLI를 가리지 않습니다. Homebrew는 소스에서 빌드하므로 Rust 툴체인을 빌드 종속 항목으로 설치합니다.

소스에서 빌드

저장소를 복제하고 설치 프로그램을 실행합니다.

git clone https://github.com/vakandi/opencode-rust.git
cd opencode-rust
./install.sh

설치 프로그램은 릴리스 바이너리를 빌드하고 에이전트 바로 가기와 함께 opr을 설치합니다. Rust 소스와 Cargo 매니페스트 파일의 지문을 생성하므로 변경되지 않은 프로젝트는 다시 빌드하지 않습니다. 항상 다시 빌드하려면 --force를 사용합니다.

Homebrew 또는 소스 설치 프로그램을 사용할 때 opr은 엔진 바이너리 자체입니다. 플래그를 전달할 때는 명시적인 하위 명령을 사용합니다.

opr tui --some-flag

npm을 사용하면 런처가 플래그를 TUI로 전달하므로 opr --some-flag는 다르게 해석됩니다.

환경 준비

설치 방법과 관계없이 플러그인 브리지와 npx를 통한 MCP 서버 실행을 위해 Node.js 18 이상이 필요합니다.

첫 실행 전에 프로바이더 키도 필요합니다. 예를 들어 셸에서 Anthropic 키를 설정합니다.

export ANTHROPIC_API_KEY=sk-ant-...

OpenCode 설정에서 지원하는 프로바이더 및 자격 증명 구성을 사용하세요. 가능한 경우 키를 소스 관리와 셸 기록에 남기지 마세요.

첫 세션 실행

대화형 TUI 시작

다음 명령으로 터미널 인터페이스를 실행합니다.

opr

TUI는 기본 대화형 인터페이스입니다. 활성 에이전트와 모델을 표시하고, 어시스턴트 출력을 스트리밍하며, / 팝업을 통해 명령 완성을 제공합니다.

단일 프롬프트 실행

완료될 때까지 실행되는 자동화된 프롬프트에는 run을 사용합니다.

opr run "check this repo for risks"

단순한 프로바이더 호출과 달리 run은 전체 세션 프롬프트 루프를 실행합니다. 도구가 실행되고, 대기 중인 하위 에이전트가 완료되며, 프로세스가 종료되기 전에 백그라운드 작업이 모두 처리됩니다.

HTTP 서버 시작

HTTP 서버를 통해 엔진을 노출하려면 다음을 실행합니다.

opr serve --port 3000

서버는 동일한 세션 엔진을 사용하며 프로젝트의 HTTP, 스트리밍 및 에이전트 인프라를 지원합니다.

이름이 지정된 에이전트 사용

TUI에는 기본 제공되는 build 및 plan 에이전트가 포함되어 있습니다. build 에이전트는 기본 전체 액세스 개발 에이전트이고, plan은 읽기 전용 분석 및 탐색을 위한 에이전트입니다. TUI에서 Tab을 눌러 에이전트를 전환합니다.

소스 설치 프로그램은 이름이 지정된 에이전트를 위한 바로 가기도 생성합니다.

gilfoyle "fix this failing test"
setbon "write 5 ad hooks"
googlebot "audit my meta tags"

이 바로 가기는 해당 --agent 값을 사용해 하나의 프롬프트를 실행합니다. 프롬프트 없이 호출하면 표준 오류에 사용법을 출력하고 상태 코드 2로 종료합니다.

OpenCode 구성과 ~/.omo/omo.jsonc 또는 ~/.config/omo/omo.jsonc의 oh-my-opencode 에이전트 저장소에서 추가 에이전트를 구성할 수 있습니다. 이 위치의 에이전트 구성은 플러그인 기본값을 재정의할 수 있으며, 표시 이름이 달라도 정규 슬러그를 사용해 에이전트를 일치시킵니다.

프로젝트 및 세션 구성

구성 파일은 작업 디렉터리에서 시작해 상위 디렉터리로 검색하면서 병합됩니다. 지원되는 프로젝트 수준 이름은 다음과 같습니다.

opencode.jsonc
opencode.json
.opencode/opencode.jsonc
.opencode/opencode.json

전역 기본 구성은 ~/.config/opencode/opencode.json 또는 이에 해당하는 JSONC 파일에 저장됩니다. 에이전트 정의는 위에서 설명한 oh-my-opencode 위치에도 저장할 수 있습니다.

세션은 SQLite에 저장되며 생성, 계속하기, 분기, 가져오기 및 내보내기, 부모-자식 관계를 지원합니다. 데이터베이스 위치를 확인하려면 다음을 사용합니다.

opr db path

프록시 풀에서 사용하는 데이터 디렉터리를 비롯한 다른 런타임 위치를 확인하려면 다음을 사용합니다.

opr debug paths

MCP 도구 사용

opencode-rust는 stdio 및 HTTP를 통한 MCP를 지원합니다. MCP 서버는 구성에서 로드되고, 90초의 시작 제한 시간 안에 병렬로 시작되며, 에이전트가 사용하는 동일한 턴별 도구 레지스트리에 등록됩니다.

즉, MCP 서버가 노출하는 도구는 모델에 도달하여 에이전트 턴의 일부로 실행될 수 있습니다. 세션을 시작하기 전에 Node.js와 필요한 MCP 서버 패키지가 사용 가능한지 확인하세요.

이 프로젝트는 MCP stdio 전송에 줄바꿈으로 구분된 JSON을 사용합니다. 이는 LSP의 Content-Length 프레이밍과 다르므로 MCP 서버 구성은 MCP 호환 전송 및 정의를 대상으로 해야 합니다.

백그라운드 작업 완료 확인

run 명령은 백그라운드 작업 정리를 위한 시간 제한을 허용합니다.

opr run --wait-background-timeout 120 "run the requested task"

기본 턴이 끝나면 엔진은 세션이 유휴 상태가 될 때까지 기다리고, oh-my-opencode가 기록한 자식 프레임을 스트리밍하며, 연속 실행 상태를 확인합니다. 기본 시간 제한은 120초입니다.

정리 작업은 멈춰 기다리는 대신 오류를 허용하는 방식으로 종료됩니다. 데이터베이스 누락, 원장 누락, 손상된 JSON, 오래된 활성 항목은 남은 작업이 없는 것으로 처리됩니다. 워크플로에 다른 제한이 필요하면 더 짧거나 긴 시간 제한을 사용하세요.

순환 프록시 구성

엔진에는 주거용 프록시 후보를 순환하는 로컬 HTTP 및 CONNECT 포워더가 포함되어 있습니다. 약 120초마다 가장 오래전에 사용된 업스트림을 선택하고, 사용 전에 후보를 검사하며, 거부된 항목을 격리합니다.

기본 풀 파일의 위치는 다음과 같습니다.

macOS: ~/Library/Application Support/opencode/proxy-pool.txt
Linux: ~/.local/share/opencode/proxy-pool.txt
Windows: %LOCALAPPDATA%\opencode\proxy-pool.txt

데이터 위치를 변경하려면 OPENCODE_PATHS_ROOT를 설정하세요. 결과 풀 경로는 $OPENCODE_PATHS_ROOT/opencode/proxy-pool.txt입니다.

항목은 호스트와 포트를 사용하며, 자격 증명과 메타데이터를 선택적으로 포함할 수 있습니다.

198.51.100.10:8080
203.0.113.24:1080
198.51.100.31:3128:myuser:mypass
203.0.113.77:8000 | note:rotates hourly

파일에는 항목만 입력하세요. 일부 예시에서는 #로 시작하는 줄을 주석으로 표시하지만, 파서는 주석 문법을 구현하지 않으므로 이러한 줄은 형식이 잘못된 항목으로 무시됩니다. 실패한 후보와 소유권 정보는 인접한 proxy-quarantine.json 및 proxy-claims.json 파일에 저장됩니다.

프록시 시작은 프록시 변수를 수동으로 내보내는 대신 opencode_proxy::start()를 통해 수행해야 합니다. 제공자 레지스트리를 구성하기 전에 클라이언트가 프록시 구성을 받아야 합니다. 풀이 비어 있거나 읽을 수 없으면 모든 요청이 실패할 리스너를 시작하는 대신 오류를 반환합니다.

명령어 표면 살펴보기

CLI에는 대화형 사용, 세션, 서비스, 구성, 인증, 에이전트, 디버깅, MCP, 데이터 전송 및 유지 관리용 명령이 포함되어 있습니다.

tui      attach   run      serve    web      acp      models
session  stats    db       config   auth     agent    debug
mcp      export   import   github   pr       upgrade  uninstall
generate version

유용한 run 옵션에는 --continue, --session, --fork, --agent, --format, --title, --dir, --port, --variant, --thinking, --wait-background-timeout이 있습니다.

개발 및 검증

저장소에서 작업하는 경우 다음 명령으로 워크스페이스 테스트와 검사를 실행하세요.

cargo test --workspace
cargo build --release --bin opencode
cargo clippy --workspace --all-targets

저장소는 CLI, 서버, 세션, 에이전트, 도구, 제공자, MCP, 플러그인, LSP, 저장소, TUI, 권한, 경로, 프록시 및 관련 유틸리티용 크레이트로 구성되어 있습니다. 크레이트별 문서는 docs/ 디렉터리에서 확인할 수 있습니다.

맺음말

opencode-rust는 대화형 TUI, 완전한 세션 실행, 구성 가능한 에이전트, MCP 및 플러그인 통합, SQLite 저장소, HTTP 액세스를 제공하는 Rust 기반 OpenCode 엔진입니다. npm, Homebrew 또는 소스 빌드로 시작하고, 제공자 키를 구성한 다음 워크플로에 따라 opr, opr run 또는 opr serve를 사용하세요.

이 프로젝트는 MIT 라이선스로 배포되며 OpenCode 팀과 제휴하지 않습니다.