OpenCode CLI에서 반복되는 타임아웃 패턴과 ‘단일 장애’ 착시

2026년 기준 터미널에서 AI 프로그래밍 에이전트를 쓰는 흐름은 이미 보편화했습니다. 그중 OpenCode는 TUI·서브에이전트·세션 관리까지 묶어 쓰기 쉬운 쪽으로 선택되는 경우가 많고, 사용자는 먼저 브라우저로 빠르게 문서를 읽은 뒤 같은 망에서 OpenCode CLI만 돌려 보곤 합니다. 그런데 문서 로딩은 빠른데 명령 한 번에 분 단위로 멈추거나, 모델 API 호출 직전에만 레이턴시가 튀는 패턴이 나오면 사람은 무의식중에 업스트림 노드만 갈아탑니다.

이때 실제로 자주 있는 구조는 이렇습니다. CDN이나 정적 에셋 줄은 회선 특성상 빠르지만, 선택한 모델 API는 다른 지역 엣지로 붙고, OAuth 교환은 또 다른 접미에서 토큰을 주고받습니다. 어느 한 줄만 회사 정책·지역 회선·규칙 순서 때문에 DIRECT와 프록시 정책이 갈라지면 TLS 핸드셰이크는 성공한 것처럼 보이다가 상위 애플리케이션에서만 API 타임아웃이 길게 남기도 합니다. 한국·일본·미국 서버를 오가는 사용자일수록 패킷 경로 편차가 커져 증상이 극단적으로 드러나는 편입니다.

그래서 첫 화면부터 Clash 라이브 연결 로그를 펼치라고 말합니다. 속도 테스트 숫자만 보면 오히려 멀어집니다. 공통 디버깅 틀은 연결 로그·TLS 타임아웃과 규칙 매칭 모범을 옆에 두면 분기 속도가 빨라집니다.

ℹ 첫 단추는 라이브 연결: 실패 직후 필터에 opencode, open-code, 선택한 공급자 접미(예: anthropic, openai, google)를 넣어 보세요. 한 줄이라도 정책 문자열이 다르면, 노드를 바꾸기 전에 도메인 분류 한두 줄이 답인 경우가 많습니다.

터미널이 실제로 두드리는 이름 공간: 제품·모델·CDN

아래 목록은 출발점용 체크리스트입니다. 제품 업데이트·엣지 캐시·조직 기본값(.well-known/opencode 등)에 따라 하위 호스트는 바뀔 수 있으므로, 팀은 실제 로그 문자열과 날짜를 YAML 주석에 남기는 습관을 들이는 편이 안전합니다.

브라우저 중심 시나리오와 달리 터미널은 HTTP_PROXY 계열 변수·셸 프로파일·IDE 통합 터미널의 상속 차이까지 겹칩니다. 그래서 «같은 노드인데 왜 브라우저만 된다»는 말이 자주 나옵니다.

OPENCODE_CLI 정책 그룹 설계와 멀티 공급자 정렬

한 덩어리로 묶는 설계

운영 난이도 대비 효과가 좋은 형태는 OPENCODE_CLI 그룹을 하나 두고, 라이브에서 관측한 제품·문서·정적 호스트 접미를 우선 같은 정책으로 보내는 것입니다. 이때 DOMAIN-SUFFIX,.com처럼 지나치게 넓은 줄을 붙이면 업무 트래픽까지 한 노드에 몰려 역효과가 나므로 주의합니다.

API와 CDN을 쪼개는 설계

OPENCODE_DOCS와 OPENCODE_MODEL_API처럼 나누면 원인 추적에는 유리하지만, 서로 다른 레이턴시 등급의 노드를 붙이면 스트리밍·장시간 세션에서 경로가 교차하며 새로운 끊김이 생길 수 있습니다. 분리한다면 같은 리전 또는 같은 채널 집합을 운영 문서로 고정하는 편이 안전합니다. 규칙 순서가 복잡해지면 GeoIP·우선순위 글과 diff를 함께 봅니다.

macOS에서 시스템 확장·레거시 프록시 잔상이 겹치면 증상만 보고는 한참 헤맬 수 있습니다. 같은 시기에 고생 중이면 macOS TUN·프록시 충돌 문서를 병렬로 열어두세요.

