기타 옵션

[General]
ipv6 = true
loglevel = notify

skip-proxy = 127.0.0.1, 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12, 100.64.0.0/10, localhost, *.local

tun-excluded-routes = 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12
tun-included-routes = 192.168.1.12/32

공통 옵션

전체 IPv6 지원 활성화 (기본값: true)

ipv6 = true

loglevel (기본값: warning)

loglevel = notify

none, fatal, warning, notify, info 또는 verbose 중 하나. 일상 사용에서 verbose를 활성화하면 성능이 크게 저하되므로 권장하지 않습니다.

skip-proxy

skip-proxy = 127.0.0.1, 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12, 100.64.0.0/10, localhost, *.local

iOS와 tvOS 버전에서는 호스트명 항목이 터널의 프록시 예외 목록에 추가되어, 그 호스트로의 연결을 Chute 프록시 대신 Chute TUN이 처리합니다. IP 주소나 CIDR 항목은 여기에 더해 터널의 제외 라우트가 되므로, 그 범위로 가는 트래픽은 Chute TUN이 처리하는 것이 아니라 터널을 아예 벗어납니다. Chute Android도 VPN 모드에서 같은 일을 합니다: 시스템 HTTP 프록시가 켜져 있는 동안 호스트명, * 와일드카드, IPv4 주소는 VPN이 앱에 넘기는 프록시의 예외 목록에 들어가고, Android 13 이상에서는 모든 IP 주소나 CIDR 항목이 VPN의 제외 라우트가 됩니다 — 단일 주소는 /32 또는 /128 라우트로. 루프백 항목은 빠집니다. 루프백 트래픽은 애초에 터널로 들어오지 않기 때문입니다. macOS 버전에서는 "시스템 프록시로 설정"이 활성화될 때 이러한 설정이 시스템에 적용됩니다. 이 옵션은 일부 앱과의 호환성 문제를 해결하는 데 사용됩니다.

• 단일 도메인을 지정하려면 도메인 이름을 입력하세요 - 예: apple.com.
• 도메인의 모든 웹사이트를 지정하려면 별표를 도메인 이름 앞에 사용하세요 - 예: *apple.com.
• 도메인의 특정 부분을 지정하려면 각 부분을 지정하세요 - 예: store.apple.com.
• 호스트 또는 네트워크를 IP 주소로 지정하려면 특정 IP 주소를 입력하세요. 예: 192.168.2.11 또는 192.168.2.* 또는 192.168.2.0/24.

주의: IP 주소 또는 주소 범위를 입력하면 해당 주소를 사용하는 호스트에 연결할 때만 프록시를 우회할 수 있으며, 해당 주소로 해석되는 도메인 이름으로 연결할 때는 불가능합니다.

프록시 서버 수신 대기

interface = 127.0.0.1
port = 8118
socks-interface = 127.0.0.1
socks-port = 8119

interface / port는 HTTP 프록시 서버의 수신 주소와 포트를 제어합니다(기본값 127.0.0.1:8118). socks-interface / socks-port는 SOCKS5 프록시 서버를 제어합니다(기본값 127.0.0.1:8119).

평문 http:// 요청의 경우 HTTP 프록시 서버의 연결 하나는 한 번의 주고받기만 실어 나릅니다: 각 응답은 Connection: close를 달고 나가며 그 뒤 연결이 닫히므로, 클라이언트는 다음 요청을 새 연결로 보냅니다. 첫 요청 뒤에 파이프라인으로 이어진 요청은 버려지며, 클라이언트가 새 연결에서 다시 보냅니다. 같은 연결에서 여러 번 왕복해야 하는 인증 방식(NTLM, Negotiate 등)은 이를 거쳐서는 완료할 수 없습니다. 복호화하지 않는 CONNECT 터널은 영향을 받지 않습니다. WebSocket 업그레이드는 연결을 유지합니다: 101 응답 이후에는 데이터가 양방향으로 그대로 오갑니다.

호환성 별칭: doh-server와 doh-service는 doh의 별칭으로 허용됩니다. http-listen / socks5-listen(예: 0.0.0.0:6152, [::]:6153, 또는 포트 번호만)은 위의 interface/port 설정에 매핑됩니다. 와일드카드 수신 호스트(0.0.0.0, ::, *)를 지정하면 allow-wifi-access = true도 함께 설정됩니다.

인바운드 프록시 인증

http-auth = username:password

클라이언트가 Chute의 HTTP 및 SOCKS5 프록시 서버를 사용하기 전에 인증하도록 요구합니다. 이 줄을 반복하여 여러 자격 증명을 허용할 수 있습니다.

HTTP 프록시는 유효한 자격 증명이 없는 요청 — 일반 요청이든 CONNECT든 — 에 407 Proxy Authentication Required와 Proxy-Authenticate: Basic realm="KLNEKit"로 응답한 뒤 연결을 닫습니다. SOCKS5 서버는 같은 자격 증명을 SOCKS5 사용자 이름/비밀번호 인증으로 받으며, 이 인증을 제시하지 않거나 인증에 실패한 연결은 닫습니다.

시스템 요청 우회

bypass-system = true

활성화되면 Chute는 고정된 Apple 호스트명 18개 — 푸시, iCloud 게이트웨이, 캡티브 포털 확인, OCSP 등 — 를 skip-proxy에 덧붙이고, 사용자의 규칙 뒤, FINAL 바로 앞에 IP-CIDR,17.0.0.0/8,DIRECT,no-resolve를 덧붙입니다 — 따라서 17.0.0.0/8에 먼저 일치하는 사용자 규칙이 여전히 이깁니다. 프로세스를 기준으로 한 일치는 없습니다: 이 옵션은 그 고정된 호스트·주소 목록일 뿐, 어떤 프로세스가 요청을 보냈는지 가리는 필터가 아닙니다.

기본값: true.

항상 실제 IP

always-real-ip = *.example.com, tracker.example.org

