蜘蛛 IP AI 工具使用指南（Skills + MCP）

在 Claude Code、Cursor、Codex 等 AI 客户端中，用自然语言查询蜘蛛 IP 余额、选购代理、生成连接配置，以及续费和管理子账号。

一次安装，同时配置 Skill 与 MCP： MCP 连接你的蜘蛛 IP 账号，执行实际查询和操作；Skill 指导 AI 选择产品、安排步骤并核对结果。只安装 Skill 不能连接账号。

支持动态住宅流量、动态住宅不限流量（带宽）、静态住宅、静态住宅 IPv6 和数据中心。具体可用操作以产品规则和当前工具为准。

1. 使用前准备

准备一个蜘蛛 IP 账号、支持本地 MCP 的 AI 客户端，以及以下软件：

Node.js 20 或更新版本，安装包需提供 npm 和 npx。
Git，并确保电脑能访问 GitHub、npm 和蜘蛛 IP 服务。

安装后重新打开终端，检查版本：

node --version
npm --version
git --version

本项目在本机通过 stdio 运行，没有远程 MCP URL。不要把蜘蛛 IP 官网或 API 地址填成 MCP 地址。

获取 API Key

登录蜘蛛 IP 网站，点击头像进入 API Keys（手机端在“我的”中），创建并复制完整 Key。安装时粘贴到本机终端即可。

API Key 获取方式

API Key 是安装和运行的必填项，只读模式也需要。 它不是网站登录密码或代理连接密码，不要发给 AI 或放进共享截图。查看获取方法。

2. 安装 Skill 与 MCP

以下两种方式任选一种，都会进入同一个安装流程。

方式 1：一键安装

在 PowerShell、Git Bash 或 macOS/Linux 终端中执行：

npx -y github:Lianzhou-Information-Technology-Co-Ltd/zhizhuip-agent-tools install

命令会自动下载项目、安装依赖并构建，无需先下载源码或单独运行 npm ci。首次执行请等待下载与构建完成。

方式 2：Git 下载到本地安装

在准备存放项目的目录打开终端，依次执行：

git clone https://github.com/Lianzhou-Information-Technology-Co-Ltd/zhizhuip-agent-tools.git
cd zhizhuip-agent-tools
npm ci
node dist/src/index.js install

git clone 下载项目，cd 进入项目目录，npm ci 安装依赖并自动构建，最后一条命令启动安装器。已有源码或已下载 ZIP 时，进入包含 package.json 和 package-lock.json 的目录，从 npm ci 开始即可。

完成安装

用方向键移动，按空格勾选一个或多个客户端，再按回车继续。
用方向键选择“当前用户的所有项目”或“当前项目”，按回车确认，再核对显示的安装位置。
粘贴 API Key 并回车。输入会显示首尾、中间遮罩；可退格修改，Ctrl+C 取消。
安装器先查询用户信息验证 Key，通过后才写入 Skill 和 MCP 配置。

范围菜单初始选中“当前用户的所有项目”；选中 Windsurf 或 Cline 时，只提供全局范围。选择客户端、安装范围或输入 Key 时，均可按 Ctrl+C 取消。

成功输出示例：

API Key 验证通过，开始安装。
codex：Skill 和 MCP 配置已安装
请重启对应客户端，即可使用蜘蛛 IP。

支持颜色的终端中，成功提示为绿色，Key 验证失败为红色。手动输错 Key 后可继续输入；验证未通过不会覆盖原配置，也不会执行购买。

如果终端已设置 ZHIZHUIP_TOKEN，安装器会直接读取它；验证失败会退出，需修正变量后重新运行。非交互安装还必须用 --agents 指定客户端，具体写法见环境变量安装说明。

3. 客户端与安装选项

支持的客户端

客户端	`--agents` ID	安装范围
Claude Code	`claude-code`	全局 / 项目
Cursor	`cursor`	全局 / 项目
Codex	`codex`	全局 / 项目
Gemini CLI	`gemini-cli`	全局 / 项目
OpenCode	`opencode`	全局 / 项目
经典 Windsurf	`windsurf`	仅全局
Cline（VS Code 扩展）	`cline`	仅全局
VS Code Copilot	`vscode`	全局 / 项目

Claude Desktop 使用后文的手工 MCP 配置。Windsurf 采用经典配置目录；Cline 和 VS Code 采用本机默认用户配置，远程开发、其他 Profile 或 Insiders 需另外核对位置。

只安装到 Codex：

npx -y github:Lianzhou-Information-Technology-Co-Ltd/zhizhuip-agent-tools install --agents codex

一次安装到多个客户端：

npx -y github:Lianzhou-Information-Technology-Co-Ltd/zhizhuip-agent-tools install --agents claude-code,cursor,codex

Git 本地方式在源码目录使用 node dist/src/index.js install，后面追加相同选项。

常用选项

选项	用途
`--agents codex,cursor`	指定客户端并跳过客户端选择菜单；省略时交互多选。
`--scope global`	指定当前用户全局安装，并跳过范围选择菜单。
`--scope project`	只配置运行命令时所在的项目，并跳过范围选择菜单。
`--readonly`	只启用标为只读的工具，保留配套 Skill。
`--dry-run`	预览安装位置，不读 Key、不请求验证、不写文件。
`--list` / `--help`	查看客户端列表或完整帮助，不执行安装。

