AI 에이전트(MCP) PRO PREVIEW

PREVIEW 알림: MCP 서버는 내부 테스트 중이며 아직 출시되지 않았습니다. 이 페이지는 테스트 중인 빌드를 설명하며, 키, 라우트, 도구 이름과 각 앱의 화면은 출시 전에 바뀔 수 있습니다.

[General]
external-mcp-server = 127.0.0.1:6180

Chute Mac, Chute iOS, Chute tvOS의 엔진에는 자체 MCP(Model Context Protocol) 서버가 있습니다. AI 에이전트 — Claude Code, Codex, 또는 MCP를 지원하는 다른 클라이언트 — 는 여기에 연결해 엔진이 무엇을 하고 있는지(상태, 정책, 규칙, 연결, DNS, 로그, 구성)를 읽고 바꿀 수 있습니다. 정책을 선택하고, 규칙을 시험해 보고, 구성의 한 섹션을 다시 쓰고, 그룹의 구성원을 측정하는 식입니다.

HTTP 제어 API의 경로 위에 만들어졌고 같은 시크릿으로 인증하지만, 리스너는 따로 있어 자체 포트의 /mcp에서 수신합니다. external-http-controller도 웹 콘솔도 필요하지 않습니다. 기본값은 꺼짐입니다.

PRO 알림: MCP 서버는 Chute Pro 기능입니다. 라이선스가 없으면 엔진은 MCP 서버를 시작하지 않습니다. external-mcp-server를 적어도 포트가 열리지 않으며, 구성은 그대로 편집할 수 있습니다. 라이선스가 적용되면 Chute를 다시 시작하지 않아도 서버가 시작되고, 라이선스가 없어지면 서버가 멈춥니다. Chute Mac의 무료 체험 기간도 라이선스가 있는 것으로 칩니다. HTTP 제어 API 자체는 영향을 받지 않습니다. 그동안 앱이 무엇을 보여 주는지는 Chute Pro가 없을 때를, 라이선스와 활성화도 함께 참고하십시오.

어디에 쓰는가

읽고 해석하는 일은 에이전트가 하므로, 평소 말투로 물으면 됩니다. 예를 들어:

  • "왜 api.example.com이 HK-01로 나가지?" — 에이전트는 match_rule로 일치한 규칙과 정책을 확인하고, edit_user_rules로 수정안을 시험한 뒤, 효과가 있으면 replace_profile_section으로 [Rule]에 적습니다.
  • "Auto 안에서 아직 쓸 수 있는 노드는?" — 그룹에 대한 test_policy가 모든 구성원을 차례로 측정하고, 끝나는 대로 하나씩 보고합니다.
  • "오늘 아침부터 이 앱이 서버에 연결되지 않아." — failed 필터를 단 list_connections, 키워드를 단 get_logs, 그리고 네트워크 자체에는 run_diagnostics.
  • "이 사이트의 광고를 막아 줘." — 먼저 add_rewrite와 add_mitm_host로 실행 중인 엔진에서 시험하고, 남길 줄을 구성에 적습니다.

켜기

external-mcp-server(기본값: 비활성화)

external-mcp-server = 127.0.0.1:6180

MCP 서버의 주소와 포트입니다. Chute 고유의 키로, Surge와 Clash에는 이에 해당하는 것이 없으며 그 구성을 가져와도 이 줄은 생기지 않습니다. 주소는 external-http-controller와 같은 방식으로 씁니다. 127.0.0.1:6180은 이 기기 전용, 0.0.0.0:6180 또는 *:6180은 모든 인터페이스, IPv6는 [::]:6180이며, 127.0.0.0/8 전체와 ::1, localhost가 루프백으로 간주됩니다. 해석할 수 없는 주소는 구성 오류입니다. 앱에서 켤 때는 포트 6180을 씁니다.

인증. 에이전트는 Authorization: Bearer <token>을 보내며, 토큰은 HTTP 제어 API의 것입니다:

  • 구성에 external-http-secret이 있으면 그것;
  • 없으면 Chute가 생성해 공유 폴더의 control-token 파일에 보관하는 토큰 — external-http-controller가 꺼져 있어도 생성되며 각 앱에 표시됩니다;
  • external-http-secret = none은 인증을 전혀 하지 않는다는 뜻이며, 루프백 주소에서만 받아들여집니다.