Chute가 하이재킹된 DNS 쿼리에 가짜 IP 주소를 제공할 때(hijack-dns 참조), 쉼표로 구분된 이 목록과 일치하는 호스트명은 항상 실제로 해석된 IP 주소로 응답됩니다. 와일드카드가 지원됩니다. always-ip-address(Shadowrocket의 표기)는 이 키로 읽힙니다: 불리언 값(true, yes, on, 1)은 모든 호스트를 뜻하며 always-real-ip = *로 다시 쓰이고, false는 버려지며, 그 밖의 값은 호스트 목록으로 읽힙니다. 구성은 always-real-ip 표기로 저장됩니다.

시스템 hosts 파일 읽기

read-etc-hosts = false

시스템 hosts 파일을 [Host] 표로 읽어 들일지 정합니다. false로 설정하면 그 파일을 무시하며, 변경은 재로드 시 적용됩니다. 로컬 DNS 매핑을 참고하세요.

기본값: true.

기존 연결 중단

interrupt-exist-connections = true

활성화되면 모든 정책 그룹에서 선택된 정책이 변경될 때(URL 테스트, 폴백, 로드 밸런스, SSID 또는 수동 선택을 통해) 기존 연결을 정상적으로 종료하여, 연결이 이전 정책에 머무르지 않고 즉시 새로 선택된 프록시를 사용하도록 합니다.

이는 연결이 거치는 모든 정책 그룹에 적용됩니다. 규칙이 지정한 그룹, 그 안에 중첩된 그룹, 체이닝 정책(underlying-proxy)의 상위 그룹, 그리고 릴레이 그룹의 멤버인 그룹입니다.

영향을 받는 각 연결은 3초의 시간 초과 내에 정상 종료를 시도하며, 그 후 강제 종료됩니다.

기본값: false. 이것은 모든 정책 그룹에 영향을 미치는 전역 설정입니다.

네트워크 프레임워크 (macOS / iOS / tvOS)

network-framework = true

Apple Network.framework를 활성화하여 아웃바운드 연결에 사용합니다. Network.framework를 사용하면 지원되는 플랫폼에서 더 나은 성능과 최신 TLS 스택 통합을 제공할 수 있습니다.

기본값: macOS에서는 true, iOS 및 tvOS에서는 false.

단순 호스트명 제외

exclude-simple-hostnames = true

활성화되면 단순 호스트명(점이 없는 단일 레이블 이름, 예: localhost)에 대한 요청은 프록시 규칙을 우회하여 로컬에서 해석됩니다. 이는 로컬 네트워크 이름에 대한 불필요한 DNS 조회를 방지하는 데 도움이 됩니다. 이는 macOS 시스템 프록시 자체의 "단순 호스트명 제외" 설정입니다. Chute Mac이 시스템 프록시 구성에 기록하므로 시스템 프록시를 따르는 애플리케이션에만 적용됩니다 — 향상 모드나 TUN 트래픽에는 적용되지 않습니다. iOS와 tvOS에서는 같은 방식으로 터널의 프록시 설정에 기록되므로, skip-proxy의 호스트명과 마찬가지로 단순 호스트명은 Chute 프록시 대신 Chute TUN이 처리합니다. Chute Android는 이 옵션을 쓰지 않습니다.

Chute Mac에서는 첫 실행 시 일회성 마이그레이션으로 이 옵션이 기본 활성화됩니다. 사용자가 명시적으로 끈 설정은 그대로 존중됩니다.

기본값: false.

데이터베이스 기록 비활성화

disable-db-record = true

활성화되면 Chute가 로컬 데이터베이스에 트래픽 기록 작성을 중지합니다. 이는 성능을 향상시키고 저장소 사용량을 줄일 수 있지만 Chute Dashboard에서 트래픽 기록을 사용할 수 없습니다.

기본값: false.

메뉴 막대 속도 표시 (Mac 전용)

menu-bar-show-speed = true

활성화되면 Chute Mac이 메뉴 막대에 현재 업로드 및 다운로드 속도를 표시합니다.

현재 엔진에서는 파싱만 되고 효과가 없습니다 — Chute Mac의 어느 부분도 이 키를 읽지 않습니다. 메뉴 막대의 속도 표시는 메뉴 항목 연결 속도 표시로 켜고 끄며, 그 값은 앱 자체 설정에 저장됩니다. 이 키는 구성을 저장할 때 그대로 다시 기록됩니다.

다른 DNS 서버 하이재킹

hijack-dns = 8.8.8.8:53

기본적으로 Chute는 Chute DNS 주소(198.18.0.2)로 전송된 DNS 쿼리에 대해서만 가짜 IP 주소를 반환합니다. 표준 DNS로 전송된 쿼리는 단순히 전달됩니다.

일부 기기나 소프트웨어는 항상 하드코딩된 DNS 서버를 사용합니다(예: Google 스피커는 항상 8.8.8.8을 사용합니다). 이 옵션을 사용하여 쿼리를 하이재킹하고 가짜 주소를 얻을 수 있습니다.

hijack-dns = *:53을 사용하여 모든 DNS 쿼리를 하이재킹할 수 있습니다.

포트가 없는 항목은 53번 포트를 뜻하므로 hijack-dns = 8.8.8.8은 8.8.8.8:53입니다. 읽을 수 없는 항목은 알림과 함께 건너뛰고, 그 줄의 나머지 항목은 그대로 적용됩니다.

가짜 IP는 Apple TV(tvOS 17 이상)에서도 사용할 수 있습니다. 이전에는 비활성화되어 있었으며, 실기기 검증이 진행 중입니다.

제외 라우트

tun-excluded-routes = 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12

Chute VIF는 TCP 및 UDP 프로토콜만 처리할 수 있습니다. 이 옵션을 사용하여 특정 IP 범위를 우회하여 모든 트래픽이 통과할 수 있도록 합니다.

