무료 AI 코딩 설정, OpenCode·NVIDIA·Claude Code 연결

추가 구독 없이 AI 코딩을 시작하는 경로로 OpenCode의 NVIDIA 연결과 FCC의 fcc-claude를 살펴볼 수 있습니다. 먼저 실행 화면과 답을 만드는 모델을 나눠야 합니다. OpenCode와 Claude Code는 코딩 도구이고, NVIDIA 같은 제공자의 endpoint는 실제 모델 요청을 처리하는 곳입니다. 무료 여부도 도구 이름이 아니라 선택한 모델과 계정의 제공 조건으로 판단합니다.

OpenCode에 NVIDIA를 직접 연결하는 절차부터 살펴보고, Claude Code를 쓰고 싶을 때 FCC를 사이에 두는 경로로 이어집니다. 설치 명령은 Windows·macOS·Linux로 나누고, 앱 안에 입력하는 /connect·/models 같은 명령은 터미널 명령과 구분합니다.

OpenCode에서 NVIDIA에 직접 연결하는 순서

설치사용하는 운영체제의 터미널에서 OpenCode를 설치하고 명령 위치를 확인합니다.
제공자프로젝트 권한을 먼저 잠근 뒤 /connect에서 NVIDIA 자격 증명 한 경로만 선택합니다.
모델OpenCode /models와 NVIDIA 모델 페이지를 대조해 현재 사용 가능한 항목을 고릅니다.
응답비민감 짧은 입력으로 응답을 확인하고 파일 쓰기와 셸 실행이 막히는지 점검합니다.

먼저 고정할 범위와 완료 조건

설치 환경은 Windows PowerShell, macOS의 zsh, Linux의 bash입니다. Node.js와 npm이 준비돼 있다는 전제로 OpenCode의 공식 npm 설치 경로를 사용합니다. OpenCode 시작 문서는 Windows에 WSL을 권장하면서 native 설치도 안내합니다. WSL을 선택한다면 Linux 명령을 사용하되 설치·프로젝트·인증을 모두 WSL 안에서 진행하고 Windows 설치와 섞지 않습니다.

여기서 macOS는 맥 컴퓨터의 운영체제입니다. iPhone·iPad의 iOS·iPadOS에 아래 데스크톱 터미널 설치 명령을 그대로 실행하는 안내는 아닙니다.

완료는 다음 조건이 모두 맞을 때입니다.

선택한 운영체제의 터미널에서 opencode 명령이 실행됩니다.
프로젝트 설정은 NVIDIA provider만 허용하고, 파일 수정·셸·외부 디렉터리 접근을 거부합니다.
/connect로 저장한 NVIDIA 키 한 경로만 사용합니다.
/models 목록과 NVIDIA 공식 모델 페이지에서 같은 모델을 확인합니다.
비민감 짧은 입력에 원격 응답이 오고, 쓰기 요청은 실제 파일을 만들지 못합니다.

이 확인은 연결과 권한 경계를 보는 스모크 테스트일 뿐, 모델의 코딩 정확도·속도·가용성·비용을 평가하는 벤치마크가 아닙니다.

hosted NVIDIA provider와 local NIM은 다른 경로다

OpenCode의 NVIDIA provider 안내는 build.nvidia.com에서 발급한 API 키로 NVIDIA가 호스팅하는 endpoint에 연결하는 흐름입니다. 반면 NVIDIA NIM LLM API 문서가 다루는 local NIM은 사용자가 별도 인프라에서 NIM 서비스를 띄우고 OpenAI 호환 baseURL을 OpenCode에 지정하는 자체 호스팅 경로입니다. local NIM의 GPU, 컨테이너, 라이선스, 운영 비용은 “원격 무료 endpoint”와 같은 문제가 아니므로 이 글의 설치 대상에서 제외합니다.

NVIDIA 원격 제공자를 사용하는 경로와 NIM을 직접 운영하는 경로를 구분한 개념도 — 원격 제공자 연결과 NIM 직접 운영은 설정·운영 책임이 다른 경로입니다. 작동 방식을 설명한 재구성입니다.

