AI 튜토리얼

로컬 우선 AI 코딩 에이전트를 위한 Shim 설정 방법

Shim을 설치하고 로컬 또는 호스팅 AI 모델을 연결하며, 코딩 에이전트 작업을 실행하고 세션을 관리하는 방법을 알아보세요. Agent Skills를 불러오고 MCP 서버를 구성하며 안전한 권한 설정을 적용하는 방법도 설명합니다. 이 튜토리얼에서는 대화형 제어와 전체 명령줄 인터페이스를 모두 다루고, Shim의 로컬 우선 설계와 보안 경계를 설명합니다.

2026년 11월 3일약 13분 소요

Shim이란?

Shim은 터미널 사용자를 위해 설계된 소형 로컬 우선 AI 에이전트 하네스입니다. 데스크톱 애플리케이션, 백그라운드 데몬, 데이터베이스, Docker, Node.js 또는 Python 없이 지원되는 모델 API, Agent Skills, Model Context Protocol 서버를 연결할 수 있는 공통 인터페이스를 제공합니다.

Shim은 정적 바이너리로 배포되며, 구성에는 일반 JSON을 사용하고 세션에는 추가 전용 JSONL 파일을 사용합니다. API 키는 Shim 구성에 기록하지 않고 환경 변수에서 읽습니다.

Shim은 하네스이지 추론 엔진이 아닙니다. 로컬 모델 가중치는 Ollama, LM Studio, llama.cpp 또는 호환 가능한 다른 서비스와 같은 추론 서버를 통해 실행해야 합니다. 호스팅 모델은 지원되는 HTTP API를 통해 제공되어야 합니다.

주요 기능

대화형 및 명시적 제어: 일반 언어로 관리 요청을 입력하거나 완전한 스크립트 가능한 CLI를 사용합니다.
로컬 명령 라우팅: 선택적 로컬 미니 모델이 관리 요청을 허용 목록에 등록된 Shim 명령으로 변환할 수 있습니다.
다중 모델 제공자: Shim은 OpenAI 호환 API, Anthropic Messages, 로컬 제공자 프리셋 및 사용자 지정 엔드포인트를 지원합니다.
Agent Skills: SKILL.md 파일을 검색하고 필요할 때만 전체 지침을 로드합니다.
MCP 통합: stdio 또는 Streamable HTTP MCP 서버에 연결하고 해당 도구를 에이전트에 제공합니다.
권한 제어: 읽기 전용, 확인 후 실행 또는 자동 실행을 선택할 수 있습니다.
이식 가능한 상태: 구성과 세션에 일반 JSON 및 JSONL 파일을 사용합니다.
텔레메트리 없음: 네트워크 활동은 명시적인 모델 호출, 스킬 다운로드, 로컬 검색 및 구성된 MCP 서버로 제한됩니다.

Shim 설치

옵션 1: 릴리스 다운로드

Shim 릴리스 페이지에서 Windows, macOS 또는 Linux용 정적 바이너리를 다운로드합니다. 실행 파일을 시스템 PATH에 넣은 다음 Shim을 초기화합니다.

shim setup
shim

PowerShell에서 현재 디렉터리의 다운로드한 실행 파일을 직접 실행할 때는 .\shim.exe를 사용합니다.

옵션 2: Go로 설치

Go 1.25 이상을 사용할 수 있다면 다음 명령으로 Shim을 설치합니다.

go install github.com/Balanov/shim/cmd/shim@v0.1.0
shim setup

옵션 3: 소스에서 빌드

저장소를 복제하고 테스트를 실행한 다음 바이너리를 빌드합니다.

git clone https://github.com/Balanov/shim.git
cd shim
go test ./...
go build -trimpath -ldflags="-s -w" -o shim ./cmd/shim
./shim setup

저장소에는 Windows용 scripts/build.ps1와 Unix 시스템용 scripts/build.sh도 포함되어 있습니다.

모델 연결

로컬 모델 서버 검색

Ollama, LM Studio, llama.cpp 또는 호환 가능한 다른 로컬 서버가 이미 실행 중이라면 Shim에 사용 가능한 모델을 검색하고 구성하도록 요청합니다.

shim model discover --add

Shim에는 모델 가중치가 포함되어 있지 않으며, 몰래 다운로드하지도 않습니다. 로컬 모델 실행은 계속해서 모델 서버가 담당합니다.

호스팅 제공자 추가

Shim에는 OpenAI, OpenRouter, Anthropic, Gemini, GitHub Models, Hugging Face 및 여러 로컬 제공자를 위한 프리셋이 포함되어 있습니다. 모델을 추가하기 전에 제공자의 자격 증명을 환경에 설정합니다.