주의: 이 옵션은 iOS와 tvOS의 패킷 터널에 적용되며, 그곳에서 이 범위들은 터널 IP 설정의 제외 라우트가 됩니다. Android 13 이상의 Chute Android에도 적용되어 VPN의 제외 라우트가 됩니다 — Android 11과 12에는 제외 라우트를 위한 API가 없으므로 그곳에서는 이 범위들이 무시됩니다. macOS에서는 두 향상 모드 유형 어느 쪽에서도 효과가 없습니다 — 도우미의 utun도, Mac 네트워크 확장도 라우트를 제외하지 않습니다. Chute 프록시 서버에서 처리된 요청은 영향을 받지 않습니다. 'skip-proxy'와 'tun-excluded-routes'를 결합하여 특정 HTTP 트래픽이 Chute를 우회하도록 합니다.

이 옵션은 시스템 오류 ENOMEM(메모리 할당 불가)을 발생시킬 수 있습니다. iOS 시스템의 버그로 보입니다. 이 옵션을 사용하지 않는 것이 좋습니다.

포함 라우트

tun-included-routes = 192.168.1.12/32

기본적으로 Chute VIF 인터페이스는 자신을 기본 라우트로 선언합니다. 그러나 Wi-Fi 인터페이스는 더 작은 라우트를 가지므로 일부 트래픽이 Chute VIF 인터페이스를 통과하지 못할 수 있습니다. 이 옵션을 사용하여 더 작은 라우트를 추가하세요.

기본 라우트만으로는 부족한 이유는 이렇습니다. 시스템은 순서가 아니라 프리픽스 길이로 라우트를 고릅니다. 물리 인터페이스가 가진 온링크 서브넷(이를테면 192.168.1.0/24)은 터널의 0.0.0.0/0보다 더 구체적이라 그 트래픽은 Chute까지 오지 않습니다. 여기에 넣은 항목은 그보다 더 구체적인 라우트를 설치하므로 이깁니다. 이 라우트들은 기본 라우트 위에 더해질 뿐, 터널이 잡는 범위를 좁히지는 않습니다.

참고: 사설 대역(10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)을 통째로 나열하지 마세요. 보통은 필요 없고 시스템 자체의 라우팅을 어지럽힐 수 있습니다. Chute는 그런 항목도 그대로 적용하지만 경고를 기록합니다 — 단, macOS에서 향상 모드의 네트워크 확장 유형은 경고 없이 적용합니다. 이 옵션을 쓰는 일반적인 이유는 다른 VPN 앱의 터널이 가진 대역에 닿기 위해서입니다.

참고: Chute 자신이 쓰는 경로를 끊어 버릴 항목은 거부되고 그 이유가 로그에 남습니다. 루프백, VIF 자신의 서브넷(198.18.0.0/15과 fd12:1:1:1::/64), 링크 로컬, 멀티캐스트, 브로드캐스트, 그리고 프리픽스 길이 0이 그렇습니다. macOS에서 향상 모드의 도우미 utun 유형은 현재 기본 게이트웨이를 포함하는 항목도 거부합니다. 네트워크 확장 유형에서는 그 이유가 Chute의 로그가 아니라 시스템 로그에 남습니다.

참고: iPhone에서는 로컬 네트워크를 잡을지 여부를 시스템이 따로 결정합니다. 여기에 적은 로컬 서브넷은 앱 설정의 로컬 네트워크 포함도 켜져 있어야 적용되며, 이 스위치는 모든 네트워크 포함이 켜져 있을 때만 켤 수 있습니다. 다른 앱의 터널이 가진 대역에는 그런 스위치가 필요 없습니다. Chute tvOS에도 같은 스위치가 있지만 터널에 적용하지는 않습니다. macOS에서는 라우트가 곧바로 설치되므로 그런 관문이 없습니다.

참고: macOS에서 향상 모드의 도우미 utun 유형은 인터페이스를 붙일 때 이 라우트들을 설치하므로, 목록이 바뀌면 재로드 시 인터페이스를 다시 붙입니다. 이 옵션에는 도우미 버전 0.8.6 이상이 필요합니다 — Chute를 업데이트한 뒤 도우미 재설치 요청을 한 번 승인하세요. 그러지 않으면 도우미 utun 유형은 도우미가 실행 중이 아니라고 보고합니다.

프로토콜 스니핑

sniffing-enabled = true
sniffing-timeout = 100

Chute는 초기 바이트를 검사하여 연결의 실제 프로토콜을 감지할 수 있습니다. 이를 통해 PROTOCOL,TLS,Proxy와 같은 규칙이 비 HTTP 인바운드 연결에서도 올바르게 작동할 수 있습니다.

sniffing-enabled (기본값: false)

sniffing-enabled = true

TCP 연결에 대한 프로토콜 감지를 활성화합니다. 향상 모드에서는 같은 스위치로 순수 IP 주소로 향하는 HTTP/3(QUIC) 흐름도 이름으로 일치할 수 있습니다. Chute는 QUIC ClientHello에서 서버 이름을 읽고, DOMAIN 계열 규칙은 주소 대신 그 이름을 보며, 같은 흐름의 이후 패킷은 모두 첫 패킷의 판정을 따릅니다. 한 패킷에 담기지 않는 큰 ClientHello(양자 내성 키 교환에서 흔함)는 이를 실어 나르는 Initial 패킷들로부터 흐름 단위로 재조립되며(재조립된 hello는 최대 16 KiB) 이름도 읽힙니다. hello의 나머지가 아직 오는 동안 그 흐름의 데이터그램은 순수 주소로 보내지 않고 보류되었다가, 이름을 읽은 뒤 그 이름의 정책을 따라 함께 나갑니다 — 그래서 쪼개진 hello의 첫 조각이 나머지와 다른 경로를 타는 일이 더는 없습니다. 안전장치는 1초 대기, 흐름당 데이터그램 8개 또는 16 KiB, 동시에 재조립 중인 흐름 64개입니다. 이 중 하나라도 넘어선 흐름과, Initial 패킷이 끝내 ClientHello를 완성하지 못한 흐름은 예전처럼 주소로 일치합니다.

sniffing-timeout (기본값: 100ms)

sniffing-timeout = 200

