API 概述

Shadowrocket电脑端提供完整的RESTful API接口，供开发者进行二次开发与自动化集成。API支持节点管理、规则更新、流量查询、连接控制等核心操作，可广泛应用于企业内网管理、运维自动化、监控告警等场景。

接口基础信息

项目 说明
基础地址 http://127.0.0.1:1989/api
认证方式 Authorization: Bearer {token}
响应格式 application/json
字符编码 UTF-8

核心接口列表

1. 获取连接状态

GET /v1/status Response: { "connected": true, "node": "JP-Tokyo-01", "latency_ms": 42, "up_bytes": 12583920, "down_bytes": 89342710 }

2. 切换节点

POST /v1/node/switch Content-Type: application/json { "node_id": "jp-tokyo-02" } Response: { "success": true, "message": "Node switched to jp-tokyo-02" }

3. 更新订阅

POST /v1/subscription/refresh Response: { "success": true, "nodes_count": 28, "updated_at": "2026-08-10T14:32:00Z" }

4. 获取流量数据

GET /v1/traffic?period=day&unit=hour Response: { "period": "2026-08-10", "data": [ {"hour": 0, "up": 1024, "down": 2048}, {"hour": 1, "up": 512, "down": 1024} ] }

自动化脚本实战

场景一：定时节点健康检查

#!/bin/bash # shadowrocket-node-check.sh # 每10分钟执行一次，自动切换到最优节点 API="http://127.0.0.1:1989/api" TOKEN="your_api_token" # 获取节点列表并测速 NODES=$(curl -s -H "Authorization: Bearer $TOKEN" "$API/v1/nodes") BEST=$(echo "$NODES" | jq -r '.nodes | sort_by(.latency) | .[0].id') curl -X POST -H "Authorization: Bearer $TOKEN" \ -d "{\"node_id\": \"$BEST\"}" \ "$API/v1/node/switch" echo "$(date): Switched to $BEST"

场景二：流量超限自动告警

#!/python3 # shadowrocket_traffic_alert.py import requests, json, smtplib API = "http://127.0.0.1:1989/api" TOKEN = "your_api_token" THRESHOLD_GB = 50 traffic = requests.get(f"{API}/v1/traffic", headers={ "Authorization": f"Bearer {TOKEN}" }).json() total = (traffic["up_bytes"] + traffic["down_bytes"]) / (1024**3) if total > THRESHOLD_GB: # 发送告警邮件 print(f"WARNING: Traffic {total:.2f}GB exceeds limit!")

💡 开发提示：API Token可在Shadowrocket设置页面的"开发者选项"中生成，请妥善保管，不要泄露给他人。

Python SDK 快速上手

pip install shadowrocket-sdk from shadowrocket import ShadowrocketClient client = ShadowrocketClient("127.0.0.1", 1989, "your_token") # 获取当前状态 status = client.get_status() print(f"Connected: {status.connected}") print(f"Node: {status.node}") print(f"Latency: {status.latency_ms}ms") # 切换节点 client.switch_node("jp-tokyo-03") # 刷新订阅 result = client.refresh_subscription() print(f"Nodes loaded: {result.nodes_count}")

注意事项