예를 들어 PowerShell 사용자는 다음과 같이 OpenRouter를 구성할 수 있습니다.

$env:OPENROUTER_API_KEY = "..."
shim model add openrouter your/model --name main --use
shim model test main

다른 자격 증명 변수로는 OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, GITHUB_TOKEN 및 HF_TOKEN이 있습니다. 영구 자격 증명에는 운영 체제 또는 셸의 표준 비밀 관리 방식을 사용합니다. Shim 프로젝트 구성에 API 키를 넣지 마세요.

호스팅 모델을 추가하는 예시는 다음과 같습니다.

shim model add openrouter anthropic/claude-sonnet-4.5 --name claude --use
shim model add openai gpt-5 --name gpt --use
shim model add huggingface org/model --name hf --use

사용자 지정 엔드포인트 추가

지원되는 OpenAI 호환 엔드포인트라면 기본 URL과 모델 식별자를 지정합니다.

shim model add custom my-model --name mine \
  --base-url http://127.0.0.1:8000/v1 --use

사용자 지정 제공자는 OpenAI 호환 어댑터 또는 Anthropic 어댑터를 사용할 수 있습니다. 사용자 지정 서비스에서는 자격 증명을 선택적으로 구성할 수 있습니다.

첫 에이전트 작업 실행

일회성 실행 사용

저장소를 검사하는 가장 안전한 방법은 읽기 전용 실행입니다.

shim run --read-only "explain this repository"

파일을 편집하고 검증 명령을 실행해야 하는 작업에는 --yes를 사용해 해당 실행의 작업을 승인하고, 추가 출력을 확인하려면 --verbose를 사용합니다.

shim run --yes --verbose "fix the tests and verify the result"

작업 공간, 모델 및 요청된 작업을 신뢰할 수 있을 때만 --yes를 사용합니다.

대화형 터미널 시작

하위 명령 없이 Shim을 실행하면 대화형 세션이 시작됩니다.

shim

그런 다음 다음과 같은 에이전트 요청을 입력할 수 있습니다.

fix the failing tests in this repository

shim help를 실행하면 전체 명령 목록을 확인할 수 있습니다.

일반 언어로 Shim 제어

Shim은 일반적인 영어 및 러시아어 관리 작업에 대한 결정론적 오프라인 구문을 인식합니다. 다른 언어를 사용하거나 더 유연한 해석이 필요하다면 모델을 명령 라우터로 구성합니다.

shim router use ollama/qwen3:4b

라우터는 명령이 아닌 채팅 텍스트를 받아 구성 요청인지 일반 에이전트 작업인지 판단합니다. 변경을 수행하는 명령을 제안하면 Shim은 실행 전에 확인을 요청합니다.

라우팅을 컴퓨터 내부에서 유지해야 한다면 루프백 모델 엔드포인트를 사용하세요. 라우터는 명령 해석만 담당하며, 선택된 기본 모델이 지원하는 언어로 일반 대화를 처리합니다.

에이전트 스킬 추가

Shim은 구성 파일과 같은 위치의 전역 skills/ 디렉터리와 작업 공간 디렉터리인 .shim/skills/, .agents/skills/, .claude/skills/에서 SKILL.md 파일을 검색합니다.

처음에는 스킬 이름과 설명만 시스템 프롬프트에 추가됩니다. 전체 지침은 load_skill을 통해 필요할 때 로드되므로 불필요한 프롬프트 내용을 줄일 수 있습니다.

저장소 참조, GitHub URL 또는 로컬 경로에서 스킬을 추가하세요.

shim skill add owner/repository
shim skill add https://github.com/owner/repository
shim skill add ./local/skill-or-collection

다음 명령으로 설치된 스킬을 확인하고 관리할 수 있습니다.

shim skill list
shim skill show name
shim skill remove name

스킬은 신뢰할 수 없는 지침입니다. 특히 셸 실행이나 네트워크 액세스를 요청하는 경우 사용 전에 검토하세요.

MCP 서버 연결

Stdio 서버 추가

다음 예제는 현재 디렉터리에 대한 MCP 파일 시스템 서버를 등록하고, 해당 도구를 나열한 다음, 도구 하나를 직접 호출합니다.

shim mcp add filesystem npx -y @modelcontextprotocol/server-filesystem .
shim mcp tools filesystem
shim mcp call filesystem list_allowed_directories '{}'

Streamable HTTP 서버 추가