프로토콜을 결정하기 위해 초기 데이터를 기다리는 최대 시간(밀리초)입니다. 느린 연결에서 프로토콜 감지가 실패할 경우 이 값을 늘리세요.

QUIC 차단

block-quic = auto

Chute가 감지된 QUIC(HTTP/3 포함) 트래픽을 거부할지 제어합니다. QUIC은 UDP를 사용하므로 Chute의 HTTP MitM으로 복호화할 수 없습니다. QUIC을 거부하면 호환 클라이언트가 TCP로 다시 시도하도록 유도하여 TCP 기반 프록시 처리와, 구성된 경우 HTTPS 복호화를 적용할 수 있습니다.

TUN을 통해 들어오는 트래픽의 경우 Chute는 거부된 QUIC 흐름에 ICMP/ICMPv6 Port Unreachable 메시지로 응답하므로, 호환 클라이언트가 QUIC 시간 초과를 기다리지 않고 TCP로 폴백할 수 있습니다.

거부된 QUIC 흐름은 규칙이 어떤 정책을 골랐든 정책이 REJECT인 것으로 기록됩니다.

block-quic의 QUIC 감지는 자동으로 수행되며 sniffing-enabled가 필요하지 않습니다. sniffing-enabled는 프로토콜 스니핑 — TCP의 TLS와 QUIC 흐름의 서버 이름 — 을 제어합니다. 개별 QUIC 흐름을 규칙으로 처리하려면 PROTOCOL,QUIC,... 규칙을 사용하세요.

터널 안에서 ICMP에 응답

icmp-auto-reply = false

터널로 들어온 ICMP 에코 요청은 — IPv4든 IPv6든 — Chute가 직접 응답합니다. 응답은 로컬에서 생성되며 대상에는 아무것도 보내지 않습니다. 따라서 규칙이 REJECT하는 주소나 다운된 호스트를 포함해 모든 대상이 응답하므로, 터널 안에서 ping이 성공해도 대상에 도달할 수 있는지는 알 수 없습니다. false로 두면 응답을 멈춥니다. 요청은 기기 밖으로 중계되지만 그 응답은 터널을 통해 돌아오지 않으므로, ping은 끝내 응답받지 못합니다.

기본값: true. TUN을 통해 들어온 트래픽에 적용되며, ICMP가 프록시를 거치는 일은 없습니다.

TUN 우회

bypass-tun = 192.168.0.0/16, 10.0.0.0/8

skip-proxy와 유사하게 TUN/VIF 라우팅 수준에서 작동합니다. 이러한 IP 범위 연결은 TUN 인터페이스를 완전히 우회하여 시스템 네트워크 스택을 직접 통과합니다.

참고: 이 옵션은 iOS와 tvOS의 패킷 터널에 적용되며, 그곳에서 이 범위들은 tun-excluded-routes와 함께 터널의 제외 라우트가 됩니다. Android 13 이상의 Chute Android에도 같은 방식으로 적용됩니다(Android 11과 12는 무시합니다). macOS에서는 두 향상 모드 유형 어느 쪽에서도 효과가 없습니다.

거부 시 오류 페이지 표시

show-error-page-for-reject = true

활성화되면 Chute는 거부된 요청에 대해 사용자 친화적인 오류 페이지를 반환합니다. 이는 HTTP 프록시 인바운드로 들어온 요청에만 해당합니다. 옵션이 꺼져 있으면 그런 요청에는 대신 HTTP/1.1 503 Service Unavailable로 응답합니다. 다른 인바운드에서 거부된 요청은 어느 쪽이든 그냥 버려집니다.

기본값: false.

낙관적 DNS

optimistic-dns = false

활성화되면 Chute는 캐시된 DNS 결과를 즉시 반환하면서 백그라운드에서 레코드를 새로 고칩니다. 이는 오래된 DNS 레코드가 반환될 수 있다는 대가로 연결 지연 시간을 줄입니다. 끄면 TTL이 지난 레코드는 제공되지 않고 버려지며 질의가 업스트림으로 갑니다. 백그라운드 갱신은 그대로 일어나므로 다음 조회는 캐시에서 응답됩니다. 또한 모든 플랫폼에서 한 이름의 여러 주소로 동시에 연결할지도 이 설정이 결정합니다.

기본값: true. 비활성화하려면 optimistic-dns = false를 설정하세요.

Wi-Fi 접근 허용

allow-wifi-access = true

같은 네트워크의 다른 기기가 Chute의 HTTP 및 SOCKS5 프록시 포트에 접근할 수 있게 합니다. 두 리스너의 바인드 주소를 0.0.0.0으로 넓히는 동작입니다. Surge 스타일 구성(그리고 sing-box 가져오기의 allow-lan 매핑)은 이 플래그만 담고 interface는 기본값 127.0.0.1로 두기 때문에, 플래그 자체가 바인드 주소를 넓혀야 합니다.

이 플래그와 명시적인 와일드카드 interface는 같은 의도의 두 가지 표기이며 Chute는 합집합을 취합니다. 이미 0.0.0.0을 적어 둔 구성의 동작은 그대로입니다. 플래그를 바꾸면 두 리스너가 다시 바인딩되므로, 접근을 회수하면 다음 시작이 아니라 재로드 시점에 적용됩니다.

이들은 프록시 포트이며 http-auth를 설정하지 않으면 인증이 없습니다. 통제하지 않는 네트워크에서는 자격 증명도 함께 설정하세요.

관리형 구성

#!MANAGED-CONFIG https://example.com/config.conf interval=86400 strict=false

첫 줄에 #!MANAGED-CONFIG 헤더가 있는 구성은 해당 URL에서 자동으로 다시 가져옵니다. 헤더 매개변수와 업데이트 동작은 관리형 구성에 문서화되어 있습니다.

복제 / 트래픽 기록

replica = true

[General]의 replica 키(replica = true)가 트래픽 기록을 활성화합니다. [Replica] 섹션은 Chute Dashboard에 표시되는 내용을 필터링하며, 해당 키는 복제에 문서화되어 있습니다.

