Cline과 OpenCode에 Gemini 4 Hydrogen 연결하기

Ofox를 통해 Hydrogen을 사용하려면 OpenAI 호환 공급자를 선택하고 Base URL을 https://api.ofox.ai/v1, 전송할 모델 ID를 google/gemini-4-hydrogen으로 설정하세요. Cline CLI에서는 공급자를 직접 설정합니다. OpenCode V2에서는 사용자 지정 공급자와 모델을 선언한 다음 선택해야 합니다. 텍스트 답변이 오는 것은 첫 확인일 뿐입니다. 코딩 클라이언트는 도구 호출을 받고 파일을 읽은 뒤 그 결과를 모델에 돌려줄 수도 있어야 합니다.

이 글은 Cline CLI 3.0.74와 OpenCode V2 2.3.0을 다루며, 확인일은 2026년 11월 13일입니다. Google 네이티브 자격 증명과 Ofox 자격 증명을 구분하고, 실제 저장소를 연결하기 전에 실행할 작은 파일 읽기 검증 과제를 제공합니다. Cline 편집기 확장은 별도의 버전과 인터페이스를 사용하므로, 여기의 CLI 명령이 모든 확장 버전에 적용되는 것은 아닙니다.

이 글은 Ofox가 발행합니다. 정식 출시된 클라이언트를 합성 스트리밍 응답을 제공하는 로컬 서버에 연결했습니다. 두 클라이언트 모두 테스트 파일을 실제로 읽고 내용을 반환했습니다. 유료 Hydrogen 요청, 고객 계정 검증, 모델 품질이나 속도 측정은 수행하지 않았습니다. 아래의 실제 서비스 검증 단계는 자신의 계정과 호출 경로가 처음부터 끝까지 작동하는지 확인하기 위해 직접 실행해야 합니다. 연결된 OpenCode, Cline, Google 원문 문서는 영어입니다.

공급자, 키, 모델을 한 묶음으로 선택하기

Google 모델 이름을 Ofox 공급자와 섞거나 Google 공급자에 Ofox 키를 입력하지 마세요. 로컬 모델 별칭과 네트워크로 전송되는 ID도 다릅니다.

Google이 새 통합에 Interactions를 권장하더라도 기존 코딩 클라이언트의 Google 공급자가 자동으로 이 API를 사용한다는 뜻은 아닙니다. Interactions 엔드포인트를 OpenAI 호환 Base URL 필드에 붙여 넣지 마세요. 서로 다른 요청 및 응답 형식은 Hydrogen API 연결 가이드에서 설명합니다.

이번에 확인한 Ofox 카탈로그에는 Hydrogen의 OpenAI·Gemini 프로토콜 지원과 Chat Completions 엔드포인트가 나와 있습니다. 이는 연결 경로를 알려 주지만, 모든 클라이언트 기능이나 상위 공급자의 도구 동작, 개별 계정의 이용 한도를 입증하지는 않습니다. Ofox 키는 API 키 인증 안내를 따르고, 메시지·스트리밍·도구 필드는 Chat Completions 문서를 확인하세요.

해당 클라이언트 버전 설치 및 작은 프로젝트 준비

OpenCode는 패키지 이름이 중요합니다. 현재 공식 설치 안내는 @opencode/cli로 V2를 설치합니다. 이전 패키지 opencode-ai는 V1입니다. 둘 다 opencode 명령을 제공하므로 명령 이름만으로 필요한 설정 문법을 알 수 없습니다.

이 글에서 확인한 버전으로 설치하려면 다음을 실행합니다.

npm install -g cline@3.0.74
npm install -g @opencode/cli@2.3.0
cline --version
opencode --version

운영체제별 설치 요구 사항은 공식 안내를 확인하세요. 버전을 고정한 목적은 재현이며, 계속 최신 버전일 것이라는 의미가 아닙니다. 이미 OpenCode V1을 사용한다면 전역 설치를 변경하기 전에 V1에서 V2로의 마이그레이션 안내를 읽으세요. V2는 기존 작업 흐름이 쓰던 같은 이름의 명령을 대체할 수 있습니다.

2026년 11월 13일 캡처한 OpenCode 공식 영어 문서입니다. 버전 차이를 보여 주는 자료이며 Hydrogen 모델 테스트 결과가 아닙니다. 마이그레이션 원문 보기.

첫 도구 테스트용 디렉터리를 따로 만드세요. 자체 Git 루트를 만들면 클라이언트가 프로젝트 설정을 찾을 때 프로젝트 경계도 명확해집니다.