핵심 비교
구분	역할	설명	예시
이 글의 경로	NVIDIA hosted endpoint	NVIDIA API Catalog의 원격 endpoint를 /connect 자격 증명으로 호출합니다.	NVIDIA provider + 현재 모델 ID
별도 경로	local NIM	사용자가 NIM 서비스를 운영하고 custom baseURL로 연결합니다. 원격 무료 endpoint 설정이 아닙니다.	http://localhost:8000/v1
클라이언트	OpenCode	모델 자체가 아니라 provider와 모델을 선택하고 도구 권한을 집행하는 에이전트 인터페이스입니다.	/connect, /models, permission

1단계: 운영체제별 OpenCode 설치

Node.js와 npm을 설치한 터미널에서 아래 명령을 실행합니다. npm 설치 명령은 같고, 실행 파일 위치를 찾는 명령만 다릅니다.

Windows — PowerShell

node --version
npm --version
npm install -g opencode-ai
Get-Command opencode

macOS·Linux — zsh 또는 bash

node --version
npm --version
npm install -g opencode-ai
command -v opencode

Get-Command가 오류를 내거나 command -v가 경로를 출력하지 않으면 인증으로 넘어가지 않습니다. 터미널을 새로 열고 npm의 전역 실행 파일 경로가 PATH에 포함됐는지 먼저 확인합니다. 설치가 확인되면 비어 있는 점검 폴더를 만듭니다.

Windows — PowerShell

New-Item -ItemType Directory -Path ./opencode-nvidia-check
Set-Location ./opencode-nvidia-check

macOS·Linux — zsh 또는 bash

mkdir ./opencode-nvidia-check && cd ./opencode-nvidia-check

이미 같은 이름의 폴더가 있으면 용도를 확인하고 다른 새 이름을 사용합니다. 회사 장비에서 설치가 차단되거나 npm 권한 오류가 나면 관리자 권한이나 sudo부터 추가하지 말고 허용된 Node.js 설치 경로를 확인합니다. 한 번의 진단에서는 native Windows·WSL·macOS·Linux 중 선택한 환경을 유지합니다.

2단계: provider와 도구 권한부터 제한

OpenCode 설정 문서에 따르면 전역 설정과 프로젝트 설정을 합치며, 프로젝트 루트의 opencode.json이 해당 프로젝트에 적용됩니다. 빈 점검 폴더에 다음 파일을 만들어 NVIDIA만 활성화하고, 읽기는 허용하되 편집·셸 실행·폴더 밖 접근은 거부합니다. 그 밖의 권한은 ask로 두어 확인을 요청하게 합니다. OpenCode 권한 문서가 설명하듯 기본 권한은 대부분 allow이므로 인증 전에 이 경계를 먼저 두는 편이 안전합니다.

{
  "$schema": "https://opencode.ai/config.json",
  "enabled_providers": ["nvidia"],
  "permission": {
    "*": "ask",
    "read": "allow",
    "edit": "deny",
    "bash": "deny",
    "external_directory": "deny"
  }
}

edit와 bash를 함께 막아야 모델이 파일 편집 도구 대신 셸 명령으로 파일을 만드는 우회도 차단할 수 있습니다. external_directory 거부는 점검 폴더 밖 읽기·쓰기를 막는 추가 경계입니다. 자동 승인을 넓히는 실행 옵션은 이 확인에 사용하지 않습니다.

3단계: `/connect`로 NVIDIA 키 등록

NVIDIA API Catalog의 API key 설정 페이지에서 이 연결에 사용할 키를 준비합니다. 실제 키는 문서, 프롬프트, 스크린샷, opencode.json, Git 저장소에 넣지 않습니다. 빈 점검 폴더에서 opencode를 실행한 뒤 다음 순서로 진행합니다.

터미널 UI에 /connect를 입력합니다.
provider 목록에서 NVIDIA를 검색해 선택합니다.
NVIDIA에서 발급한 API 키를 붙여 넣습니다.
원래 화면으로 돌아오면 키를 다시 출력하거나 프롬프트에 노출하지 않습니다.

