SolonCode는 모델을 포함하지 않은 상태로 출시됩니다. 이는 누락이 아니라 의도적인 제품 선택입니다. 번들로 제공되는 프로바이더(provider), 기본 키(default key), 요청하지 않은 텔레메트리(telemetry) 기반 엔드포인트가 없습니다. 장점은 DeepSeek, 로컬 Ollama 서버, 또는 에어갭(air-gapped) 상태의 기업용 게이트웨이에 동일한 용이성으로 연결할 수 있다는 점입니다. 단점은 바이너리를 설치한다고 해서 바로 작동하는 어시스턴트를 얻을 수 없다는 것입니다. 먼저 모델을 연결(wire up)해야 하며, 바로 이 지점에서 대부분의 초보 사용자들이 막히게 됩니다.

이 글은 SolonCode 설치 이후의 후속 단계입니다. 여기서는 하나의 모델을 연결하고 '안정적(stable)'으로 만드는 방법을 다룹니다. 즉, 긴 도구 호출(tool-calling) 세션, 취약한 네트워크, 그리고 다중 파일 리팩터링(multi-file refactors) 과정에서도 작업 중간에 알 수 없는 실패 없이 견뎌내는 상태를 의미합니다.

JSON 파일이 아닌 웹 설정 페이지부터 시작하세요

settings.json을 직접 편집할 수도 있습니다. 하지만 적어도 첫날에는 그렇게 하지 말아야 합니다. 설정 페이지는 입력값을 검증하며 연결 테스트(Test connection) 버튼을 제공하는데, 이는 제품 전체에서 가장 유용한 디버깅 기능입니다.

soloncode web        # 기본 포트 4808
soloncode web 0      # 사용 가능한 아무 포트나 선택
soloncode web 1212   # 명시적 포트

그 다음 Settings → LLM으로 이동하여 모델을 추가하고 테스트를 누르세요. 테스트를 건너뛰지 마십시오. 테스트 결과가 초록색으로 나온다는 것은

문서에서 바로 확인할 수 있는 유용한 참고 사항 두 가지가 있습니다: Claude 또한 OpenAI 호환 모드를 제공하므로, anthropic 대신 openai Dialect를 통해 실행할 수 있습니다. Alibaba의 Bailian은 자체 DashScope 프로토콜과 OpenAI 호환 프로토콜을 모두 제공합니다. 제공업체가 두 가지를 모두 제공하는 경우, OpenAI 호환 엔드포인트가 거의 항상 테스트를 통과(green test)하는 데 더 빠른 경로입니다.

필드 참조 및 apiUrl을 위한 세 가지 규칙

내부적으로 모델 항목은 Solon AI의 ChatConfig에 매핑됩니다:

이제 실제 실패가 발생하는 지점인 apiUrl 규칙입니다:

1. 전체 curl 스타일 주소(예: /chat/completions 또는 /api/chat로 끝나는 주소)를 붙여넣을 수 있으며, 끝부분을 통해 Dialect가 추론됩니다.
2. **Base URL과 standard**를 함께 제공할 수 있으며, 이 경우 경로가 자동으로 완성됩니다.
3. 자동 완성이 잘못되는 내부 배포 환경의 경우, 주소를 #으로 끝내십시오. 이는 "이것이 전체 주소이므로 더 이상 추가하지 마십시오"라는 의미입니다. # 이후의 모든 내용은 제거됩니다.

한 가지 솔직한 난점은, ChatConfig 참조 문서에는 apiUrl을 "baseUrl이 아닌 전체 주소"라고 설명하는 반면, Dialect 페이지에서는 baseUrl + standard를 명시적으로 지원한다는 점입니다. 두 설명 모두 공식 문서에 존재합니다. 저의 실무적인 해석은 다음과 같습니다: 전체 주소를 붙여넣으십시오. 그렇게 하면 모호함의 한 부류를 완전히 제거할 수 있으며, # 규칙은 추가 작업이 문제를 일으킬 수 있는 경우를 위해 정확히 존재합니다.

복사할 가치가 있는 세 가지 설정

필드 형태(Field shapes)는 안정적입니다. 하지만 호스트 이름(Hostnames)과 모델 ID(model ids)는 그렇지 않습니다. 제공업체(providers)는 모델의 이름을 변경하거나 오래된 모델을 폐기하기 때문입니다. 항상 벤더 콘솔(vendor console)에서 현재 ID를 확인해야 하며, 문서나 스크린샷, 또는 커밋(commit)에 실제 키를 절대 포함하지 마세요.

OpenAI 호환 엔드포인트(OpenAI-compatible endpoint)를 사용하는 클라우드 제공업체 — 가장 일반적인 사례이며, 시작점으로 적합합니다:

apiUrl: "https://api.example.com/v1/chat/completions"
apiKey: "sk-xxxxxx"
model: "<콘솔에서 정확한 ID를 복사하세요>"
...