루프백이 아닌 주소에서는 MCP 서버에 명시적인 external-http-secret이 필요합니다. 생성된 토큰도 none도 충분하지 않습니다. 없으면 시작하지 않으며, 앱이 그 이유를 보여 줍니다.

엔진과 함께 실행됩니다. Chute가 시작될 때 시작하고 멈출 때 멈추므로, 에이전트는 Chute를 시작하거나 멈출 수 없고 앱이 다른 구성으로 전환하게 할 수도 없습니다. 다시 로드할 때 리스너는 주소나 시크릿이 바뀐 경우에만, 그것도 이미 보내고 있던 응답을 모두 쓴 뒤에 다시 시작합니다 — MCP 서버 자신의 주소를 바꾼 에이전트도 그 응답은 받습니다.

external-mcp-mask-secrets(기본값: true)

external-mcp-mask-secrets = false

비밀번호, 키, 토큰을 핸들 형태로 에이전트에 넘길지 여부입니다 — 시크릿 마스킹을 참조하십시오. 이것도 Chute 고유의 키이며, false일 때만 구성에 기록됩니다.

앱에서

  • Chute iOS: 구성 편집기의 외부 컨트롤러 → MCP 서버: 스위치, 포트, Wi-Fi 접근 허용(0.0.0.0에서 수신하며, 이때 필요한 시크릿 행은 HTTP 제어 API의 것입니다), 시크릿 마스킹. 제어판에서 웹 콘솔 아래에 있는 AI 에이전트 (MCP) 행은 실행 중, 시작되지 않음, 구성 안 됨 중 하나를 보여 주고, 누르면 다음이 담긴 페이지가 열립니다: 서버가 수신하지 않는 이유, 이 기기용 주소와 (루프백이 아니면) 다른 기기용 주소, 토큰(토큰 표시를 누를 때까지 가려지며, 행을 누르면 복사), 바로 쓸 수 있는 claude mcp add 명령과 JSON이 담긴 클라이언트 설정, 그리고 빠른 작업. MCP 서버는 VPN 안에서 실행되므로, VPN이 꺼져 있으면 현재 구성으로 시작하면 어떻게 될지를 보여 줍니다.
  • Chute Mac: 메인 창의 구성 탭 → 일반 → MCP 서버: MCP 서버 활성화, 주소와 포트, HTTP 제어 API와 함께 쓰는 시크릿, 비밀 정보 가리기, 상태 및 클라이언트 설정…. Chute가 실행 중일 때 메뉴 막대 메뉴(그리고 메뉴 막대 패널의 … 메뉴)의 AI 에이전트(MCP)…가 창을 엽니다. 상태, 주소, 토큰(보기, 복사), 시크릿이 마스킹되는지, 그리고 에이전트 연결: HTTP로 연결하는 Claude Code용 설정, chute 명령을 거치는 Claude Code용 설정, 기타 클라이언트용 JSON입니다.
  • Chute tvOS: 구성 편집 → 일반 → MCP 서버: 켜기·끄기, 수신 대기 주소(127.0.0.1 또는 0.0.0.0), 포트, 비밀 정보 마스킹. 같은 페이지에서 시크릿도 설정합니다. 이것이 바로 HTTP 제어 API의 external-http-secret입니다. 값은 가려서 표시되며 원문을 보도록 고를 수 있습니다. 비워 두면 Chute가 생성한 토큰을 쓰고, none은 인증을 하지 않는다는 뜻이며 위험하다는 경고가 나옵니다. 공백이나 줄바꿈은 넣을 수 없습니다. 바꾸면 웹 콘솔과 chute 명령의 인증도 함께 바뀝니다. 0.0.0.0인데 시크릿이 없으면, 서버가 시작되지 않는다고 알려 주고 그 자리에서 설정하게 합니다. 제어판의 AI 에이전트(MCP) 행은 상태, 주소, LAN 주소, 토큰을 보여 주며, 토큰은 선택할 때까지 가려집니다. TV에서는 복사할 수 없습니다.

빠른 스위치 — iOS의 빠른 작업, Mac 창의 MCP 켜기 / MCP 끄기와 비밀 정보 가리기, TV 페이지의 MCP 서버와 비밀 정보 마스킹 — 는 현재 구성 파일의 이 두 키를 바꾸고 즉시 적용합니다. 여기서 켜면 서버는 127.0.0.1:6180에서 수신합니다. iOS에서는 구독 구성일 때 이 스위치가 비활성화됩니다. 다음 업데이트가 변경을 되돌리기 때문입니다.

