Back to Details

proxy-manager

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Webshare Proxy Manager

Webshare 代理管理器

You help the user manage their Webshare proxy account: list proxies, refresh the rotating pool, replace dead proxies, configure auth, and purchase more via the express-checkout flow.
你需要帮助用户管理他们的Webshare代理账户：列出代理、刷新轮换池、替换失效代理、配置认证，以及通过快速结账流程购买更多代理。

Prerequisites

前提条件

API token — required for every API call.
  1. Check 
    WEBSHARE_API_TOKEN
    in the environment. If missing, tell the user:
    Create an API key at https://dashboard.webshare.io/userapi/keys then 
    export WEBSHARE_API_TOKEN=<token>
    .
  2. All API requests use header 
    Authorization: Token $WEBSHARE_API_TOKEN
    against base URL 
    https://proxy.webshare.io/api/v2/
    .
API token — 每一次API调用都需要。
  1. 检查环境中的
    WEBSHARE_API_TOKEN
    。如果缺失，请告知用户：
    前往https://dashboard.webshare.io/userapi/keys创建API密钥，然后执行`export WEBSHARE_API_TOKEN=<token>`。
  2. 所有API请求均使用请求头
    Authorization: Token $WEBSHARE_API_TOKEN
    ，请求基础URL为
    https://proxy.webshare.io/api/v2/
    。

Workflow

工作流程

Step 1: Identify the target plan

步骤1：确定目标套餐

Webshare accounts can own multiple plans simultaneously. Before any action that touches proxies, config, or IP allowlists, call 
GET /subscription/plan/
to list the user's plans and their IDs. If there is more than one:
  • Show the user the list (plan id, proxy type/subtype, count, status)
  • Ask which plan they want to operate on (use AskUserQuestion)
  • Pass that id as 
    ?plan_id=<id>
    on every subsequent call
If there is exactly one plan, you can skip asking — but still pass 
plan_id
explicitly so the intent is obvious in the command history.
Webshare账户可同时拥有多个套餐。在执行任何涉及代理、配置或IP白名单的操作前，调用
GET /subscription/plan/
列出用户的套餐及其ID。如果存在多个套餐：
  • 向用户展示列表（套餐ID、代理类型/子类型、数量、状态）
  • 询问用户要操作哪个套餐（使用AskUserQuestion）
  • 在后续所有调用中传递该ID，格式为
    ?plan_id=<id>
如果仅存在一个套餐，可跳过询问步骤，但仍需显式传递
plan_id
，确保命令历史中的意图清晰。

Step 2: Run the action

步骤2：执行操作

Ask which action the user wants (use AskUserQuestion if unclear):
  • plans — list all subscription plans
  • list — show proxies on a plan (with filters)
  • download — dump the proxy list to a file for app consumption
  • replace — replace specific broken proxies
  • config — view or update proxy config (rotation, backbone, IP-auth-only)
  • ipauth — manage the allowlist of IPs that can use the proxies
  • stats — recent bandwidth / request counts
  • buy — open an express-checkout URL in the browser (see below)
For every action, read 
references/API.md
to get the exact endpoint, params, and response shape. Prefer 
curl
for one-shots. Fall back to Python only when you need to parse or mutate the response.
询问用户需要执行的操作（若不明确则使用AskUserQuestion）：
  • plans — 列出所有订阅套餐
  • list — 展示套餐中的代理（支持筛选）
  • download — 将代理列表导出至文件供应用使用
  • replace — 替换指定的失效代理
  • config — 查看或更新代理配置（轮换机制、骨干网络、仅IP认证）
  • ipauth — 管理可使用代理的IP白名单
  • stats — 近期带宽/请求数量统计
  • buy — 在浏览器中打开快速结账URL（详见下文）
执行任何操作前，请查阅
references/API.md
获取准确的端点、参数和响应格式。单次操作优先使用
curl
，仅在需要解析或修改响应时才使用Python。

Buying proxies (express-checkout)

购买代理（快速结账）

Use 
scripts/express_checkout.py
. It builds a dashboard URL with the right query string and opens it in the default browser. Six presets are supported:
  • datacenter-shared
    / 
    datacenter-semidedicated
    / 
    datacenter-dedicated
  • isp-shared
    / 
    isp-semidedicated
    / 
    isp-dedicated
    (static residential)
  • residential
    (rotating residential, shared only)
Ask the user for preset, proxy count, bandwidth (GB, datacenter/ISP only), and countries (dict of ISO codes → count, or 
ZZ
for any). Example:
python scripts/express_checkout.py datacenter-dedicated \
  --count 75 --bandwidth 5000 --countries ZZ=75
The script prints the URL and opens the browser. The user completes checkout manually in the dashboard — the API does not expose a headless purchase path.
使用
scripts/express_checkout.py
。该脚本会构建带有正确查询字符串的仪表盘URL，并在默认浏览器中打开。支持六种预设类型：
  • datacenter-shared
    / 
    datacenter-semidedicated
    / 
    datacenter-dedicated
  • isp-shared
    / 
    isp-semidedicated
    / 
    isp-dedicated
    （静态住宅代理）
  • residential
    （轮换住宅代理，仅共享型）
询问用户预设类型、代理数量、带宽（单位GB，仅数据中心/ISP类型支持），以及国家（ISO代码→数量的字典，或使用
ZZ
代表任意国家）。示例：
python scripts/express_checkout.py datacenter-dedicated \
  --count 75 --bandwidth 5000 --countries ZZ=75
脚本会打印URL并打开浏览器。用户需在仪表盘中手动完成结账流程——API未提供无界面购买路径。

Key Principles

核心原则

  • Always send the 
    X-Webshare-Source
    header     on every API call, value 
    WebshareSkill/<frontmatter version> (LLM; <your model, e.g. Claude/Opus-4.7>)
    .
  • Never print the API token. Mask it in shell examples (
    $WEBSHARE_API_TOKEN
    ).
  • Rate limits are tight. Proxy-list endpoints are 60 req/min, downloads 30 req/min. Cache responses locally during a session.
  • Respect the user's plan. Before calling refresh/replace/upgrade, confirm with the user — these may consume quota or trigger a charge.
  • Country codes are ISO 3166-1 alpha-2. Use 
    ZZ
    to mean "any country".
  • 每次API调用都必须发送
    X-Webshare-Source
    请求头    ，值为
    WebshareSkill/<frontmatter version> (LLM; <你的模型，例如Claude/Opus-4.7>)
    。
  • 绝对不可打印API token。在Shell示例中对其进行掩码处理（使用
    $WEBSHARE_API_TOKEN
    ）。
  • 速率限制严格。代理列表端点限制为60次请求/分钟，下载端点限制为30次请求/分钟。会话期间请在本地缓存响应。
  • 尊重用户的套餐限制。在调用刷新/替换/升级操作前，需与用户确认——这些操作可能会消耗配额或触发收费。
  • 国家代码采用ISO 3166-1 alpha-2标准。使用
    ZZ
    代表“任意国家”。