제공업체의 콘솔에서 "OpenAI 호환(OpenAI compatible)" 베이스 URL(base URL)을 찾아 standard는 기본값으로 두고, 모델 ID를 기억해서 입력하기보다는 복사해서 사용하세요. 콘솔에 표시되는 이름(display name)이 API ID와 일치하지 않는 경우가 빈번합니다.

로컬 Ollama 인스턴스, 공식 예시 기준:

ChatModel chatModel = ChatModel.of("http://127.0.0.1:11434/api/chat")
        .standard("ollama")
        .model("llama3.2")
...

model 값은 사용자가 풀(pull)한 모델 이름 그대로입니다. 만약 ollama run deepseek-r1:7b를 실행했다면, deepseek-r1:7b라고 작성해야 합니다. 방언(dialect) 테이블에는 탐지 규칙으로 standard=ollama만 나열되어 있다는 점에 유의하세요. /api/chat 접미사 매칭(tail-matching) 동작은 테이블이 아닌 방언의 소스 코드에 포함되어 있습니다. standard를 명시적으로 선언하는 것이 안전한 방법입니다.

또한 기대치를 설정해둘 필요가 있습니다. 연결이 잘 되는 작은 로컬 모델이라 할지라도, 다중 파일 리팩터링(multi-file refactors)이나 긴 도구 체인(tool chains) 작업에서는 여전히 신뢰할 수 없을 수 있습니다. 이는 설정 버그가 아니라 성능의 한계(capability ceiling)입니다.

기업용 게이트웨이(corporate gateway). 게이트웨이 자체 문서에 따라 apiUrl을 채우고, 테넌트(tenant) 또는 사용자 정의 인증 헤더를 headers에 넣으세요. 공개 클라우드 이름 대신 게이트웨이의 허용 목록(allow-list)에 있는 모델 이름을 사용해야 하며, 게이트웨이 경로가 특이한 경우 # 접미사를 적용하세요. 클라이언트 전용 게이트웨이가 사용자의 컴퓨터에 있는 다른 모든 프로젝트로 유출되지 않도록, 이 설정은 워크스페이스(workspace) 범위로 유지하십시오.

범위(Scope): 전역(global) 대 워크스페이스(workspace)

설정은 다음 두 곳 중 하나에 있는 settings.json에 저장됩니다:

병합 순서는 명확하게 문서화되어 있습니다: 사용자 레벨 파일이 먼저 읽힌 다음 워크스페이스 파일이 읽히며, 워크스페이스 설정이 사용자 설정을 덮어쓰거나 보완합니다 (workspace config overrides or supplements user config). 설정 페이지에서 저장하면 실행 중인 엔진에 쓰기를 시도하므로 재시작이 불필요한 경우가 많습니다. 문서에는 "반드시 필요한 것은 아니다 (not necessarily)\

재시도 (Retries)는 불안정한 네트워크 문제에는 도움이 되지만, 그 외의 상황에는 도움이 되지 않습니다. 401 오류나 잘못된 모델 ID (model id)는 세 번 모두 동일하게 실패할 것이며, 단지 로그 (log) 양만 세 배로 늘릴 뿐입니다.

기본값인 60초 timeout (타임아웃)은 다시 검토해 볼 가치가 있습니다. 단순한 채팅 (chat) 용도로는 괜찮습니다. 하지만 느린 프록시 (proxy) 뒤에서 긴 컨텍스트 (context)를 처리하는 추론 모델 (reasoning model)의 경우, 이 제한에 걸리기 쉽습니다. 이 값을 높이는 것은 합리적이지만, 사실상 무한대에 가깝게 높이는 것은 권장하지 않습니다. 보이지 않는 상태의 멈춤 (hang) 현상은 빠른 실패 (fast failure)보다 진단하기가 더 어렵기 때문입니다.

컨텍스트 압축 (Context compression)

긴 작업은 대화 턴 (conversation turns)과 도구 결과 (tool results)를 축적합니다. 압축 (Compression)은 오래된 콘텐츠를 요약하여 컨텍스트 압박 (context pressure)을 완화합니다. 두 가지 설정과 명칭상의 주의사항이 있습니다:

compressionThresholdPercent의 기본값은 75입니다. 즉, 컨텍스트 윈도우 (context window)의 75%가 사용되면 압축이 트리거 (trigger)됩니다. 두 문서 페이지 모두 이 부분은 일치합니다.

메시지 개수 트리거 (message-count trigger)의 기본값은 100이지만, 문서상에서 두 가지 서로 다른 이름으로 나타납니다. 설정 참조 (settings reference)에서는 이를 summaryWindowSize라고 부르는 반면, 압축 가이드 (compression guide)에서는 compressionThresholdMessages라고 부릅니다. 마찬가지로, sessionWindowSize (새로운 지시 사항이 포함하는 최근 메시지 수)는 한 페이지에서는 8로, 다른 페이지에서는 12로 기록되어 있습니다. 어떤 것이 권위 있는 정보인지 추측하지 않겠습니다. 사용자의 설정 페이지에 실제로 표시되는 내용을 확인하고, 해당 버전에 대한 진실로 간주하십시오.