iOS, tvOS, Android에서는 유효한 라이선스도 필요합니다: 라이선스가 없으면 replica = true여도 아무것도 캡처되지 않습니다.

외부 컨트롤러 접근 (Chute Dashboard)

external-controller-access = password@0.0.0.0:6155

Chute Dashboard가 사용하는 원격 제어 서버를 시작합니다. 값은 password@host:port 형식이며, 비밀번호 앞에 선택적으로 사용자 이름을 붙일 수 있습니다(user:password@host:port). iOS와 tvOS에서는 보조 USB 채널이 port + 1에서 열립니다(macOS에서는 열리지 않습니다). 연결 방법은 Chute Dashboard 페이지에 있습니다.

HTTP 제어 API 및 웹 콘솔

[General]
external-http-controller = 127.0.0.1:9090
external-http-secret = your-secret-token
external-http-ui = true
external-http-cors = false

Chute는 Clash 및 Surge 대시보드와 유사한 내장 HTTP 제어 API 및 웹 콘솔을 제공합니다. API는 REST 엔드포인트를 통해 엔진 상태, 트래픽, 연결, DNS, 정책 제어 및 구성 관리를 노출합니다.

Surge의 http-api = <secret>@<host>:<port>는 external-http-controller와 external-http-secret으로 읽힙니다. 각 부분을 따로 적어도 됩니다. http-api-secret, http-api-ui, http-api-cors는 각각 external-http-secret, external-http-ui, external-http-cors로, http-api-web-dashboard도 external-http-ui로 읽히며, 구성은 external-http-* 키로 저장됩니다. http-api-tls는 지원되지 않고(컨트롤러는 평문 HTTP로 동작), 알림만 남깁니다.

external-http-controller (기본값: 비활성화)

external-http-controller = 127.0.0.1:9090

콘솔이 서비스하는 동안 메모리에 유지하는 요청은 macOS에서 4 MB, iOS·tvOS·Android에서 1 MB로 제한됩니다.

HTTP 제어 서버의 주소와 포트입니다. 로컬 전용으로 쓰려면 127.0.0.1을 사용하세요. 루프백이 아닌 주소(예: 192.168.1.5:9090)에 바인딩하려면 external-http-secret을 명시해야 합니다. 없으면 서버는 시작을 거부하고 무엇이 빠졌는지 로그에 남깁니다.

와일드카드 주소(0.0.0.0, ::, *)는 이 검사에서 루프백이 아닌 것으로 취급됩니다. 모든 인터페이스에서 수신하므로 로컬 전용의 정반대이기 때문입니다. 허용되는 표기는 0.0.0.0:9090, *:9090(같은 뜻), IPv6는 [::]:9090입니다 — 대괄호 없이 쓴 :::9090에는 대괄호가 자동으로 붙습니다. 파싱할 수 없는 주소는 컨트롤러를 조용히 꺼 두는 대신 구성 오류로 보고됩니다. 127.0.0.1뿐 아니라 127.0.0.0/8 전체가 루프백입니다.

external-http-secret (기본값: 자동 생성된 토큰)

external-http-secret = your-secret-token