여러 공급자를 하루에 번갈아 쓰는 팀이라면 프로필 안에서 섹션 주석으로 OpenCode 전용 블록과 공급자별 블록을 시각적으로 나누는 것이 중요합니다. 그렇지 않으면 나중에 RULE-SET이 자동 갱신될 때 덮어쓰기 사고가 납니다.

OAuth·디바이스 흐름이 중간에서 끊기는 조건

브라우저에서 성공 배너를 봤다고 CLI까지 끝난 것은 아닙니다. 마지막 교환 패킷이 여전히 차단되면 터미널은 조용히 재시도 루프에 들어갑니다. 회사망에서는 HTTPS 인터셉트 없이도 정책 라벨만으로 특정 접미가 느려지거나 HTML 응답이 바뀌는 일이 있어, 사람 눈에는 단순 터미널 CLI 버그처럼 보입니다.

따라서 OAuth 관련 호스트도 제품 블록과 같은 지연 프로필 아래 두거나, 최소한 라이브 로그에서 정책 문자열을 맞춘 뒤에야 로그인을 다시 시도하는 순서를 지키는 편이 낫습니다. 수동으로 HTTPS_PROXY를 넣었다면 자식 프로세스가 변수를 물려받지 못하는 빌드도 있으므로, 재현 순서를 로그 스크린샷 수준으로 남기면 이후 분석이 빨라집니다.

예시 YAML 조각과 운영 시 수정 포인트

아래는 교육용 예시입니다. 프로덕션에 그대로 복사하지 마세요. 실제 수동 줄은 라이브 연결 문자열과 공식 문서의 호스트 목록을 따라가고, RULE-SET이 수동 DOMAIN을 가리지 않는지 패치 노트처럼 확인합니다. 선택한 모델 API 공급자에 맞춰 하단 블록을 반드시 확장해야 합니다.

Illustrative YAML fragment

rules:
  - DOMAIN-SUFFIX,open-code.ai,OPENCODE_CLI
  - DOMAIN-SUFFIX,dev.opencode.ai,OPENCODE_CLI
  # Add observed provider API suffixes from live logs:
  # - DOMAIN-SUFFIX,anthropic.com,OPENCODE_CLI
  # - DOMAIN-SUFFIX,openai.com,OPENCODE_CLI
  - GEOIP,KR,DIRECT
  - MATCH,DIRECT

GEOIP 줄과 최종 MATCH는 조직·회선에 맞게 조정합니다. 구독 품질·갱신 URL 자체가 병목이 되는 경우는 구독 유지 가이드와 함께 봅니다.

TUN, Meta DNS, 터미널 환경 변수

터미널이 운영체제의 시스템 프록시 레이어를 건너뛰면 TUN으로 로컬 소켓 패스 전체를 한 라우팅 스택 아래 둘 때가 많습니다. 그다음은 DNS입니다. 외부 DoH가 빠르게 응답해 보여도 규칙 적중 순서만 틀어지면 같은 엔드포인트라도 다른 IP로 붙고 줄이 또 갈립니다. 가능하면 단말 안의 권위 경로를 한 갈래로 정리합니다.

Meta DNS에서는 fallback과 fake-ip 필터 순서가 중요합니다. 구체 패턴은 nameserver·fallback·fake-ip 문서를 적용한 뒤, 터미널 앱을 완전히 종료했다가 다시 열어 상속을 초기화합니다.

Clash를 종료했는데도 시스템 프록시 잔상이 남으면 CLI 문제와 비슷한 착시가 납니다. 종료 후 네트워크 복구 절차를 함께 확인하세요.

검증 순서와 체크포인트