모델 컨텍스트 윈도우 (model context window)별 공식 튜닝 (tuning) 범위:

그리고 진정으로 유용한 부분인 증상-노브 (symptom-to-knob) 매핑입니다:

만약 작업이 일관되게 중간에 끊긴다면, maxTurns가 너무 낮을 수 있습니다. 하지만 모델이 제자리걸음을 반복하고 있다면, 대신 작업 설명 (task description)을 더 구체화하세요. 요청 사항이 불분명한 경우, 턴(turn) 수를 늘린다고 해서 해결되지 않습니다.

연결되지 않는 경우

공식 체크리스트는 간단합니다: apiUrl, apiKey, 모델 이름, 그리고 네트워크 프록시 (network proxy)를 확인하세요. 실제로 실행해 볼 수 있도록 확장하면 다음과 같습니다:

1. 제공업체의 콘솔을 열어 잔액이 충분한지 확인할 수 있습니까? 결제 문제는 인증 오류 (auth errors)로 나타납니다.
2. API 키가 활성화되어 있고 채팅 (chat) 권한이 부여되었습니까?
3. 모델 ID (model id)가 여전히 최신입니까? 콘솔에서 새로 복사하세요.
4. 네트워크에 프록시가 필요합니까? 기업용 네트워크는 종종 필요합니다.
5. apiUrl이 벤더의 홈페이지가 아닌 채팅 엔드포인트 (chat endpoint)입니까? /v1 또는 /chat/completions 세그먼트를 누락하지 않았나요?
6. Ollama의 경우: standard=ollama로 설정되어 있습니까, 아니면 전체 /api/chat 주소가 사용되고 있습니까?
7. 내부 엔드포인트의 경우: 자동 완성 기능이 경로를 망가뜨리고 있습니까? # 접미사를 시도해 보세요.

여전히 막막하신가요? logLevel을 DEBUG 또는 TRACE로 설정하고, 오류를 한 번 재현한 뒤 .soloncode/logs/를 읽어보세요. timeout, 401, 403, dialect, model 키워드로 검색(grep)해 보십시오. 특히 방언 (dialect) 불일치와 관련하여, 문서는 두 가지 원인을 명시합니다: 잘못된 standard 설정, 또는 누락된 의존성 패키지 (dependency package).

언급할 가치가 있는 실패 모드가 하나 더 있습니다. 이는 설정 문제처럼 보이지만 실제로는 설정 문제가 아닙니다: 연결 테스트는 통과(green)하지만 코딩 출력 결과가 좋지 않은 경우입니다. 프로젝트 루트 (project root)에서 실행했는지(작업 디렉토리가 틀리면 프로젝트 컨텍스트가 생성되지 않음), 프로젝트에 빌드 및 테스트 명령을 설명하는 AGENTS.md가 있는지, 그리고 세션이 너무 오염되지는 않았는지 확인하세요. 새로운 세션을 시작하는 것만으로도 종종 해결됩니다. 이 중 어느 것도 도움이 되지 않는다면, 그것은 모델의 능력 (capability) 한계이며, 해결책은 설정 값을 바꾸는 것이 아니라 다른 모델을 사용하는 것입니다.

5분간의 수락 테스트 (acceptance testing)

실제 업무에 이 설정을 신뢰하고 맡기기 전에, 프로젝트 루트(root)에서 다음 단계들을 실행해 보세요:

4단계는 사람들이 흔히 건너뛰지만 가장 중요한 단계입니다. 한 번도 실패한 적이 없는 테스트 버튼은 신뢰할 수 없는 테스트 버튼입니다.

다섯 단계가 모두 통과되면, 두 번째 모델을 추가하고 트래픽을 분산시키세요. 코드를 읽거나 작은 수정 작업을 할 때는 기본값으로 저렴하고 빠른 모델을 사용하고, 모듈 간 리팩토링(refactor)이나 까다로운 버그를 해결할 때는 의도적으로 더 강력한 모델로 전환하는 방식입니다. 모든 작업을 가장 비싼 모델로 실행하는 것은 예상치 못한 청구서를 받는 가장 빠른 방법이며, 그것이 성공과 실패를 가르는 결정적인 요인이 되는 경우는 드뭅니다. 대개 모델의 등급(tier)보다는 작업 설명(task description)의 품질이 더 중요합니다.

참고 (Reference)

기본값(Defaults)과 필드 이름은 버전 간에 변경될 수 있으며, 현재 두 개의 문서 페이지가 몇 가지 항목에 대해 서로 다르게 설명하고 있습니다. 의구심이 생길 때는 설치된 빌드(build)의 설정 페이지가 최종 권위(authority)입니다. 모델 ID(model ids)와 엔드포인트 경로(endpoint paths)는 제공자(provider)의 영역입니다. 설정(config)에 대해 버그를 보고하기 전에 콘솔에서 해당 사항들을 다시 한번 확인하세요.