AdsPower 本地 API 与 adspower-browser

Skills CLI（npx adspower-browser）是用于通过 adspower-browser 命令行工具管理 AdsPower 浏览器配置文件、分组、代理以及应用/分类列表的包管理器。有关本产品及服务的更多信息，请访问 AdsPower 官方网站。

安装 CLI

npm install -g adspower-browser

安装完成后，您可使用以下任一等效命令：

adspower-browser
adspower
ads

adspower-browser 是原始命令名。adspower 和 ads 是指向同一 CLI 入口的别名。

何时使用该技能

当用户执行以下操作时适用：

• 请求创建、更新、删除或列出 AdsPower 浏览器配置文件
• 提及“打开环境”、“配置文件”、“profile”、“AdsPower”等，意指启动已有浏览器环境 → 使用 open-browser（CLI 或 MCP）；完整语义映射关系详见 references/tool-intent-map.md
• 提及浏览器/配置文件的开启、关闭、指纹、UA 或代理设置
• 希望管理分组、标签、代理，或检查 API 状态
• 提及 AdsPower 或 adspower-browser（且 MCP 未运行或不适用）

请确保 AdsPower 正在运行（默认端口为 50325）。如需，可在运行 start 命令时传入 --port / --api-key 参数，或提前设置环境变量 ADS_API_KEY。

该 CLI 本身支持通过 API 密钥启动 AdsPower 应用程序。若已安装 AdsPower 客户端，则也可通过 API 密钥启动 AdsPower 无头模式（headless mode）。

如何运行

下方示例为简洁起见统一使用 ads，但 adspower-browser 和 adspower 的行为完全一致。

ads start -k 

若已设置环境变量 ADS_API_KEY，则可直接运行：

ads start

通用命令格式：

ads  [] [--port PORT] [--api-key KEY]

AdsPower 客户端无头模式（headless mode）启动方式：

AdsPower Global：
Windows设备下： "AdsPower Global.exe" --headless=true --api-key=your_api_key --api-port=50325
MacOS设备下："/Applications/AdsPower Global.app/Contents/MacOS/AdsPower Global" --args --headless=true --api-key=your_api_key --api-port=50325
Linux设备下：adspower_global --headless=true --api-key=your_api_key --api-port=50325

支持两种形式：

1. 单值（简写形式） —— 适用于配置文件相关命令，仅传入一个配置文件 ID 或编号：

   • ads open-browser
   • ads close-browser
   • ads get-profile-cookies
   • ads get-browser-active
   • ads get-profile-ua （单个 ID；数值型 token 将被识别为 profile_no）
   • ads new-fingerprint （单个 ID；数值型 token 将被识别为 profile_no）

2. JSON 字符串 —— 任意命令的完整参数（参见下方命令参考）：

   • ads open-browser '{"profile_id":"abc123","launch_args":"..."}'
   • 无参数命令：可省略 ，或传入 '{}'。

面向 AI 代理的关键命令

您可通过 ads -h 或 ads -h 查看具体参数说明。

CLI 启动与停止

ads start -k                     # 启动 adspower 运行时
ads stop                              # 停止 adspower 运行时
ads restart                           # 重启 adspower 运行时
ads status                            # 获取 adspower 运行时状态

浏览器配置文件 —— 开启/关闭

ads open-browser                     # 或 JSON 格式：profile_id, profile_no?, ip_tab?, launch_args?, headless?, last_opened_tabs?, proxy_detection?, password_filling?, password_saving?, cdp_mask?, delete_cache?, device_scale?
ads close-browser                    # 或 JSON 格式：profile_id? | profile_no?（二者至少提供其一）

浏览器配置文件 —— 创建/更新/删除/列出

ads create-browser '{"group_id":"0","user_proxy_config":{"proxy_soft":"no_proxy"},...}'  # group_id 与 account 字段为必填项；proxy 可选（默认为 no_proxy；当同时提供 proxyid 与 user_proxy_config 时，proxyid 优先级更高）
ads update-browser '{"profile_id":"...",...}'    # profile_id 为必填项
ads delete-browser '{"profile_id":["..."]}'     # profile_id 为必填项
ads get-browser-list '{}'                       # 或 group_id?, limit?, page?, profile_id[]?, profile_no[]?, sort_type?, sort_order?, tag_ids?, tags_filter?, name?, name_filter?
ads get-opened-browser                          # 无需参数

浏览器配置文件 —— 移动/获取 Cookie/UA/指纹/缓存/共享/活跃状态