Chute Pro가 없을 때

라이선스가 없으면 앱은 서버를 수신하지 않는다고 보고하는 대신 Chute Pro가 필요하다고 알려 줍니다:

  • Chute Mac: 메뉴 막대 메뉴와 메뉴 막대 패널의 … 메뉴에 있는 AI 에이전트(MCP)…, 그리고 일반 페이지의 MCP 서버 활성화에 PRO 캡슐이 붙습니다. AI 에이전트(MCP) 창은 맨 위에 Chute Pro 안내와 Chute Pro 받기 버튼을 보여 주고, 상태는 Chute Pro 필요로 표시되며 주소와 토큰은 보이지 않습니다. MCP 켜기는 서버를 켜는 대신 Chute Pro 창을 엽니다. 끄기와 비밀 정보 가리기는 평소대로 동작합니다. Chute Pro 창의 기능 목록에는 AI 에이전트(MCP)가 들어 있습니다.
  • Chute iOS와 Chute tvOS: 제어판의 AI 에이전트(MCP) 행과 구성 편집기의 MCP 스위치에 PRO 캡슐이 붙습니다. 상태 페이지는 Chute Pro 필요로 표시되고, 주소와 토큰 대신 Chute Pro로 가는 길을 보여 줍니다. 그 페이지의 빠른 스위치로 서버를 켜려고 하면, 앱의 다른 Chute Pro 스위치처럼 먼저 Chute Pro를 요구합니다.
  • 세 앱 모두 구성 편집기의 항목은 그대로 편집할 수 있으며, 「이번 실행에서 동작하지 않은 Chute Pro 기능」을 알리는 안내에 MCP 서버가 포함됩니다.

에이전트 연결

HTTP로 연결

Streamable HTTP를 지원하는 클라이언트는 바로 연결합니다:

  • 주소: http://<host>:<port>/mcp — 같은 기기의 에이전트라면 http://127.0.0.1:6180/mcp;
  • 헤더: Authorization: Bearer <token>, 토큰은 앱에 표시되는 것.

Claude Code:

claude mcp add --transport http chute http://127.0.0.1:6180/mcp --header "Authorization: Bearer <token>"

JSON으로 설정하는 클라이언트:

{"mcpServers": {"chute": {"type": "http", "url": "http://127.0.0.1:6180/mcp", "headers": {"Authorization": "Bearer <token>"}}}}

Chute iOS와 Chute Mac은 이 두 가지를 주소와 토큰을 채운 채로 복사해 줍니다. iPhone에서는 같은 iPhone에 있는 에이전트 앱도 127.0.0.1로 연결합니다.

서버는 MCP 2026-07-28을 구현하며 2025-11-25, 2025-06-18, 2025-03-26 클라이언트도 받아들입니다. 세션을 유지하지 않습니다. JSON-RPC 메시지 하나가 /mcp로의 POST 한 번이며, 응답은 JSON — 오래 걸리는 도구는 이벤트 스트림 — 이고, 응답 뒤에 연결이 닫힙니다. GET, DELETE, OPTIONS에는 405를 반환하고, 배치(JSON 배열)는 거부하며, 요청 본문은 1 MB까지, 동시에 처리하는 연결은 8개까지입니다.

chute mcp로 연결

MCP 서버를 직접 실행하는 프로그램으로만 다룰 수 있는 클라이언트나, 구성에 토큰을 두고 싶지 않은 클라이언트는 chute 명령줄 도구를 중계로 씁니다. chute mcp는 읽은 줄을 하나씩 MCP 서버에 넘기고 응답을 한 줄씩 돌려줍니다.

claude mcp add chute -- chute mcp
{"mcpServers": {"chute": {"command": "chute", "args": ["mcp"]}}}

Chute가 실행 중인 Mac에서는 이것으로 충분합니다. chute mcp는 메시지마다 엔드포인트 파일에서 주소와 토큰을 읽으므로, 클라이언트보다 나중에 시작한 Chute도 찾아냅니다. 토큰은 다음 중 처음 찾은 것을 씁니다:

  1. --token-file <path>;
  2. 환경 변수 CHUTE_MCP_TOKEN;
  3. 이 Mac의 서버에 한해 엔드포인트 파일, 그다음 공유 폴더의 control-token.