OpenCode 공식 제공자 문서는 /connect로 받은 자격 증명을 ~/.local/share/opencode/auth.json에 저장한다고 설명합니다. 이 경로 표기는 OpenCode 문서의 홈 디렉터리 기준이며, 사용자가 만드는 프로젝트 설정 파일과는 별개입니다. API 키의 발급·회수 상태는 NVIDIA API key 설정에서 별도로 확인합니다. 저장 파일을 Git에 복사하거나 문제 해결을 위해 내용을 통째로 출력하지 않습니다.

NVIDIA_API_KEY는 같은 provider가 읽을 수 있는 대체 인증 경로이지 /connect 뒤에 추가하는 필수 단계가 아닙니다. 이 글의 주 경로에서는 환경 변수를 설정하지 않습니다. 환경 변수 방식을 택해 별도로 진단할 때는 새 터미널 세션에서 /connect를 사용하지 않은 상태로 시작하고, 어느 경로가 키를 공급했는지 기록합니다. 두 방식을 동시에 켠 뒤 키를 번갈아 바꾸면 401 오류의 원인을 구분하기 어렵습니다.

4단계: 현재 `Free Endpoint` 모델 선택

OpenCode에서 /models를 열고 NVIDIA provider 아래의 모델 목록을 확인합니다. 그다음 NVIDIA 공식 모델 페이지에서 같은 모델 ID를 검색해 다음 조건을 함께 봅니다.

현재 페이지에 Free Endpoint 표시가 있는가
텍스트 생성 또는 코딩 입력을 받는 모델인가
OpenCode의 /models에도 같은 식별자가 나타나는가
계정이나 지역에 별도 접근 조건이 표시되는가

OpenCode 제공자 문서에 나온 모델 이름은 설정 예시일 수 있으므로 그 이름을 현재 무료 모델로 고정하지 않습니다. NVIDIA 모델 페이지의 목록과 표시는 바뀔 수 있고, Free Endpoint는 무제한 무료, 일정한 rate limit, SLA, 장기 제공을 뜻하지 않습니다. 요청 직전 모델 상세 페이지에 표시된 조건을 기준으로 판단하고, 업무용 코드나 비밀 데이터는 무료 여부와 무관하게 입력하지 않습니다. (NVIDIA 모델 목록)

모델을 선택했는데 목록에서 사라지거나 호출이 거부되면 곧바로 다른 모델을 무작위로 시도하지 않습니다. 먼저 NVIDIA 모델 페이지에서 제공 상태를 다시 보고, OpenCode를 재시작해 /models를 새로 확인합니다. 모델 접근 오류와 API 키 인증 오류를 같은 문제로 취급하지 않는 것이 핵심입니다.

5단계: 짧은 응답과 권한 제한 확인

모델을 선택한 뒤 저장소 내용, 고객 정보, 소스 코드가 없는 짧은 입력으로 왕복 연결만 확인합니다.

도구를 호출하거나 파일을 읽지 말고, "연결 확인"이라는 짧은 응답만 반환해 줘.

응답이 도착하면 OpenCode → NVIDIA provider → 선택 모델의 요청 경로가 작동했다는 뜻입니다. 문구가 완전히 같지 않더라도 정상 응답과 provider 오류를 구분하면 됩니다. 이 한 번의 응답으로 코딩 품질이나 무료 잔여량을 판단하지 않습니다.

권한 설정이 실제로 적용되는지도 빈 점검 폴더에서 따로 확인합니다.

현재 폴더에 verify.txt 파일을 만들고 한 줄을 기록해 줘.

기대 결과는 파일 편집이나 셸 실행이 거부되고 파일이 생기지 않는 것입니다. 운영체제에 맞춰 파일 존재 여부를 확인합니다.

Windows — PowerShell

Test-Path ./verify.txt

macOS·Linux — zsh 또는 bash

if [ -e ./verify.txt ]; then
  printf '%s\n' 'True'
else
  printf '%s\n' 'False'
fi

파일이 없다는 False만으로 권한 차단이 확인되는 것은 아닙니다. 모델이 도구를 호출하지 않았거나 연결 오류가 났어도 파일은 생기지 않습니다. 세션에서 해당 도구의 사용이 제한되거나 요청이 거부된 근거와 파일이 없다는 결과를 함께 확인합니다. 제한 동작을 확인할 수 없다면 “권한 차단 미확인”으로 남기고, 검사를 통과시키려고 권한을 넓히지 않습니다.