未指定 --scope 时，交互终端会显示范围选择菜单；非交互执行仍默认使用 global。

项目安装前，先进入要使用蜘蛛 IP 的业务项目，例如：

cd "<你的业务项目目录>"
npx -y github:Lianzhou-Information-Technology-Co-Ltd/zhizhuip-agent-tools install --agents codex --scope project

使用本地源码时，也先进入业务项目，再运行 node "<工具源码目录的绝对路径>/dist/src/index.js" install --agents codex --scope project，不要把源码目录误当作业务项目。

配置保存在哪里

安装器会显示 Skill 与 MCP 配置的位置。MCP 运行文件保存在 ~/.zhizhuip-agent-tools/versions/，客户端通过 Node.js 直接启动它，不依赖 npx 缓存一直存在。

API Key 保存在所选客户端的 ZHIZHUIP_TOKEN 环境配置中，不写入 Skill；API 地址和超时也会同步保存。每个客户端独立保存 Key，配置和备份不要提交或分享。 移动 Node.js 安装路径后需重新安装。

4. 安装后怎样使用

先确认连接

重启所选客户端，按提示启用 zhizhuip MCP 和 Skill、信任项目并允许工具调用。然后对 AI 说：

使用蜘蛛 IP 工具查询我的账号余额。

助手实际调用工具并返回余额，说明本次 MCP 与管理接口查询成功；这不等于已经测试了代理流量转发。

当前 MCP 提供 44 个工具，其中 21 个标为只读、23 个为写操作。Skill 覆盖这些工具的使用流程，但不代表能调用网站上的所有功能。

查询账号与用量

列出我的静态住宅原生子账号，显示国家、IP 和到期时间。

查看动态住宅永久流量子账号最近 7 天的用量，按使用量排序。

子账号列表有分页；查询全部时需要继续翻页。子账号每日流量单次查询最多 30 天，结束日期不能晚于今天。

选购、续费与管理

我想购买 10 GB 动态住宅永久流量。先查询价格和优惠券，列出方案，等我确认再下单。

帮我检查选中的静态住宅子账号能否续费 30 天，列出账号和费用，等我确认。

为选中的动态住宅流量子账号设置每日流量上限，先展示目标、数值及可能影响的其他配置。

购买、续费和升级可能扣除余额；测试 IP 也不是免费试用。删除子账号不可恢复。修改备注、限流或账密可能同时影响协议等其他设置，若要求其他配置不变，应先核实，不直接执行。

获取已有代理连接配置

用我已有的美国动态住宅账号生成 SOCKS5 连接配置，不购买、不创建账号、不发送测试流量。

为这个动态住宅流量账号生成 20 分钟的美国会话配置。

助手会根据实际返回的入口、端口、用户名和密码生成配置。当前没有独立的“提取出口 IP”或“执行换 IP”工具；实际出口 IP 需要通过代理请求观察，可能消耗流量。

更换 Session 不等于创建子账号，也不保证出口一定不同或始终不变。详细参数见代理连接说明。

产品范围与重要限制

产品	常用功能
动态住宅流量（永久、期限）	购买流量、查询用量、新建与删除子账号、设置账密和流量上限、查询白名单。
动态住宅不限流量（带宽）	查询子账号、新购、续费、升级带宽、申请退单。
静态住宅 IPv4	查询账号和库存、购买、续费、管理账密和端口、查询及升级带宽、申请退单。
静态住宅 IPv6	查询账号、购买、续费、自定义账密。
数据中心	查询账号、购买、续费、管理账密、预约 IP。

动态流量新购为整数 1–5000 GB；期限流量当前仅支持 30 天。静态 IPv6 购买与续费不接收优惠券。
动态不限流量带宽每次新购一个子账号，入口为美国、德国或新加坡，最低 10 Mbps，时长为 30/90/180 天；升级应指定升级后的总带宽。
动态带宽目前没有 MCP 报价和库存查询工具，操作前请在网站核实费用与优惠券。退单需要审核，提交成功不代表退款到账。
流量上限 limit_flow=0 表示删除限制，不表示停用账号；白名单当前只支持查询。

更多适用范围、操作前提和结果核对方式，见工具覆盖表。

5. 操作确认与只读模式

购买、续费、升级、修改、删除等写操作会先展示预览。支持弹窗的客户端由你点击确认；其他客户端由助手转述并等待明确同意。已经拒绝或取消时应停止操作。

预览不会自动查询价格和余额，扣费前需要先核实费用。 确认等待时间结束不等于授权；操作超时也不代表失败，应先检查订单、余额与账号状态，避免重复执行。

只需要查询时，在安装命令后加 --readonly：

npx -y github:Lianzhou-Information-Technology-Co-Ltd/zhizhuip-agent-tools install --agents codex --readonly