mkdir hydrogen-client-check
cd hydrogen-client-check
git init
printf 'Local test marker: HYDROGEN_CLIENT_CHECK_20261113\n' > fixture.txt

처음에는 이 테스트 파일만 있는 프로젝트를 사용하세요. 목표는 한 번의 파일 읽기를 관찰하는 것이며 큰 저장소를 검토하거나 긴 수정 작업을 승인하는 것이 아닙니다. 키를 opencode.json이나 버전 관리에 넣지 마세요. OpenCode 예제는 OFOX_API_KEY에서 키를 읽습니다. 평소 사용하는 로컬 비밀 관리 방식으로 변수를 설정하고, 실제 값이 들어 있는 환경 파일은 커밋하지 마세요.

Cline CLI에서 Hydrogen 설정하기

Cline의 CLI 참고 문서는 공급자 인증과 사용자 지정 모델 선택을 설명합니다. Ofox 경로에서는 정확한 Base URL과 모델 ID로 OpenAI 호환 공급자를 설정합니다.

cline auth -p openai \
  -b https://api.ofox.ai/v1 \
  -m google/gemini-4-hydrogen \
  -k "$OFOX_API_KEY" \
  --data-dir "$PWD/.cline-hydrogen"

openai는 이번 테스트에서 사용한 CLI 공급자 인수이며, 저장할 때 openai-compatible로 정규화됐습니다. 별도 데이터 디렉터리는 이 Cline 테스트 상태를 평소 CLI 상태와 분리합니다. 해당 디렉터리는 비공개 로컬 설정으로 취급하고 버전 관리에서 제외하세요. 명령은 자격 증명을 클라이언트에 전달하므로 변수가 실제 값으로 확장된 인수를 로그나 스크린샷에 남기지 마세요. 환경에 더 적합하다면 Cline의 대화형 인증을 사용할 수도 있습니다.

Base URL은 /v1에서 끝납니다. /chat/completions는 공급자가 구성하므로 직접 붙이지 마세요. 로컬에서 캡처한 요청에서도 공급자가 /chat/completions를 추가했고 설정한 모델 문자열을 그대로 전송했습니다.

Google 네이티브 경로를 사용하려면 별도 데이터 디렉터리에 Google 키와 네이티브 모델 ID를 설정하세요.

cline auth -p gemini \
  -m gemini-4-hydrogen \
  -k "$GEMINI_API_KEY" \
  --data-dir "$PWD/.cline-google-hydrogen"

이 명령에 Ofox Base URL을 추가하지 마세요. 설정 검사에서 Cline CLI 3.0.74는 gemini용 사용자 지정 Base URL을 거부했습니다. 가짜 키로 네이티브 설정을 저장하는 데는 성공했지만, 이는 CLI가 설정을 수락한다는 뜻일 뿐 키의 유효성이나 프로젝트의 Hydrogen 접근 권한을 증명하지 않습니다. 첫 네이티브 요청이 실패하면 Hydrogen 접근 가이드에 따라 Google 프로젝트 할당량과 인증 요구 사항을 확인하세요.

이제 테스트 파일 디렉터리에서 Ofox 검증을 시작합니다.

cline --data-dir "$PWD/.cline-hydrogen" \
  --auto-approve false \
  "Read fixture.txt using a file tool. Return its exact marker. Do not modify files or run shell commands."

승인 요청이 나타나면 의도한 파일 읽기인지 확인하고 승인하세요. 이 CLI 버전은 기본적으로 자동 승인이 켜져 있으므로 --auto-approve false를 명시했습니다. 이는 대화형 검증 과제이며 무인 작업이 아닙니다. 후속 자동화는 목적에 맞는 권한을 따로 정의해야 합니다.

모델 선택 목록에 Hydrogen이 없다면 목록과 서비스 자체를 구분하세요. 확인한 Cline 소스 카탈로그에는 Hydrogen이 없었지만 CLI는 사용자 지정 Hydrogen ID를 수락했습니다. 어느 쪽도 실제 서비스 가용성을 입증하지 않습니다. 정확한 사용자 지정 ID와 저장된 공급자를 확인하고, 비슷한 이름의 구형 모델을 선택하는 대신 첫 실제 응답을 살펴보세요. 편집기 확장에 관한 배경은 Cline API 설정 가이드(영어)에서 확인할 수 있습니다.

OpenCode V2에 사용자 지정 Hydrogen 공급자 설정하기