파일이 생겼다면 실제 프로젝트로 이동하지 말고 opencode.json의 위치·JSON 구문·permission 키와 세션 재시작 여부를 확인합니다. OpenCode 권한 문서에 따르면 에이전트별 권한이 전역 규칙을 덮어쓸 수 있으므로 현재 선택한 에이전트의 별도 설정도 대조해야 합니다.

OpenCode 연결 문제를 실행·인증·모델·호출·도구 권한 순서로 나눠 점검하는 흐름 — 짧은 요청으로 연결을 확인하고 도구 권한은 별도의 점검 항목으로 남깁니다. 작동 방식을 설명한 재구성입니다.

오류가 나면 다음 순서를 유지합니다.

명령 없음: Windows는 Get-Command opencode, macOS·Linux는 command -v opencode로 실행 위치와 npm 전역 경로를 확인합니다.
401·인증 오류: 이번 세션이 /connect와 NVIDIA_API_KEY 중 어느 한 경로만 쓰는지 확인하고, 선택한 경로의 키 상태를 NVIDIA 설정에서 봅니다.
모델 없음·404: /models와 NVIDIA 모델 페이지의 현재 모델 ID·제공 상태를 다시 대조합니다.
429·용량 오류: 무료 한도를 추정해 반복 호출하지 말고 해당 모델 페이지와 계정 화면의 현재 제한을 확인합니다.
파일이 생성됨: 프로젝트 설정 위치와 권한 규칙을 바로잡기 전 실제 저장소에서 OpenCode를 실행하지 않습니다.

한 번의 확인을 마치면 더 이상 쓸 필요가 없는 NVIDIA API 키는 NVIDIA API key 설정에서 폐기하거나 회전합니다. 점검 폴더는 자격 증명을 담지 않지만, opencode.json의 권한 예시를 보관할 이유가 없다면 삭제할 수 있습니다. OpenCode 자격 증명 파일은 다른 provider 항목도 포함할 수 있으므로 파일 전체를 무심코 지우지 말고, 현재 공식 인증 관리 절차를 확인한 뒤 필요한 항목만 다룹니다.

OpenCode 경로는 명령 실행, NVIDIA 응답, 파일·셸 권한 제한을 각각 확인해야 마무리됩니다. Claude Code의 인터페이스를 원한다면 같은 NVIDIA 제공자를 다음의 FCC 경로로 연결할 수 있습니다.

Claude Code 화면을 쓰고 싶다면: FCC 연결

fcc-claude는 **Free Claude Code(FCC)**가 제공하는 실행 명령입니다. FCC는 Anthropic이 만든 제품이 아니라 독립 오픈소스 프로젝트이며, Claude Code와 선택한 모델 제공자 사이에서 요청 형식을 연결합니다. 프로젝트 안내가 무료·유료·로컬 모델을 모두 다루는 이유입니다.

따라서 “Claude Code를 무료 제공 모델에 연결한다”와 “Anthropic의 Claude 모델을 무료로 제공받는다”를 구분해야 합니다. NVIDIA 모델을 선택했다면 코딩 화면은 Claude Code여도 답을 만드는 모델은 NVIDIA endpoint에서 제공하는 해당 모델입니다. 무료 범위는 FCC라는 이름이 아니라 선택한 제공자의 모델·계정 조건으로 결정됩니다.

핵심 비교
구분	역할	설명	예시
직접 연결	OpenCode → NVIDIA	OpenCode의 NVIDIA provider에 키를 등록하고 모델을 고릅니다. 로컬 변환 서버가 하나 덜 필요합니다.	opencode → /connect → NVIDIA → /models
FCC 연결	Claude Code → FCC → NVIDIA	FCC에 제공자와 모델을 설정한 뒤 fcc-claude로 Claude Code를 실행합니다. FCC 서버도 함께 켜 둡니다.	fcc-server → Admin 설정 → fcc-claude

1. FCC와 Claude Code 설치

이미 설치했다면 먼저 버전과 명령 위치만 확인하면 됩니다. 아래 설치 스크립트를 다시 실행하면 업데이트가 될 수 있으므로, 설치 여부 확인과 설치 실행을 구분합니다.

Windows — PowerShell