--url http://<host>:<port>/mcp는 다른 기기를 가리킵니다. CHUTE_MCP_ENDPOINT는 대신 읽을 엔드포인트 파일을 지정합니다. --token과 --token-stdin은 거부됩니다. 표준 입력 자체가 MCP 통로이고, 명령줄에 적은 토큰은 클라이언트 구성과 프로세스 목록에 남기 때문입니다. 서버에 닿지 않으면 에이전트는 이유가 적힌 오류를 받습니다 — 포트가 닫혀 있으면 external-mcp-server를, 401이면 토큰을 확인하라고 알려 줍니다.

컴퓨터에서 iPhone이나 Apple TV로 연결

  1. 기기에서 네트워크 수신과 시크릿을 설정합니다:

    [General]
    external-mcp-server = 0.0.0.0:6180
    external-http-secret = a-long-random-secret
    

    iOS에서는 Wi-Fi 접근 허용과 시크릿 행, tvOS에서는 같은 페이지에서 수신 대기 주소를 0.0.0.0으로 하고 시크릿을 설정합니다.

  2. VPN을 연결한 뒤 다른 기기(iOS) 또는 LAN 주소(tvOS)에서 주소를 확인합니다 — 예: http://192.168.1.20:6180/mcp.
  3. 같은 네트워크의 컴퓨터에서:

    claude mcp add --transport http chute-phone http://192.168.1.20:6180/mcp --header "Authorization: Bearer a-long-random-secret"
    

    또는 시크릿을 파일에 두고:

    chute mcp --url http://192.168.1.20:6180/mcp --token-file ~/.config/chute/phone.token
    

이 주소는 네트워크에서의 기기 주소이므로, 네트워크가 기기에 다른 주소를 주면 바뀝니다.

엔드포인트 파일

MCP 서버가 수신하는 동안 엔진은 공유 폴더에 mcp-endpoint를 소유자만 읽을 수 있는 권한으로 쓰고, 서버가 멈추면 지웁니다. 값이 모두 문자열인 JSON 객체로, running, configured, url, lan_url(루프백이 아닐 때), bind, port, loopback, token, anonymous, mask_secrets — 앱이 보여 주는 내용 — 이 들어 있습니다. Mac에서는 ~/Library/Application Support/com.R3Studio.Chute-Mac/Share/mcp-endpoint(파일 위치 참조)에 있으며, 덕분에 로컬 클라이언트는 포트도 토큰도 몰라도 됩니다. iPhone과 Apple TV에서는 앱의 컨테이너 안에 있으므로 주소는 앱에서 확인하십시오.

시크릿 마스킹

에이전트가 읽은 내용은 에이전트의 모델 제공자에게 전달됩니다. 그래서 기본적으로 구성의 시크릿은 에이전트에 넘어가지 않습니다. 각 시크릿은 구성에서든, 로그를 포함한 다른 모든 결과에서든, 나타나는 곳마다 <secret:password:3f9c0a1b2e> 같은 핸들 — 종류와 식별자 — 로 바뀝니다. 서버 주소는 그대로 보이므로, 에이전트는 노드나 다운로드가 어느 서버를 가리키는지 여전히 알 수 있습니다.

[Proxy]
HK-01 = trojan, hk.example.com, 443, password=<secret:password:3f9c0a1b2e>, sni=hk.example.com

[Proxy Group]
Sub = select, policy-path=https://sub.example.com<secret:url_secret:8d2e4f6a1c>

마스킹 대상: 프록시의 비밀번호, UUID, 사전 공유 키, 개인 키, obfs와 shadow-tls 비밀번호, MASQUE의 token 같은 토큰 — WireGuard·AmneziaWG 섹션과 프록시 공급자 노드의 것도 포함; http-auth의 각 비밀번호, external-http-secret, external-controller-access의 비밀번호; ca-p12와 ca-passphrase; Tailscale auth key; 스크립트의 argument=; 구독, policy-path, 규칙 세트, 모듈, #!MANAGED-CONFIG URL의 경로, 쿼리, 사용자 정보 부분(스킴, 호스트, 포트는 남습니다); 그리고 [Header Rewrite]에서 이름이 Authorization, Proxy-Authorization이거나 token, key, secret, auth, password, cookie를 포함하는 헤더의 값. 8자보다 짧은 시크릿은 필드 값으로 나타나는 자리에서는 바뀌지만, 로그 줄 같은 자유 텍스트 안에서는 바뀌지 않습니다. 거기서는 평범한 단어와 구별할 수 없기 때문입니다.