테스트 프로젝트에 opencode.json을 만들고 다음 전체 V2 설정을 저장하세요. 현재 공급자 설정과 모델 설정 구조를 사용합니다.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "ofox-hydrogen/hydrogen",
  "providers": {
    "ofox-hydrogen": {
      "name": "Ofox Hydrogen",
      "env": ["OFOX_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.ofox.ai/v1"
      },
      "models": {
        "hydrogen": {
          "modelID": "google/gemini-4-hydrogen",
          "name": "Gemini 4 Hydrogen",
          "limit": {
            "context": 1048576,
            "output": 65536
          },
          "capabilities": {
            "tools": true,
            "temperature": false
          }
        }
      },
      "compatibility": {
        "maxTokensField": "max_tokens"
      }
    }
  },
  "permissions": [
    { "action": "*", "resource": "*", "effect": "deny" },
    { "action": "read", "resource": "*fixture.txt", "effect": "allow" }
  ]
}

세 가지 이름을 구분해야 합니다.

• ofox-hydrogen은 로컬 공급자 키입니다. 독립적인 이름을 쓰면 내장 공급자나 기존 사용자 설정과 혼동하는 일을 줄일 수 있습니다.
• hydrogen은 로컬 모델 키입니다. 둘을 합친 선택 문자열이 ofox-hydrogen/hydrogen입니다.
• google/gemini-4-hydrogen은 modelID이며 호환 공급자가 실제로 Ofox에 보내는 값입니다.

컨텍스트와 출력 수치는 모델 제한을 클라이언트에 설명하는 값이지 할당량 부여나 모든 요청의 최대 사용 보장이 아닙니다. Hydrogen의 1,048,576토큰 창은 입력·사고·출력이 공유하며, 65,536토큰 출력 예산에는 보이는 텍스트뿐 아니라 사고도 포함됩니다. 각각 독립적으로 최대로 사용할 수 있는 한도가 아닙니다. 출력 상한은 목표 답변 길이도 아닙니다. 작은 작업부터 시작하고 실제 경로가 반환하는 사용량을 확인하세요.

두 호환성 설정에 주목하세요. temperature: false는 해당 샘플링 제어값을 전송하지 않도록 클라이언트에 알립니다. maxTokensField: max_tokens는 Ofox 문서의 출력 토큰 필드에 맞춥니다. 덮어쓰기 전 OpenCode V2 캡처는 max_completion_tokens를 사용했고, 설정 후 주요 요청은 max_tokens를 사용했습니다. 검증된 것은 클라이언트의 전송 필드 변경이지 Ofox가 다른 모든 별칭을 거부한다는 사실이 아닙니다.

권한 규칙은 다른 작업을 거부하고 테스트 파일 접미사와 일치하는 읽기를 허용합니다. 테스트 파일 하나만 있는 프로젝트에 맞춘 좁은 설정이지만, 와일드카드는 fixture.txt로 끝나는 다른 경로에도 일치할 수 있습니다. 운영체제 샌드박스는 아닙니다. 실제 저장소나 편집 도구, 셸 접근에 맞게 변경하기 전에 OpenCode 권한 문서를 읽으세요.

설정 경로를 명시해 테스트를 실행합니다.

OPENCODE_CONFIG="$PWD/opencode.json" \
  opencode run --standalone --format json \
  --model ofox-hydrogen/hydrogen \
  "Read fixture.txt using a file tool. Return its exact marker. Do not modify files or run shell commands."

--standalone은 검증한 V2 CLI에서 지원됩니다. 설정 파일과 모델을 명시하면 상속된 설정이나 의도하지 않은 기본 모델 문제를 진단하기 쉬워집니다. JSON 이벤트 출력을 검증 자료로 보관하고, 공유 전 자격 증명과 비공개 경로를 제거하세요.

OpenCode 일반 API 설정 가이드(영어)는 공급자 설정의 더 넓은 배경을 설명합니다. 현재 예제는 위 V2 설정을 일관되게 사용하세요. 복수형 providers와 permissions 필드를 구형 V1 예제에 부분적으로 섞지 마세요.

파일 도구의 전체 왕복 호출 확인하기

예상 답변에는 HYDROGEN_CLIENT_CHECK_20261113이 포함되지만 텍스트만으로는 충분한 증거가 아닙니다. 모델이 파일을 읽지 않고 대화 기록의 값을 반복할 수도 있습니다. 클라이언트 도구 이벤트에서 다음 순서를 확인하세요.