Get-Command fcc-server,fcc-claude,claude
fcc-server --version

macOS·Linux — 터미널의 zsh 또는 bash

command -v fcc-server
command -v fcc-claude
command -v claude
fcc-server --version

FCC가 없다면 프로젝트의 Windows 설치 스크립트 또는 macOS·Linux 설치 스크립트를 사용합니다. 아래는 먼저 파일로 내려받는 명령입니다. 해당 링크의 내용을 확인한 뒤 다음 실행 블록으로 넘어갑니다.

Windows — 다운로드

Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1' -OutFile './install-fcc.ps1'

Windows — 확인한 설치 파일 실행

& ./install-fcc.ps1

macOS·Linux — 다운로드

curl -fL 'https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh' -o ./install-fcc.sh

macOS·Linux — 확인한 설치 파일 실행

sh ./install-fcc.sh

설치기의 에이전트 선택 질문에서는 이 경로에 필요한 Claude Code를 선택합니다. 사용하지 않을 다른 에이전트나 음성 기능까지 추가할 필요는 없습니다. 설치 후 터미널을 다시 열고 위의 명령 위치·버전 확인을 반복합니다. Windows 실행 정책으로 스크립트가 막히면 조직의 허용된 설치 절차를 확인하세요.

fcc-claude가 있어도 실제 claude 명령이 없으면 실행할 수 없습니다. FCC의 런처 소스는 실제 Claude Code 실행 파일에 연결 설정과 인자를 전달합니다. Claude Code 설치 자체가 실패했다면 Anthropic의 운영체제별 설치 안내로 먼저 돌아갑니다.

2. FCC 서버를 켜고 NVIDIA를 설정

이번 연결은 같은 컴퓨터에서만 사용하므로 서버 주소를 127.0.0.1로 지정합니다. FCC의 서버 설정 소스에서 HOST와 PORT를 확인할 수 있습니다. 이미 데스크톱 앱이나 다른 터미널에서 FCC 서버를 실행 중이면 중복 실행하지 말고 기존 서버의 Admin을 엽니다.

Windows — 서버용 PowerShell 창

$env:HOST = '127.0.0.1'
fcc-server

macOS·Linux — 서버용 터미널 창

HOST=127.0.0.1 fcc-server

서버 로그에 표시되는 Admin URL을 브라우저로 엽니다. 기본 포트라면 http://127.0.0.1:8082/admin이며, 포트를 바꿨다면 로그의 주소를 따릅니다. 서버용 터미널은 계속 열어 둡니다.

제공자 설정의 NVIDIA_NIM_API_KEY에 NVIDIA 키를 입력합니다. OpenCode의 /connect에 저장한 키가 FCC에도 자동 등록되는 것은 아닙니다.
MODEL에서 NVIDIA 모델을 선택하고, 해당 모델의 제공 조건을 NVIDIA 페이지에서 대조합니다.
Apply로 적용합니다. 사용하는 버전에 Validate가 있으면 그 결과도 확인합니다.
추가한 fallback 모델이 있다면 함께 확인합니다. 다른 모델로 재시도할 때 별도 제공자의 사용량이 들 수 있습니다.

이 설정 순서와 fallback 동작은 FCC의 제공자 연결 안내를 따릅니다. “무료”라는 표시만 보고 모든 모델 경로가 무료라고 판단하지 않습니다.

3. 새 창에서 fcc-claude 실행

서버용 창과 별도로 터미널을 열고, 코드나 비밀 자료가 없는 새 점검 폴더로 이동합니다. 앞의 OpenCode 폴더를 재사용하기보다 구분하면 어떤 설정이 어느 도구에 적용됐는지 확인하기 쉽습니다.

Windows — 클라이언트용 PowerShell 창

New-Item -ItemType Directory -Path ./fcc-check
Set-Location ./fcc-check
fcc-claude --permission-mode plan

macOS·Linux — 클라이언트용 터미널 창

mkdir ./fcc-check && cd ./fcc-check
fcc-claude --permission-mode plan