다시 쓰기. 에이전트가 구성 텍스트를 다시 쓸 때 그대로 둔 핸들은 원래 값으로 돌아갑니다. 그래서 에이전트는 비밀번호를 몰라도 노드의 포트나 이름을 바꾸거나 섹션의 순서를 바꿀 수 있습니다. 핸들은 옮기거나 복사할 수도 있지만 두 가지 제한이 있습니다:

  • 같은 종류의 필드로만 돌아갑니다 — 비밀번호 핸들은 비밀번호 필드로;
  • 그 줄이 시크릿이 나온 서버와 같은 서버에 닿아야 합니다: 프록시의 서버, URL의 호스트, 또는 같은 [General] 키.

그 밖의 자리에 있는 핸들 — 다른 서버로 가는 줄, 규칙 안, 지어낸 것, 만료된 것(아래 참조) — 은 줄 번호와 이유와 함께 거부되며, 아무것도 적용되지 않습니다. 그 값은 직접 입력해야 합니다. 에이전트가 새 시크릿을 원문 그대로 쓰면 그대로 받아들이지만, 물론 그때는 이미 에이전트의 컨텍스트에 들어가 있습니다.

같은 값에는 언제나 같은 핸들이 붙으므로, 에이전트는 두 노드가 같은 비밀번호를 쓴다는 것을 알 수 있습니다. 핸들은 그것을 발급한 프로세스가 살아 있는 동안만 유효합니다 — Chute Mac이 종료될 때까지, 또는 Chute iOS나 Chute tvOS의 VPN이 끊길 때까지. 그 뒤에는 거부되므로 에이전트가 구성을 다시 읽게 하십시오.

마스킹은 구성의 시크릿을 대상으로 합니다. 사용자 자신의 트래픽에 있는 자격 증명 — 웹사이트의 쿠키, 앱이 보낸 Authorization 헤더 — 은 구성의 시크릿이 아니므로 마스킹되지 않으며, 이것들이 명시적으로 요청할 때만 제공되는 이유이기도 합니다(아래 참조).

끄기. external-mcp-mask-secrets = false — 또는 앱의 마스킹 스위치 — 로 하면 모든 시크릿이 원문 그대로 에이전트에 전달되고, 에이전트에게도 그렇게 알립니다. 이 자격 증명이 에이전트 모델 제공자의 컨텍스트에 들어가는 것을 받아들일 때만 그렇게 하십시오.

서드파티 콘텐츠

요청과 응답의 헤더와 본문, 로그 줄, 스크립트 출력, URL에서 내려받은 모듈 텍스트는 다른 사람이 쓴 것입니다 — 웹사이트, 앱, 서버 운영자. 웹 페이지에는 에이전트에게 내리는 지시처럼 보이도록 쓴 글이 들어 있을 수 있습니다. 그래서:

  • 기본적으로 도구는 메타데이터만 돌려줍니다: 호스트, URL, 포트, 정책, 규칙, 프로세스 이름, 바이트 수, 시간, 상태;
  • 내용은 에이전트가 명시적으로 요청할 때만 — include를 단 get_connection, get_logs, run_script, get_module — untrusted 키 아래에 담겨 오며, 에이전트에게는 이를 지시가 아닌 데이터로 읽으라고 알립니다.

이것은 에이전트의 컨텍스트를 깨끗하게 하고 토큰 비용을 줄이기 위한 것이지 접근 제어가 아닙니다. 토큰을 가진 에이전트는 HTTP 제어 API를 직접 호출해 무엇이든 읽을 수 있습니다.

도구

각 도구는 네 가지 종류 중 하나로 표시되며, 클라이언트는 이를 보고 호출하기 전에 사용자에게 물을지를 정합니다.

읽기 전용