1. 의도한 공급자와 정확한 모델 ID로 요청한다.
2. 모델이 fixture.txt를 읽는 파일 도구를 요청한다.
3. 클라이언트가 도구를 실행하고 그 결과에 파일의 마커가 포함된다.
4. 클라이언트가 다음 모델 요청에 도구 결과를 돌려준다.
5. 모델이 반환된 결과를 바탕으로 최종 답변을 생성하며, 미완료 도구 호출이나 클라이언트 오류가 남지 않는다.

더 확실하게 확인하려면 파일의 마커를 바꾸고 새 값을 프롬프트에 넣지 않은 채 새 작업을 시작하세요. 반환되는 마커도 바뀌어야 합니다. 파일이 수정되지 않았고 예상하지 못한 작업을 승인하지 않았는지도 확인하세요. 이는 작은 정확성 검사이며 Hydrogen이 실제 코드베이스에서 기능을 얼마나 잘 구현하는지 평가하는 테스트가 아닙니다.

발행 전 검증으로 확인한 범위는 다음과 같습니다.

OpenCode는 테스트 중 보조 요청도 보냈습니다. 화면에 보이는 사용자 작업 하나가 과금 대상 모델 요청 한 번과 정확히 일치한다고 가정하지 마세요. 실제 서비스 연결 후 계정 사용량을 확인하세요. 로컬 테스트의 시간이나 합성 토큰 수치를 성능 또는 청구 증거로 사용하지 않았습니다.

Cline의 사용자 지정 모델 캡처에는 명시적인 max_tokens나 temperature 필드가 없었습니다. 모델 이름을 저장한다고 OpenCode 예제와 동일한 출력 상한까지 설정되는 것은 아닙니다. 큰 작업 전에 클라이언트가 지원하는 설정과 실제 요청 동작을 확인하세요.

버전·인증·도구 기록 오류 진단하기

한 번에 변수 하나만 바꾸세요. 먼저 설정 로딩, 인증, 텍스트 생성, 도구 결과 반환 중 어느 단계에서 실패하는지 구분합니다.

첫 번째 버전 오류는 V1에 V2 권한 배열을 전달해 재현했습니다. 패키지 업그레이드와 권한 정책 마이그레이션은 다른 작업입니다. 올바른 실행 파일을 선택했다고 기존 프로젝트 정책의 의미가 그대로 유지된다는 사실까지 자동으로 확인되지는 않습니다.

Gemini의 함수 호출 문서와 사고 서명 문서는 여러 턴의 도구 교환에 텍스트 기록 이상의 정보가 필요한 이유를 설명합니다. 클라이언트나 어댑터가 필수 모델 상태를 제거하면 첫 턴은 성공해도 다음 턴이 실패할 수 있습니다. Gemini 도구 호출의 사고 서명 누락 진단도 참고하세요. 이는 실패 패턴을 설명할 뿐, 두 클라이언트에 Hydrogen 관련 해당 버그가 있음을 증명하지 않습니다.

Gemini API 오류 가이드는 인증·할당량·잘못된 요청을 구분하는 데도 도움이 됩니다. 다만 Argon을 중심으로 작성됐으므로 실제 Hydrogen 응답과 비교하고 모델별 세부 사항이 그대로 적용된다고 가정하지 마세요. 서명을 만들어 내거나 실패한 도구 결과를 조용히 버려서 서명 오류를 고치지 마세요.

실제 코딩 작업 전 작동 기준 저장하기

클라이언트 패키지와 버전, 선택한 공급자, 전송 모델 ID, Base URL, 관련 설정, 권한 규칙, 성공한 파일 도구 기록을 보관하세요. 자격 증명은 기록에 넣지 마세요. 로컬 합성 테스트인지 실제 서비스 테스트인지, 어느 계정의 이용 한도를 사용했는지도 적어 두세요.

실제 서비스에서 파일 테스트가 통과하면 작은 저장소에서 함수 하나를 읽기 전용으로 설명하도록 요청하세요. 그다음 검토 가능한 수정 하나를 허용하고 프로젝트의 관련 검사를 실행하세요. 이 순서는 경로와 도구 전송을 모델의 코드 판단 능력과 분리합니다. 파일을 읽었다고 셸 동작의 안전성, 수정의 신뢰성, 모든 플러그인 호환성이 증명되는 것은 아닙니다.

클라이언트·공급자·모델 버전을 바꾸면 작은 검증 과제부터 다시 실행하세요. 원시 요청을 살펴볼 때는 Hydrogen API 가이드, 사용할 모델을 고를 때는 Carbon·Hydrogen·Argon 선택 가이드를 참고하세요. 모델 선택과 특정 클라이언트가 도구 교환을 완료할 수 있는지는 구분해 판단해야 합니다.