ads move-browser '{"group_id":"1","user_ids":["..."]}'   # group_id 与 user_ids 均为必填项
ads get-profile-cookies              # 或 JSON 格式：profile_id? | profile_no?
ads get-profile-ua                   # 或 JSON 格式：profile_id[]? | profile_no[]?（最多支持 10 个）；数值型简写将映射至 profile_no[]
ads close-all-profiles                          # 无需参数
ads new-fingerprint                  # 或 JSON 格式：profile_id[]? | profile_no[]?（最多支持 10 个）；数值型简写将映射至 profile_no[]
ads delete-cache-v2 '{"profile_id":["..."],"type":["cookie","history"]}'  # type 可选值：local_storage|indexeddb|extension_cache|cookie|history|image_file
ads share-profile '{"profile_id":["..."],"receiver":"email@example.com"}' # receiver 为必填项；share_type?, content? 可选
ads get-browser-active               # 或 JSON 格式：profile_id? | profile_no?
ads get-cloud-active '{"user_ids":"id1,id2"}'    # user_ids 以英文逗号分隔，最多支持 100 个

内核（Kernel）

ads download-kernel '{"kernel_type":"Chrome","kernel_version":"141"}'
ads get-kernel-list '{}'                         # kernel_type?：Chrome | Firefox（留空表示获取全部）

Patch

ads update-patch '{}'                            # version_type?：stable | beta（默认为 stable）

标签（Tag）

ads get-tag-list '{}'                              # ids?, limit?, page?
ads create-tag '{"tags":[{"name":"My tag","color":"blue"}]}'   # 每项均需提供 name；color 为可选项
ads update-tag '{"tags":[{"id":"1","name":"Renamed"}]}'        # 每项均需提供 id；name?, color? 为可选项
ads delete-tag '{"ids":["tagId1","tagId2"]}'                   # ids 为必填项

分组（Group）

ads create-group '{"group_name":"My Group","remark":"..."}'   # group_name 为必填项
ads update-group '{"group_id":"1","group_name":"New Name"}'    # group_id 与 group_name 均为必填项；remark?（设为 null 表示清空）
ads get-group-list '{}'                         # group_name?, page_size?, page?

应用（分类）

ads check-status                                # 无需参数 —— 检查 API 可用性
ads get-application-list '{"category_id":"123","page":1,"limit":20}'

代理（Proxy）

ads create-proxy '[{"type":"http","host":"127.0.0.1","port":"8080"}]'  # 顶层为数组；每项均需提供 type、host、port
ads update-proxy '{"proxy_id":"proxy-1","proxy_url":"https://refresh.example.com"}'
ads get-proxy-list '{}'                         # limit?, page?, proxy_id[]?
ads delete-proxy '{"proxy_id":["..."]}'        # proxy_id 为必填项，最多支持 100 个

命令参考（完整接口与参数）

浏览器配置文件管理

关于 open-browser、close-browser、create-browser、update-browser、delete-browser、get-browser-list、get-opened-browser、move-browser、get-profile-cookies、get-profile-ua、close-all-profiles、new-fingerprint、delete-cache-v2、share-profile、get-browser-active、get-cloud-active 及其参数，请参阅 references/browser-profile-management.md。

分组管理

关于 create-group、update-group、get-group-list 参数，请参阅 references/group-management.md。

应用管理

关于 check-status、get-application-list 参数，请参阅 references/application-management.md。

代理管理

关于 create-proxy、update-proxy、get-proxy-list、delete-proxy 参数，请参阅 references/proxy-management.md。

标签管理

关于 get-tag-list、create-tag、update-tag、delete-tag 参数，请参阅 references/browser-tag-management.md。

内核管理

关于 download-kernel、get-kernel-list 参数，请参阅 references/browser-kernel-management.md。

Patch 管理

关于 update-patch 参数，请参阅 references/client-patch-management.md。

user_proxy_config（用于 create-browser / update-browser 的内联代理配置）

关于全部字段（proxy_soft、proxy_type、proxy_host、proxy_port 等）及示例，请参阅 references/user-proxy-config.md。若未指定，默认为 {"proxy_soft":"no_proxy"}。若同时提供了 proxyid，则 proxyid 优先级更高，user_proxy_config 将被忽略。

fingerprint_config（用于 create-browser / update-browser 的指纹配置）

关于全部字段（timezone、language、WebRTC、browser_kernel_config、random_ua、TLS 等）及示例，请参阅 references/fingerprint-config.md。

自动化能力（本 CLI 不支持）

诸如 navigate、click-element、fill-input、screenshot 等依赖持久化浏览器连接的命令，未通过本 CLI 暴露。如需浏览器自动化能力，请使用 local-api-mcp MCP 服务器。

深入文档

包含完整枚举值与字段列表的参考文档：

当您需要确切允许值或语义细节时，请查阅上述文档；本文档主体内容仅为概要说明。