도구 하는 일
get_status 엔진이 실행 중인지, 어떻게 실행 중인지: 아웃바운드 모드, 각 스위치, TUN, 리스너, 메모리, 연결 수, 지난 실행이 끝난 방식
get_network_summary 기기가 있는 네트워크 — 종류, Wi-Fi 이름, 라우터 — 와 그곳에서 SSID 설정이 Chute를 일시 중지하는지, 기기의 주소
get_traffic 업로드·다운로드 바이트와 현재 속도
list_policies 그룹과 현재 선택, 최종적으로 닿는 노드와 그 지연 시간. group은 그룹 하나 전체, detail은 모든 구성원
get_policy 정책 하나의 구성 줄과 엔진이 지금 알고 있는 것: 서버, 포트, UDP, 지연 시간, 최종 목적지
list_rules 일치 순서대로의 규칙과 각 규칙의 출처. filter로 좁힘
match_rule 요청이 어느 규칙과 정책에 걸리는지, 이름 해석 전후 각각. 실제로 보내지는 않음
list_user_rules 엔진 실행 중에 추가된 규칙
list_connections 열려 있거나 기록된 연결, 메타데이터만. 호스트, 프로세스, 정책, 실패 여부로 필터
get_connection 연결 하나. 헤더와 본문은 include에 지정했을 때만
get_logs 엔진 로그의 줄. 최소 수준과 키워드로 필터
get_events 이번 실행의 주요 사건. after로 새 것만
list_dns_cache DNS 레코드와 각각에 응답한 서버
query_dns 엔진 자신의 리졸버로 이름을 해석하고, 어느 것이 응답했는지 알려 줌
geoip_lookup 주소나 이름의 국가와 ASN
get_profile 실행 중인 구성을 한 페이지씩, revision과 함께
list_profile_sections 구성의 섹션들. 각각의 revision과 쓸 수 있는지 여부
get_profile_section 섹션 하나의 텍스트와 revision
validate_profile 다시 로드할 때처럼 구성을 해석하되 적용하지 않음
get_log_level 로그 수준과 기록 중인 섹션
list_scripts run_script로 실행할 수 있는 generic 스크립트
list_rewrites 적용 중인 다시 쓰기 규칙과 모의 응답 규칙, MitM 호스트 목록
list_mitm_hosts 복호화 중인 호스트
list_modules 로드된 모듈, 그 id, 켜져 있는지 여부
get_module 모듈 하나의 텍스트
list_external_resources 외부에서 가져오는 규칙 세트, 규칙 공급자, 프록시 공급자, 모듈: 각각의 갱신 시각, 항목 수, 마지막 오류
get_tailscale Tailscale 노드: ID, 출구 노드, DERP, detail로 피어
watch_events 1~60초 동안 엔진의 이벤트를 지켜보고 모두 돌려줌

테스트

이 도구들은 스스로 트래픽을 보냅니다.

도구 하는 일
test_policy 정책을 거쳐 HTTPS 요청 하나를 보내고 상태 코드와 시간을 돌려줌. 그룹이면 모든 구성원을 하나씩 보고
test_policies 여러 정책 또는 모든 정책을 하나씩 보고
ping 기기에서 직접 ICMP, 또는 TCP 연결을 여는 데 걸린 시간
egress_probe 물리 네트워크에서의 이 기기 자신의 주소
internet_test 프록시 없이 internet-test-url에 요청 한 번: 인터넷이 되기는 하는지
run_diagnostics 엔진 상태, 인터넷 테스트, 출구 주소, DNS 조회를 한 단계씩 한 뒤 보고서

test_policy가 그룹 구성원에 대해 보고하는 시간은 HTTPS 왕복 시간입니다. 그룹 자체 테스트는 보통 평문 HTTP URL을 가져오므로 수치가 다르며, 그룹은 이 수치로 선택하지 않습니다. 그룹 자체 테스트는 그 뒤에 실행되어 평소처럼 선택합니다.

설정 변경

도구 하는 일
set_outbound_mode 규칙, 전역, 직접
select_policy select 그룹의 구성원, 또는 전역 선택(GLOBAL). 자동 그룹은 스스로 고르므로 거부
set_feature MitM 또는 트래픽 기록을 켜거나 끔
set_log_level 로그 수준과 기록할 섹션. 다시 로드할 필요 없음
edit_user_rules 런타임 규칙을 교체, 추가, 비움. 규칙이 아닌 줄이 하나라도 있으면 변경 전체를 거부
add_mitm_host, remove_mitm_host MitM 호스트 목록
add_rewrite, remove_rewrite URL·헤더·본문 다시 쓰기 규칙 또는 모의 응답 규칙. 구성 줄의 형식으로
set_modules_enabled 모듈을 켜거나 끔
update_external_resource 규칙 세트, 규칙 공급자, 프록시 공급자를 지금 가져옴
replace_profile_section 구성의 섹션 하나를 교체(또는 추가)하고 다시 로드
replace_profile 구성 전체를 교체하고 다시 로드