恢复全部工具时，以相同客户端和范围重新安装，省略 --readonly。安装器保留写操作确认，不接受 --yes；不要为了省掉提示关闭确认。

6. 更新、更换 Key 与移除

更新版本

一键安装用户按原客户端和范围再次运行安装命令：

npx -y github:Lianzhou-Information-Technology-Co-Ltd/zhizhuip-agent-tools install --agents codex --scope global

npx 可能复用缓存；需要明确管理版本，或重装后仍未更新时，可使用 Git 本地方式。

Git 本地安装用户在源码目录执行：

git pull --ff-only
npm ci
node dist/src/index.js install --agents codex --scope global

更新源码并构建后，必须重新运行 install，才能更新已复制的 Skill 与 MCP。 两种方式都要保留原客户端、范围和 --readonly 设置。项目安装先在源码目录拉取和构建，再回到原业务项目，用源码入口的绝对路径执行 install --scope project。完成后重启客户端，再查询一次余额。

更换 API Key

在网站取得新 Key，用相同客户端和范围重新安装并输入；若设置了 ZHIZHUIP_TOKEN，先更新该变量。验证通过后保存，重启客户端生效；验证失败不覆盖旧配置。

只重装 Codex 不会更新 Cursor，多客户端需分别选择或一次选齐。重新安装也不会自动吊销网站上的旧 Key。

暂停使用或移除

当前没有 uninstall 命令。暂停使用可在客户端停用 zhizhuip；完全移除时，删除对应 MCP 配置项和 zhizhuip Skill 文件夹，保留其他服务。

清理共享 Skill 目录、~/.zhizhuip-agent-tools/ 运行文件或旧备份前，确认其他客户端已不再引用。本地移除不会删除网站产品，也不会吊销 API Key；Key 需在网站单独停用。

7. 手工配置 MCP（可选）

已完成一体安装的客户端可跳过本节。Claude Desktop、只想使用 MCP 或安装器未适配的客户端，可以生成配置片段后手工添加：

npx -y github:Lianzhou-Information-Technology-Co-Ltd/zhizhuip-agent-tools setup --npx

setup 只输出配置，不修改客户端文件、不安装 Skill，也不执行 Key 验证。将输出中的 Key 占位值替换为自己的 API Key，按对应客户端格式合并 zhizhuip 条目。

例如 Claude Desktop 的 claude_desktop_config.json：

{
  "mcpServers": {
    "zhizhuip": {
      "command": "npx",
      "args": ["-y", "github:Lianzhou-Information-Technology-Co-Ltd/zhizhuip-agent-tools"],
      "env": {
        "ZHIZHUIP_TOKEN": "YOUR_API_KEY"
      }
    }
  }
}

Windows 若找不到 npx，将 command 改为 cmd，并在 args 最前加入 "/c", "npx"。保存后重启客户端，再查询余额。

本地源码用户可在构建后运行 node dist/src/index.js setup，生成直接引用源码路径的配置；此方式需保留源码目录。其他客户端配置见手工接入指南。

若客户端支持 Skill，可将项目中的 skills/zhizhuip/ 整个目录放入其技能目录，保留 references/，并重载客户端。只复制 SKILL.md 会遗漏参考文件；Skill 和 MCP 应使用同一项目版本。

8. 常见问题

问题	处理方法
Key 验证失败或超时	核对完整 Key、网站状态和网络。手动输入可重输；环境变量或非交互执行需修正后重跑。
为什么没有提示输入 Key，失败就退出？	可能已设置 `ZHIZHUIP_TOKEN`。更新该变量，或清除后在交互终端重跑。
找不到 node、npx 或 git	安装 Node.js 和 Git 后重新打开终端及客户端，检查版本号。
安装成功但没有工具或 Skill	重启客户端，检查 `zhizhuip` 是否启用、项目是否信任、是否在支持工具的模式中；特殊 Profile 或远程环境需核对安装路径。
多个客户端只有部分成功	保留成功项，检查失败项的配置格式、权限和路径后单独重跑。
找不到购买、续费工具	检查 `--readonly` 和客户端工具权限；调整后重启。
已确认但仍提示等待	遵循返回的等待提示，不循环重试；确认码过期或参数变化后重新预览。
提示余额不足、需实名或访问频繁	按接口提示充值、完成验证或稍后重试。
扣费操作超时	先到网站核对订单、余额和子账号状态，不直接重复下单。

更多配置和排查方法见完整使用指南；业务流程见Skill 操作说明。

蜘蛛 IP AI 工具使用指南（Skills + MCP）

1. 使用前准备​

获取 API Key​

2. 安装 Skill 与 MCP​

方式 1：一键安装​

方式 2：Git 下载到本地安装​

完成安装​

3. 客户端与安装选项​

支持的客户端​

常用选项​

配置保存在哪里​

4. 安装后怎样使用​

先确认连接​

查询账号与用量​

选购、续费与管理​

获取已有代理连接配置​

产品范围与重要限制​

5. 操作确认与只读模式​

6. 更新、更换 Key 与移除​

更新版本​

更换 API Key​

暂停使用或移除​

7. 手工配置 MCP（可选）​

8. 常见问题​