API 인증에 사용하는 Bearer 토큰입니다. 요청에는 Authorization: Bearer <secret> 헤더가 있어야 합니다. 토큰은 이 헤더로만 받으며 쿼리 파라미터로는 받지 않고, 비교는 상수 시간으로 수행됩니다. 인증 실패는 401과 {"ok": false, "error": {"code": "unauthorized", "message": "missing or invalid token"}}을 반환합니다. 데이터를 다루는 경로는 모두 보호됩니다: /api/* 경로, Clash 호환 별칭, 그리고 Chute Android만 아직 제공하는 예전 경로들(/status, /policies, /dns, /records 등)로, 이들도 토큰을 이 헤더로만 받습니다. Chute Android 자체의 원격 대시보드는 이제 /api/* 경로만 씁니다. 웹 콘솔의 페이지와 정적 자원(/, /assets/…, Chute Android에서는 /ui도)에는 토큰이 필요 없습니다(external-http-ui = false이면 아예 사라져 페이지가 404가 됩니다).

이 키가 없으면 Chute는 인증 없이 서비스하는 대신 토큰을 생성합니다. 생성된 토큰은 Chute의 공유 폴더에 있는 control-token에 소유자만 읽을 수 있는 권한으로 기록되며 — 구성 파일 옆이 아니라 iOS와 tvOS에서는 App Group 컨테이너, Android에서는 앱의 비공개 데이터 디렉터리입니다 — 재시작 후에도 재사용되고 각 앱이 보여 줍니다 — 웹 콘솔 열기를 참고하세요. 제어 API는 연결 데이터베이스를 넘겨줄 수 있고, 그 기록에는 이번 실행에서 본 모든 URL과 헤더, 프로세스 이름이 담깁니다. 인증 없이 열린 컨트롤러는 합리적인 기본값이 아닙니다.

그래도 인증 없이 서비스하려면 구성에 분명히 적으세요:

external-http-secret = none

이 값은 루프백 바인딩에서만 허용됩니다. 루프백이 아닌 곳에서는 none도, 키를 빼는 것도 충분하지 않습니다. 제어 서버는 시작을 거부하고 무엇이 필요한지 알려 줍니다.

업그레이드 참고: external-http-secret이 없는 것을 '인증 없음'으로 사용해 왔다면 로컬 스크립트가 401을 받기 시작합니다. 앱에서 생성된 토큰을 읽거나, external-http-secret = none을 적어 기존 동작을 의도적으로 유지하세요.

external-http-ui (기본값: true)

external-http-ui = true

활성화되면 Chute는 컨트롤러 주소에서 내장 웹 콘솔을 제공합니다. 웹 콘솔은 개요, 연결 관리, DNS 검사, 트래픽 모니터링, 정책 제어 및 구성 편집을 제공합니다. false로 설정하면 API는 활성화된 상태에서 UI를 비활성화합니다.

웹 콘솔 열기

콘솔은 제어 서버 주소에서 제공되며, 각 앱이 주소와 토큰을 건네줍니다 — 자동 생성된 토큰까지 포함해서입니다. 그렇지 않으면 그 값을 읽을 방법이 없습니다:

• Chute Mac: 메뉴 막대 → 웹 콘솔 열기, 그리고 웹 콘솔 토큰 복사. 연결 상세 창에도 요청 및 기록이 있어 콘솔을 엽니다 — 열리는 것은 홈이지 그 연결 자체는 아닙니다.
• Chute iOS: 제어판 → 웹 콘솔 행 → 열기, 주소 복사, 액세스 토큰 복사.
• Chute tvOS: 제어판에는 별도의 웹 콘솔 주소 행이 있어 호스트와 포트를 보여 줍니다. 선택하면 리스너에 다른 기기에서 접근할 수 있을 때 QR 코드를 표시하며 — 로그인 토큰은 화면이 아니라 코드 안에만 들어 있습니다 — 컨트롤러가 루프백에 바인딩되어 있으면 대신 설명을 보여 줍니다. 루프백 콘솔은 휴대전화에서 열 수 없기 때문입니다.
• Chute Android: 제어판 → 웹 콘솔 주소 → 열기 또는 주소 복사, 그리고 누르면 복사되는 생성된 액세스 토큰 행. 토큰이 직접 설정한 시크릿이면 두 행 모두 나타나지 않으며, 그 시크릿은 결코 표시되지 않습니다.

이 진입점들이 만들어 주는 주소에는 토큰이 쿼리 파라미터로 담겨 있습니다. 페이지는 로드 시 그것을 소비하고 주소 표시줄에서 지우므로, 링크를 여는 것만으로 로그인이 끝나며 32자리 16진수를 옮겨 적을 필요가 없습니다.

external-http-cors (기본값: false)

external-http-cors = true

CORS(Cross-Origin Resource Sharing) 헤더를 API 응답에서 활성화합니다. 웹 콘솔 또는 서드파티 도구가 다른 오리진에서 API에 접근해야 할 때 유용합니다.

API 엔드포인트:

엔드포인트 참고 사항:

• GET /api/connections는 limit(양의 정수, 기본값과 최대값 모두 1000)과 cursor(id가 커서보다 큰 연결만 반환)를 받습니다. 응답 data에는 connections, total, page_size, has_more가 담기고 — 더 많은 페이지가 있을 때는 — next_cursor도 담깁니다.
• GET /api/connections/history는 limit(기본값 100, 최대 1000)과 cursor/before(동의어; 둘 다 전달하면 거부됨)를 받습니다.
• GET /api/connections/:id/request 및 .../response는 {"connection_id": <id>, "data": "<base64>"}를 반환합니다. 2 MiB보다 큰 캡처는 413을 반환합니다.
• GET /api/config는 민감한 값(http-auth, external-http-secret, ca-p12, ca-passphrase, WireGuard 키 등)이 <redacted>로 대체된 구성을 반환합니다 — 결과를 그대로 PUT /api/config에 다시 전달하지 마세요. 그렇게 하면 자리 표시자가 구성에 문자 그대로 기록됩니다.
• GET과 PUT /api/config는 /api/configs로도, 그리고 Clash 별칭 /configs로도 닿을 수 있습니다.
• PUT /api/config는 JSON {"configuration": "<full text>"} 또는 요청 본문으로 전달된 원시 구성 텍스트를 받습니다(1 MB 제한). 성공하면 엔진이 다시 로드되며 — 실행 중이 아니었다면 시작됩니다.
• PUT /api/policies/:group은 본문 키 policy, name, selected, select 중 첫 번째 것에서 선택 값을 가져옵니다; 값은 정책 이름이거나 문자열로 된 숫자 인덱스일 수 있습니다. 특수 그룹 이름 GLOBAL은 글로벌 선택 정책을 설정합니다.
• PUT /api/mode는 JSON 숫자를 요구합니다: {"mode": 0} — 0 규칙, 1 다이렉트, 2 프록시.
• PUT /api/features/mitm과 PUT /api/features/record-traffic은 {"enabled": true}를 받습니다.
• GET /api/logs는 since(Unix 초)를 받습니다; 메모리 내 버퍼는 최근 1000개 항목을 유지하며, 각 항목은 {timestamp, wall_time, level, section, message}입니다 — timestamp와 wall_time은 같은 Unix 초 값을 담으며, 시계가 나아가지 않을 때는 항목의 순서가 엄격히 유지되도록 조금씩 앞으로 밀립니다.
• GET /api/health는 엔진이 무엇을 붙들고 있는지, 마지막으로 무엇을 왜 거절했는지, 그리고 이전 실행이 어떻게 끝났는지(clean, unclean, suspected_memory — 문제 해결 참고)를 보고합니다.
• GET /api/events는 메모리 링을 제공합니다. ?persisted=1은 이번 실행의 저장된 기록을 읽으며, 기록이 꺼져 있으면 available: false로 답합니다.
• [Tailscale] 섹션이 없으면 GET /api/tailscale은 state: "idle"을 반환합니다. 오류가 아니라 정상적인 답입니다.
• POST /api/diagnostics/* 검사들은 쿼리 문자열이나 JSON 본문에서 인자를 받고, 10초로 제한되며, 정확히 한 번만 응답합니다. url-test/:policy는 정의되지 않은 정책 이름을 거부하며 REJECT를 측정하지 않습니다.
• GET /api/scripts는 활성화된 generic 스크립트를 {name, type}으로 나열합니다. POST /api/scripts/run은 본문이나 쿼리 문자열에서 name을 받고, 진단 검사들과 같은 시간 제한이 걸리며, {name, timedOut, result}로 답합니다 — timedOut은 $done을 끝내 부르지 않은 스크립트와 끝까지 실행된 스크립트를 구분해 줍니다. 활성화된 generic 스크립트가 아닌 이름은 404입니다.
• POST /api/rules/match는 연결을 열지 않고 요청이 어디로 갈지 답합니다. host(또는 호스트와 포트를 가져올 url. URL-REGEX 규칙은 이 url을 적힌 그대로 대조합니다(실제 트래픽에서는 평문 http:// 요청만 봅니다)), port(기본 443), 그리고 선택적으로 ip, protocol, process, process_path, src_ip, src_port, in_port, in_type, in_user, in_name, network, ssid, bssid, from_tun, user_agent를 받습니다 — 모르는 필드는 무시되지 않고 허용 목록과 함께 거부됩니다. 응답에는 matched 규칙(규칙 줄, 종류, 그것이 지목하는 정책, 그리고 그룹이 현재 가리키는 resolved_policy), policy, need_resolve, 그리고 계산의 근거가 된 rule_count와 match_generation이 담깁니다. 도메인은 두 번 — 이름으로 한 번, 주소를 알고 나서 다시 한 번 — 일치하므로 passes에는 패스마다 한 항목이 들어갑니다. ip를 주지 않으면 해석 전 패스만 존재하고, 응답이 note로 그렇게 말합니다. explain=true를 더하면 함께 일치할 수 있었던 후보 규칙을 최대 50개까지, 펼치지 않은 규칙 세트의 수와 함께 돌려줍니다.
• POST /api/config/validate는 구성을 파싱한 뒤 버립니다: 실행 중인 엔진은 아무것도 받아들이지 않습니다. {"configuration": "<full text>"}로 보내거나 원문 텍스트를 그대로 보내세요. 응답은 valid, error_count, advisory_count, rule_count, policy_count, 그리고 {line, severity, content, error}로 이루어진 errors 목록입니다 — severity는 거부된 줄과 단서를 달아 받아들인 줄을 구분하고, content는 민감한 부분을 가린 문제의 줄입니다 — 잘못된 [Proxy] 줄에는 대개 그 원인이 된 비밀번호가 들어 있기 때문입니다. PUT /api/config 전에 쓰세요. 그쪽은 디버깅 중인 실행을 재시작시킵니다.
• GET /api/loglevel은 현재 level, nslog_level, 파일에 기록 중인 sections, 그리고 설정할 수 있는 available_levels / available_sections를 보고합니다. PUT(또는 PATCH)은 level, sections 또는 둘 다를 받습니다: sections는 섹션 이름의 배열이거나 문자열 "all"이고, 빈 배열은 거부됩니다 — 기록을 멈추려면 level을 none으로 하세요. 이 방법으로 수준을 바꿔도 실행은 재시작되지 않으며, 그것이 요점입니다: 파일에 적은 loglevel = verbose는 재로드가 필요하고, 재로드는 보려던 것을 잃게 만듭니다.
• GET /api/rules는 rewrite_hits도 함께 보고합니다 — 이번 실행에서 적용된 모든 재작성/모의 응답 규칙과 횟수입니다. 거기에 없는 규칙은 한 번도 일치한 적이 없습니다. 재작성이 아무 일도 하지 않는 것처럼 보이는 흔한 이유가 바로 이것입니다. 이 표는 서로 다른 규칙을 최대 512개까지 추적하며, 그 이상은 rewrite_hit_dropped_rules로 보고합니다. rules는 매처가 훑는 모든 규칙을 순서대로 나열합니다. Tailscale 자동 규칙, 모듈 규칙, 구성의 [Rule] 섹션 순이며 마지막은 FINAL입니다. rule_regions는 각 줄의 출처를 같은 인덱스로 알려 줍니다(front, module, configuration).
• POST /api/rewrites/:family는 {"rule": "<configuration line>"}을 받습니다 — 파일에 적을 바로 그 텍스트입니다. 파싱되지 않는 줄은 400으로 거부되며, 결코 일치할 수 없는 규칙으로 저장되지 않습니다. :family는 url-rewrite, header-rewrite, body-rewrite, mock 중 하나입니다. 이렇게 추가한 규칙은 실행 중인 엔진에만 존재하며 구성 파일로 다시 쓰이지 않습니다.
• GET /api/connections/export?format=har는 HAR 1.2 문서를, POST /api/diagnostics/bundle은 zip을 반환합니다. 둘 다 파일이므로 다른 엔드포인트와 달리 {"ok": ..., "data": ...} 봉투로 감싸지 않습니다. export는 source(기본 current, 또는 history), limit(기본 100, 최대 300), ids, 그리고 캡처된 페이로드를 포함하는 bodies=1을 받습니다. 각 항목에는 HAR에 대응 필드가 없는 정보 — 선택된 정책, 일치한 규칙, 적용된 재작성 — 가 _kl 객체로 담깁니다.
• 체이닝된 연결의 GET /api/connections와 GET /api/connections/history 레코드에는 chainPath가 있습니다. 이 기기부터 출구까지의 경로로, 예를 들면 Airport/HK-01 → Landing입니다. 정책 하나만 쓴 연결에서는 비어 있으며, HAR 내보내기에서는 _kl.chain입니다. GET /api/traffic의 정책별 카운터에서는 상위 정책에도 체이닝된 연결을 위해 나른 바이트가 집계되며, 전체 합계에는 한 번만 집계됩니다.

예시 — 상태를 읽은 다음 정책 그룹을 전환합니다:

curl -H "Authorization: Bearer your-secret-token" http://127.0.0.1:9090/api/status
{"ok":true,"data":{"running":true,"outbound_mode":0,"mitm":false, ...}}

curl -X PUT -H "Authorization: Bearer your-secret-token" \
     -d '{"policy": "ProxyB"}' http://127.0.0.1:9090/api/policies/MainGroup
{"ok":true,"data":{"outbound_mode":0,"selectable_groups":[...], ...}}

예시 — 요청을 보내기 전에 그것이 어디로 갈지 묻습니다:

curl -X POST -H "Authorization: Bearer your-secret-token" \
     -d '{"url": "https://api.example.com/v1/orders", "explain": true}' \
     http://127.0.0.1:9090/api/rules/match
{"ok":true,"data":{"policy":"MainGroup","matched":{"rule":"DOMAIN-SUFFIX,example.com,MainGroup", ...}, ...}}

재현하는 동안 실행을 재시작하지 않고 로그를 한 하위 시스템으로 좁힙니다:

curl -X PUT -H "Authorization: Bearer your-secret-token" \
     -d '{"level": "verbose", "sections": ["MitM", "DNS"]}' \
     http://127.0.0.1:9090/api/loglevel

참고: 이 기능은 기본적으로 비활성화되어 있습니다. 모든 응답은 성공 시 {"ok": true, "data": {...}}, 오류 시 {"ok": false, "error": {"code": "...", "message": "..."}} 형식의 봉투(envelope)를 사용합니다; 요청 본문은 1 MB로 제한됩니다.

PUT 엔드포인트는 PATCH도 허용합니다. 서드파티 대시보드를 위해 Clash 호환 별칭 경로를 사용할 수 있습니다: /version, /traffic, /connections, /configs, /proxies, /rules — 경로에는 도달할 수 있지만, 응답은 Clash의 스키마가 아닌 Chute의 봉투와 필드 이름을 사용하므로(/version은 {"name", "run_id", "egress_probe"}를 반환하며, egress_probe는 Apple 엔진에서 network_address, Android 엔진에서 egress_ip입니다) Clash 대시보드가 바로 작동하지는 않습니다.

프록시 테스트 URL

[General]
proxy-test-url = http://cp.cloudflare.com/generate_204
test-timeout = 3

proxy-test-url은 자체 url을 설정하지 않은 모든 url-test, fallback, load-balance 그룹의 측정 URL이고, test-timeout(초)은 timeout이 없는 그런 그룹의 시간 제한입니다. 구성을 저장한 뒤에도 그룹은 이 키들을 계속 따르며, 그룹 줄에 쓴 url이나 timeout만 이를 덮어씁니다. 잘못된 proxy-test-url은 구성 오류입니다. internet-test-url은 웹 콘솔의 직접 인터넷 테스트에서 사용되며 프록시를 거치지 않습니다. 설정하지 않으면 엔진의 내장 성공 확인 URL을 사용합니다.

UDP를 지원하지 않는 정책의 UDP

udp-policy-not-supported-behaviour = DIRECT

정책이 UDP를 중계할 수 없을 때(예: 일반 HTTP 프록시) 그 UDP 데이터그램을 어떻게 처리할지 정합니다. REJECT(기본값)는 버리고, DIRECT는 대신 직접 보냅니다. block-quic은 이보다 먼저, 규칙이 고른 정책을 기준으로 판정됩니다: block-quic = auto이면 UDP를 중계할 수 없는 프록시로 향하는 QUIC은 직접 보내지지 않고 거부됩니다. 그 밖의 UDP는 여전히 DIRECT로 폴백합니다. 상위를 거쳐 UDP를 보낼 수 없는 체이닝 정책의 UDP도 같은 방식으로 처리됩니다. 아웃바운드 모드를 따르는 DoQ나 DoH3 업스트림이 UDP를 나르지 않는 정책에 해당할 때도 마찬가지로, REJECT는 그 업스트림을 건너뛰고 DIRECT는 직접 질의합니다.

프런트 프록시

[General]
global-underlying-proxy = Airport

자신의 underlying-proxy가 없는 모든 프록시 정책을 지정한 정책 또는 그룹을 거쳐 연결하게 합니다. Shadowrocket이 프런트 프록시(前置代理)라고 부르며 앱에서만 설정하는 기능입니다. 프록시 제공자의 정책도 포함됩니다. 다음은 그대로 둡니다: 프런트 정책 자체를 거치는 연결이 지날 수 있는 모든 정책(그 멤버, 그들의 상위, 그 안의 릴레이 홉 — 그래서 프런트 정책이 자기 자신을 거치는 일은 없습니다), 제외를 뜻하는 underlying-proxy=DIRECT를 적은 정책, 멤버가 결정하는 정책 그룹, 그리고 DIRECT, REJECT, TAILSCALE. 키를 적지 않거나 DIRECT를 적으면 꺼집니다. 정의되지 않은 이름이면 적용 대상이 될 모든 정책이 직접 연결되는 대신 거부됩니다.

close-if-proxy-chain-missing(Shadowrocket)은 읽히고 프로필을 저장할 때 다시 기록됩니다. Chute는 언제나 그 값이 true일 때처럼 동작해, 상위가 없는 체이닝 정책을 거부합니다. Shadowrocket의 기본값인 false(없는 홉을 건너뛰고 노드에 직접 연결)는 따르지 않으며, 그렇다는 알림을 한 번 남깁니다.

클라이언트 지문

global-client-fingerprint = chrome

자체 fingerprint를 지정하지 않은 모든 정책에 TLS 클라이언트 지문을 설정합니다. 프록시 제공자가 제공하는 정책도 포함됩니다. 정책 자체의 값이 항상 우선하므로 이것은 덮어쓰기가 아니라 기본값입니다.

사용할 수 있는 값은 chrome, firefox, safari, ios 그리고 edge, 360, qq, android, random이며 뒤의 값들은 모두 Chrome으로 처리됩니다. 그 밖에 fingerprint에 나열한 이름도 쓸 수 있습니다. 인식할 수 없는 값은 경고 Ignoring unsupported global-client-fingerprint '<value>'와 함께 무시되고 플랫폼 TLS 스택이 사용됩니다.

기본값: 비어 있음(플랫폼 TLS 스택). ShadowTLS 정책은 항상 이 값을 읽고, VLESS 정책은 tls=true나 reality=true, Trojan과 VMess 정책은 tls=true, Shadowsocks 정책은 ws=true와 tls=true를 모두 설정했을 때 읽습니다. gRPC 전송을 쓰는 정책도 tls=true를 써야 합니다. ShadowsocksR 정책은 이 값을 읽지 않습니다.