폴더 생성이 실패하면 기존 폴더의 용도를 확인하고 다른 새 이름을 사용합니다. --permission-mode plan은 Claude Code의 CLI 옵션이며, Plan 모드는 소스 편집 없이 탐색하는 용도입니다. 이것만으로 데이터 전송까지 막히는 것은 아니므로 점검 입력도 비민감 내용으로 제한합니다. OpenCode의 opencode.json 권한 규칙은 Claude Code에 적용되지 않습니다.

Claude Code 화면에서 /model을 열어 FCC가 제공하는 모델을 선택한 뒤 짧게 요청합니다.

도구를 호출하거나 파일을 읽지 말고, "연결 확인"이라는 짧은 응답만 반환해 주세요.

응답뿐 아니라 FCC 화면이나 서버 기록의 선택 제공자·실제 모델도 대조합니다. 모델에게 자신의 이름을 말해 달라고 하는 것은 연결 증거가 되지 않습니다. 연결이 확인된 뒤에만 공개 샘플 코드의 작은 작업으로 도구 호출과 결과 검수까지 넓혀 갑니다.

4. 오류는 어느 구간에서 났는지 나누기

fcc-claude 명령 없음: FCC 설치와 새 터미널의 PATH를 확인합니다. fcc라는 이름으로 추정해서 실행하지 않습니다.
claude 명령 없음: FCC와 별개인 Claude Code 설치를 확인합니다.
프록시에 연결할 수 없음: fcc-server가 실행 중인지, Admin에 표시된 포트가 맞는지 봅니다. 포트 사용 중 오류라면 기존 FCC 앱·서버부터 확인합니다.
401·403: FCC 자체 프록시 인증과 NVIDIA 제공자 인증 중 어느 구간에서 거부됐는지 확인합니다. 키나 인증 토큰 원문을 로그 공유에 넣지 않습니다.
429·모델 오류: NVIDIA의 모델 제공 상태·계정 제한과 FCC의 선택 모델을 확인합니다. 연결 성공과 무료 한도 보장은 별개입니다.
말은 하지만 파일 작업에 실패: 선택 모델의 도구 호출 호환성과 Claude Code 권한을 나눠 확인합니다. 권한 제한을 전부 해제하는 방식으로 해결하지 않습니다.

점검이 끝나면 클라이언트를 종료하고 서버용 터미널에서 Ctrl+C로 FCC를 종료합니다. 직접 실행한 서버를 끄는 것으로 저장된 제공자 키까지 삭제되는 것은 아닙니다. 더 이상 사용할 키는 제공자의 관리 화면에서 회수합니다.

무료 사용 조건과 별개로 설정·재시도·검수에 드는 시간도 기록해 보세요. 결제액과 사람의 시간을 나누어 비교하는 방법은 AI 코딩 도구 비용 계산에서 확인할 수 있습니다.

어느 경로부터 시작할까요?

OpenCode 화면이 괜찮고 NVIDIA 한 곳만 연결하려면 직접 provider를 설정하는 경로가 단순합니다. Claude Code의 작업 방식을 유지하면서 다른 제공자의 모델을 연결하려면 FCC 경로를 검토할 수 있습니다. 어느 쪽이든 클라이언트 이름, 실제 모델, 무료 범위, 파일 권한을 따로 확인해야 자신이 무엇을 쓰는지 알 수 있습니다.

VIEW—

먼저 고정할 범위와 완료 조건

hosted NVIDIA provider와 local NIM은 다른 경로다

1단계: 운영체제별 OpenCode 설치

2단계: provider와 도구 권한부터 제한

3단계: /connect로 NVIDIA 키 등록

4단계: 현재 Free Endpoint 모델 선택

5단계: 짧은 응답과 권한 제한 확인

Claude Code 화면을 쓰고 싶다면: FCC 연결

1. FCC와 Claude Code 설치

2. FCC 서버를 켜고 NVIDIA를 설정

3. 새 창에서 fcc-claude 실행

4. 오류는 어느 구간에서 났는지 나누기

어느 경로부터 시작할까요?

함께 보면 좋은 글

AI 코딩 도구 비용, 구독료와 검수 시간까지

하네스 엔지니어링, AI 코딩에 기준 세우기

AI PR 작성법, 작게 나누고 제대로 리뷰하기

3단계: `/connect`로 NVIDIA 키 등록

4단계: 현재 `Free Endpoint` 모델 선택