이름과 URL을 지정하여 원격 Streamable HTTP 엔드포인트를 등록하세요.

shim mcp add internal https://mcp.example.com/mcp

다음 명령으로 구성된 서버를 나열하거나 제거할 수 있습니다.

shim mcp list
shim mcp remove filesystem

MCP 도구는 mcp_filesystem_list_allowed_directories와 같은 이름으로 노출됩니다. 기본 권한 모드에서는 MCP 호출에 확인이 필요합니다.

Shim의 JSON 구성에서 HTTP 헤더와 stdio 환경 변수를 추가할 수 있습니다. 값은 ${ENV_VAR} 확장을 지원하므로 구성 파일 대신 환경 변수에 비밀을 보관할 수 있습니다.

권한 모드 선택

Shim의 기본 모드는 ask입니다. 작업 공간 파일 읽기, 나열, 검색은 허용되지만 파일 쓰기, 편집, 셸 명령, MCP 호출에는 확인이 필요합니다.

다음 명령으로 전역 권한 정책을 선택하세요.

shim permissions read-only
shim permissions ask
shim permissions auto

read-only: 쓰기, 셸 명령, MCP 호출을 비활성화합니다.
ask: 중요한 작업에 대해 확인을 요청합니다.
auto: 확인 프롬프트 없이 에이전트가 작업하도록 허용합니다.

일시적인 변경에는 전역 기본값을 수정하는 대신 shim run --read-only 또는 shim run --yes를 사용하세요.

Shim은 운영 체제 수준의 샌드박스가 아닙니다. 셸 명령과 MCP 서버는 사용자 계정의 권한으로 실행됩니다. 신뢰할 수 없는 작업에는 컨테이너, 가상 머신 또는 운영 체제 샌드박스를 사용하세요.

Shim의 파일 도구는 작업 공간에서 어휘적 경로 탐색과 심볼릭 링크를 통한 이탈을 거부하지만, 이러한 검사는 악성 프로세스를 격리할 수 없습니다. 모델 출력, 저장소 콘텐츠, 스킬, MCP 응답을 신뢰할 수 없는 데이터로 취급하세요.

세션 및 구성 관리

세션을 확인하거나, 새 세션을 시작하거나, 이전 세션을 계속 진행하세요.

shim session list
shim session new
shim run --resume SESSION_ID "continue"

문제 해결 시 진단 및 구성 명령을 사용하세요.

shim status
shim doctor
shim config path
shim config show

주 구성 파일은 운영 체제의 사용자 구성 위치 아래 shim/config.json에 있습니다. SHIM_CONFIG 환경 변수 또는 --config 옵션으로 경로를 재정의할 수 있습니다. 세션 기록은 구성 파일과 같은 위치에 추가 전용 JSONL 파일로 저장됩니다.

고급 팁

읽기 전용 모드로 시작하세요. 편집이나 명령 실행을 허용하기 전에 저장소를 분석할 때 --read-only를 사용하세요.
모델 구성을 테스트하세요. 공급자를 추가한 후 shim model test NAME을 실행하여 연결과 인증 정보를 확인하세요.
라우팅을 로컬에서 유지하세요. 자연어 명령 분류를 컴퓨터 내부에 유지해야 한다면 루프백 모델을 라우터로 지정하세요.
MCP 비밀 정보에는 환경 변수 확장을 사용하세요. 비밀 값을 직접 저장하는 대신 구성에서 ${ENV_VAR}를 참조하세요.
실행별 권한을 우선하세요. 전역 정책을 auto로 유지하는 대신 개별 작업에 --read-only와 --yes를 사용하세요.
타사 지침을 검토하세요. 다운로드한 스킬을 점검하고 셸, 파일 시스템 또는 네트워크 액세스 권한을 부여하기 전에 MCP 서버의 동작을 고려하세요.
먼저 진단을 실행하세요. shim status 및 shim doctor와 같은 명령은 에이전트를 실행하기 전에 구성 문제를 식별하는 데 도움이 됩니다.

결론

Shim은 지원되는 모델 API, Agent Skills, MCP 서버를 연결하는 간결한 터미널 계층을 제공합니다. 정적 바이너리, 일반 파일 구성, 환경 기반 인증 정보, 명시적 권한 모드를 제공하므로 가볍고 검토 가능한 AI 에이전트 워크플로를 원하는 사용자에게 적합합니다. 읽기 전용 작업으로 시작하고, 각 공급자 또는 도구를 확인한 뒤, 필요한 경우에만 더 광범위한 권한을 부여하세요.