아래 순서를 플레이북처럼 고정하면 다른 앱과의 교차 영향을 줄이면서 빠르게 좁힐 수 있습니다.

  1. 설치·업데이트 단계부터 연결 로그를 켭니다. 패키지 레이어에서 막히면 사용자 공간 규칙 이전에 별도 카테고리가 필요합니다.
  2. 실패 직후 라이브 목록에서 제품 호스트·공급자 API·정적 자산 줄의 정책명을 나란히 비교합니다. 하나라도 다르면 DOMAIN 줄을 보강하고 RULE-SET 상단 순서를 점검합니다.
  3. OAuth 브라우저 탭이 조직 차단 페이지로 바뀌지 않았는지 확인한 뒤 CLI를 재시작합니다.
  4. RULE-SET을 자동 갱신한 직후에만 깨졌다면 차단 카테고리가 새로운 접미를 삼켰는지 외부 diff로 확인합니다.
  5. 노드 교체로 패턴이 그대로면 순수 회선 문제인지 TLS 경고인지 TLS 로그부터 다시 읽습니다.
  6. GUI 편집은 부담스럽지만 터미널 디버깅은 가볍다고 느낀다면, 사용 중인 클라이언트가 라이브 뷰를 제대로 내주는지 클라이언트 선택 문서와 대조합니다.

자주 묻는 질문

Windows에서는 괜찮고 Linux에서만 OpenCode가 자주 멈춥니다. 무엇부터 보나요?

systemd·NetworkManager·회사 에이전트가 끼어 있는 환경에서는 DNS 스텁과 TUN 라우팅 순서가 OS마다 다릅니다. 한쪽만 재현되면 해당 OS에서 fake-ip 필터와 split routing 순서를 먼저 다시 매깁니다.

RULE-SET에 이미 AI 공급자가 포함된다고 적혀 있는데 추가 규칙이 필요할까요?

주석에 포함된다고 해서 실제 패널 줄이 GeoIP나 광범위한 차단 규칙에 밀려 다른 정책으로 찍히지 않는다는 뜻은 아닙니다. 라이브 문자열이 한 줄이라도 다르면 수동 DOMAIN을 보강하는 편이 안전합니다.

HTTP/2나 스트리밍 경고가 로그에 반복됩니다. 무시해도 되나요?

중간 프록시가 협상만 방해하면 업로드·다운로드 비대칭 구간에서만 지연이 커질 수 있습니다. 반복되면 노드나 스니핑 관련 옵션을 검토하되, 조직 정책으로 금지된 설정은 건드리지 마세요.

준수와 한계

⚠ 준수 알림: 현지 법령, 서비스 약관, 고용·학내 정책을 따르세요. 본 글은 합법망에서의 라우팅 위생을 다루는 기술 자료이며, 통제 회피를 돕는 내용은 포함하지 않습니다.

Zero Trust 장비에서는 사용자가 규칙을 아무리 정교하게 써도 인증 교환 단계에서 아예 거절되는 경우가 많습니다. 이때는 IT 승인 없이 우회를 시도하기보다, 정책상 불가능한 케이스로 분류하고 공식 경로를 밟는 편이 안전합니다.

맺음말

OpenCode CLI의 API 타임아웃은 단일 장애라기보다 제품 CDN·모델 API·OAuth 줄이 서로 다른 출구를 타거나 DNS와 TCP 경로만 엇나가며 생기는 경우가 적지 않습니다. Clash에서 이를 줄이려면 이름 공간마다 명시적인 도메인 분류와 짧은 주기의 규칙 세트 점검 루틴이 필요하고, 터미널 전용 호스트 목록을 브라우저용 목록과 문서적으로 분리해 두는 편이 혼선을 줄입니다.

한 노드만 고르게 켜 두는 앱 일부는 터미널 패스를 세밀하게 보여 주는 라이브 뷰가 부족해, 증상이 길어지면 시간만 소모되는 경우가 있습니다. 회사 디바이스에서는 기능적으로 막힌 줄과 순수 회선 문제를 구별해야 하는데, 그때는 규칙 교정보다 내부 규정이 우선입니다. 이런 전제 속에서 라우팅·TUN·연결 로그를 한 패널에서 다룰 수 있는 Clash Meta 계열 선택이 디버깅 루프를 짧게 만드는 데 도움이 됩니다. Clash V.CORE는 멀티 스트림·멀티 공급자 시나리오를 전제로 프로필과 UI 신호를 정리해 두었기 때문에 OpenCode처럼 조용히 멈추는 터미널 툴과 맞물릴 때도 확인 단계가 덜 헷갈립니다.

→ Clash를 무료로 다운로드해서 이번에 정리한 OpenCode·모델 공급자 줄을 라이브 연결 숫자로 다시 교차 검증해 보세요.