파괴적

도구 하는 일
reload_profile 런타임 변경을 되돌림: 다시 쓰기, MitM 호스트, 모듈 스위치가 구성대로 돌아감
kill_connection 열린 연결 하나를 닫음. 상대편 앱에는 연결이 끊긴 것으로 보임
flush_dns DNS 캐시 전체, 또는 이름 하나의 레코드를 지움
run_script 구성의 generic 스크립트 하나를 실행하고 출력을 돌려줌

도구의 응답 방식

  • 기본은 요약. 목록 도구는 각 항목의 주요 필드만 줍니다. detail: true는 모든 필드를 주며, 그만큼 토큰을 더 씁니다.
  • 페이지. 긴 목록과 텍스트는 offset과 limit를 받고, 더 있으면 next_offset을 돌려줍니다.
  • 최대 256 KB. 그보다 큰 결과는 항목이나 줄 단위로 잘리며, 중간에서 잘리지 않고 truncated: true와 이어서 읽을 next_offset이 붙습니다 — 받는 것은 언제나 올바른 JSON입니다.
  • 오류는 문장으로. 실패한 도구는 상태 코드만이 아니라 에이전트가 대처할 수 있는 문장으로 이유를 말합니다.

변경이 얼마나 유지되는가

Chute iOS와 Chute tvOS에서는 모든 변경이 실행 중인 엔진 안에서만 이루어집니다. 구성 파일에도 앱 자체 설정에도 아무것도 쓰지 않으므로, 다시 시작하면 그 내용으로 돌아갑니다. 웹 콘솔과 같습니다.

Chute Mac에서는 다음 변경을 앱이 유지합니다. 앱 자체 메뉴에서 같은 변경을 했을 때처럼 유지되므로 다시 시작한 뒤에도 남습니다. 에이전트가 하든, 웹 콘솔이나 chute 명령, HTTP 제어 API로 하든 마찬가지입니다:

  • 아웃바운드 모드와 정책 선택(글로벌 선택 포함, set_outbound_mode, select_policy): 앱이 기억합니다.
  • MitM과 트래픽 기록(set_feature): 현재 구성 파일에 씁니다.
  • 구성 자체(replace_profile, replace_profile_section): 현재 구성 파일에 쓴 뒤, 앱의 저장 및 적용과 같은 방식으로 적용합니다.

이 결과에는 persisted: true가 붙으며, 에이전트가 읽는 도구 설명에도 미리 그렇게 적혀 있습니다. 다음 경우에는 구성 쓰기가 거부되고 아무것도 쓰지 않습니다:

상황 코드 할 일
메인 창에 저장하지 않은 변경이 있음 user_editing 먼저 앱에서 저장하거나 버리십시오
구성 파일이 Chute 밖에서 바뀌었음 file_changed 먼저 Chute에서 다시 불러오십시오
현재 구성이 로컬 파일이 아님 profile_missing —
앱이 대화 상자를 띄우고 있음 needs_user_action 대화 상자에 답한 뒤 다시 시도하십시오

엔진이 거부한 구성도 파일에 쓰지 않습니다. 앱이 10초 안에 끝내지 못하면 에이전트는 host_busy를 받습니다. 변경이 그래도 적용될 수 있으므로, 에이전트는 상태를 다시 읽은 뒤 재시도할지 정합니다. 알아 둘 점이 하나 있습니다: set_feature는 MitM이나 트래픽 기록을 즉시 바꾸고 스위치를 파일에 쓰지만 구성을 다시 로드하지는 않습니다. 그래서 바로 뒤에 get_profile이 돌려주는 구성 텍스트와 revision은 다음 다시 로드 때까지 예전 그대로입니다.

모든 플랫폼에서 로그 수준, 다시 쓰기, MitM 호스트, 모듈 스위치, 런타임 규칙은 이번 실행 동안만 유효하며, 앱에서 구성을 다시 로드하면 다시 쓰기, MitM 호스트, 모듈 스위치는 되돌아갑니다. reload_profile은 다시 로드하지 않고 다시 쓰기, MitM 호스트, 모듈 스위치를 되돌리며, 로그 수준, 앱의 LAN 연결 스위치, 아웃바운드 모드, 정책 선택은 그대로 둡니다. edit_user_rules의 런타임 규칙은 다시 로드한 뒤에도 남고 엔진이 멈추면 사라집니다.

구성 편집

구성은 섹션 단위로 바꾸도록 에이전트에 요청하십시오. get_profile_section은 섹션 하나와 그 revision을 읽고, replace_profile_section은 그 revision을 붙여 다시 씁니다. 그 사이에 섹션이 바뀌었으면 쓰기는 거부되고 에이전트에게 다시 읽으라고 알립니다. 다른 섹션의 변경은 방해가 되지 않으므로, 두 에이전트가 서로 다른 섹션을 편집할 수 있습니다. 파일 전체를 다루는 get_profile과 replace_profile도 구성 전체의 revision으로 똑같이 동작하지만, 큰 구성은 한 번의 응답에 들어가지 않고 replace_profile은 1 MB까지만 받습니다.

  • #!include 줄이 있는 섹션, 그 뒤의 모든 섹션, #!MANAGED-CONFIG가 있는 섹션은 이 방법으로 쓸 수 없습니다.
  • 쓴 섹션은 다시 로드한 구성에서 읽어 옵니다. [General]과 [MITM]의 값은 Chute의 형식으로 다시 쓰이고 [WireGuard …]의 키는 순서가 바뀌므로, 보낸 텍스트와 다를 수 있습니다. 응답에는 다음에 쓸 새 revision이 들어 있습니다.
  • Chute가 거부한 구성은 적용되지 않으며, 에이전트는 이유를 받습니다. 관리형 구성에서는 다음 관리형 업데이트가 변경을 덮어씁니다.

오래 걸리는 도구의 진행 상황

그룹에 대한 test_policy, test_policies, run_diagnostics, watch_events는 진행하면서 보고합니다. 진행 상황을 요청하고(progressToken) 이벤트 스트림을 받는 클라이언트는 구성원, 정책, 단계, 이벤트마다 notifications/progress를 하나씩 받은 뒤 결과를 받고, 스트림이 닫힙니다. 다른 클라이언트는 도구가 끝났을 때 결과만 받습니다. 오래 걸리는 도구는 최대 60초 동안 실행된 뒤 그때까지의 결과를 돌려주며, 동시에 스트리밍되는 것은 최대 네 개입니다. 클라이언트가 스트림을 닫으면 호출이 취소되지만, 이미 보낸 측정은 끝까지 진행되고 그룹도 갱신됩니다.

보안

  • 토큰은 전권입니다. 가진 사람은 구성, 연결 기록, 로그를 읽고, 라우팅을 바꾸고, 스크립트를 실행할 수 있습니다 — 게다가 HTTP 제어 API의 토큰이기도 합니다. 공유 파일이나 스크린샷에 넣지 마십시오. 바꾸려면 external-http-secret에 새 값을 주십시오.
  • 네트워크에서 수신하면 그 네트워크의 모든 기기가 시도할 수 있습니다. 연결은 평문 HTTP라 토큰이 암호화되지 않은 채 네트워크를 지나고, 실패한 시도도 차단되지 않습니다. 길고 무작위적인 external-http-secret을 쓰고, 신뢰하는 네트워크에서만 사용하며, 끝나면 127.0.0.1로 되돌리십시오.
  • run_script는 코드를 실행합니다. 구성에 정의된 generic 스크립트만 실행하지만, 스크립트가 하는 모든 일 — 요청, 저장, 알림 — 은 에이전트가 요청할 때 일어납니다. 구성 쓰기를 허락받은 에이전트는 스크립트를 추가한 뒤 실행할 수도 있습니다. 무엇을 바꿨는지 확인하십시오.
  • 웹 페이지는 차단됩니다. 서버 자신이 아닌 웹 페이지의 Origin이 붙은 요청은 403으로 거부되고 교차 출처 헤더도 보내지 않으므로, 방문한 사이트가 브라우저를 통해 서버에 닿을 수 없습니다.
S. Smart Rabbit LLC © All Rights Reserved            updated 2026-11-21 15:39:20

이 페이지는 영어판의 번역본입니다. 내용이 다를 경우 영어판이 우선합니다.

results matching ""

    No results matching ""