adspower-browser

使用 adspower-browser 调用 AdsPower 本地 API

Skills CLI（npx adspower-browser）是一个包管理器，可通过 adspower-browser CLI 操作 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）。如有需要，传入 --port / --api-key，或在运行 start 前设置 ADS_API_KEY 环境变量。

CLI 本身支持通过 API key 启动 AdsPower 应用程序。如果已安装 AdsPower 客户端，也可以通过 API key 启动 AdsPower 无头模式。

运行方法

以下示例为简洁起见使用 ads，但 adspower-browser 和 adspower 的用法相同。

ads start -k <KEY>

如果已设置 ADS_API_KEY 环境变量，可以直接使用以下命令启动 CLI：

ads start

通用命令格式：

ads <command> [<arg>] [--port PORT] [--api-key KEY]

AdsPower 客户端无头模式：

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

<arg> 的两种形式：

1. 单个值（简写） — 对于与配置文件相关的命令，传入一个配置文件 ID 或编号：

   • ads open-browser <profile_id>
   • ads close-browser <profile_id>
   • ads get-profile-cookies <profile_id>
   • ads get-browser-active <profile_id>
   • ads get-profile-ua <profile_id>（单个 ID；数字形式的参数会被视为 profile_no）
   • ads new-fingerprint <profile_id>（单个 ID；数字形式的参数会被视为 profile_no）

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

   • ads open-browser '{"profile_id":"abc123","launch_args":"..."}'
   • 无参数的命令：省略 <arg> 或使用 '{}'。

与 AI Agent 配合使用的基本命令

你可以使用 ads -h 或 ads <command> -h 查看具体参数。

启动和停止 CLI

ads start -k <KEY>                    # Start the adspower runtime
ads stop                              # Stop the adspower runtime
ads restart                           # Restart the adspower runtime
ads status                            # Get the status of the adspower runtime

浏览器配置文件 – 打开／关闭

ads open-browser <profile_id>                    # Or 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 <profile_id>                   # Or JSON: profile_id? | profile_no? (one required)

浏览器配置文件 – 创建／更新／删除／列出

ads create-browser '{"group_id":"0","user_proxy_config":{"proxy_soft":"no_proxy"},...}'  # group_id required: always include it; use "0" for Ungrouped; if given a group name, call get-group-list first; include either proxyid or user_proxy_config
ads update-browser '{"profile_id":"...",...}'    # profile_id required
ads delete-browser '{"profile_id":["..."]}'     # profile_id required
ads get-recycle-bin-list '{}'                   # page?, limit? (1-100). Omit either to use the Local API backend default. Last 30 days only
ads restore-recycle-bin '{"profile_id":["id1","id2"],"group_id":"123"}'  # profile_id[] or profile_no[], group_id required
ads get-browser-list '{}'                       # CLI defaults to page=1,limit=200 (Local API itself returns only 1). Or group_id?, limit?, page?, profile_id[]?, profile_no[]?, sort_type?, sort_order?, tag_ids?, tags_filter?, name?, name_filter?
ads get-opened-browser                          # No params

列出所有环境： get-browser-list 会返回 total_count / total_pages。CLI 默认发送 page=1,limit=200，因此一次调用最多可获取 200 个配置文件。如果 total_pages > 1，请使用相同的筛选条件并将 page 递增 1，持续调用，直到获取所有页面的数据。对于“对某个分组中的所有环境执行操作”这类任务，请先收集所有页面的数据，再对返回的每个 profile_id 执行操作——切勿只处理第一页。

浏览器配置文件 – 移动／Cookie／UA／指纹／缓存／共享／活跃状态

ads move-browser '{"group_id":"1","user_ids":["..."]}'   # group_id + user_ids required
ads get-profile-cookies <profile_id>             # Or JSON: profile_id? | profile_no?
ads get-profile-ua <profile_id>                  # Or JSON: profile_id[]? | profile_no[]? (up to 10); numeric shorthand maps to profile_no[]
ads close-all-profiles                          # No params
ads new-fingerprint <profile_id>                 # Or JSON: profile_id[]? | profile_no[]? (up to 10); numeric shorthand maps to 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 protected]"}' # receiver required; share_type?, content?
ads get-browser-active <profile_id>              # Or JSON: profile_id? | profile_no?
ads get-cloud-active '{"user_ids":"id1,id2"}'    # user_ids comma-separated, max 100

内核

ads download-kernel '{"kernel_type":"Chrome","kernel_version":"141"}'
ads get-kernel-list '{}'                         # kernel_type?: Chrome | Firefox (omit to get all)

补丁

ads update-patch '{}'                            # version_type?: stable | beta (default stable)

标签

ads get-tag-list '{}'                              # ids?, limit?, page?
ads create-tag '{"tags":[{"name":"My tag","color":"blue"}]}'   # name required per item; color optional
ads update-tag '{"tags":[{"id":"1","name":"Renamed"}]}'        # id required per item; name?, color?
ads delete-tag '{"ids":["tagId1","tagId2"]}'                   # ids required

分组

ads create-group '{"group_name":"My Group","remark":"..."}'   # group_name required
ads update-group '{"group_id":"1","group_name":"New Name"}'    # group_id + group_name required; remark? (null to clear)
ads get-group-list '{}'                         # group_name?, page_size?, page?

成员

ads create-member '{"user_group_id":"...","email":"[email protected]","password":"password1","identity":4}'  # identity: 2 admin, 3 manager, 4 staff; manager optional; member only for identity 3
ads update-member '{"user_id":"...","name":"Alice"}'   # omit to keep; empty name/manager/remark/member/authorized_group can clear; do not empty email or identity
ads reset-member-password '{"user_id":"..."}'          # unbind_phone?: 0|1; new_password is in the response
ads delete-member '{"user_id":"..."}'                  # permanent, not recoverable
ads get-member-list '{}'                               # user_group_id?, user_id[]?, email[]?, page?, limit? (default 50, max 200)
ads get-member-group-list '{}'                         # page?, limit? (default 50, max 200)

应用程序（类别）

ads check-status                                # No params – API availability
ads get-application-list '{"category_id":"123","page":1,"limit":20}'

代理

ads create-proxy '[{"type":"http","host":"127.0.0.1","port":"8080"}]'  # top-level array; type, host, port required per item
ads update-proxy '{"proxy_id":"proxy-1","proxy_url":"https://refresh.example.com"}'
ads get-dynamic-proxy-traffic                    # start_date?, end_date? (YYYY-MM-DD); available traffic, package expiration dates, daily usage; defaults to current month through today
ads get-proxy-list '{}'                         # limit?, page?, proxy_id[]?
ads delete-proxy '{"proxy_id":["..."]}'        # proxy_id required, max 100

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

浏览器配置文件管理

open-browser、close-browser、create-browser、update-browser、delete-browser、get-recycle-bin-list、restore-recycle-bin、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。

成员管理

有关 create-member、update-member、reset-member-password、delete-member、get-member-list 和 get-member-group-list 的参数，请参阅 references/member-management.md。

应用管理

有关 check-status 和 get-application-list 的参数，请参阅 references/application-management.md。

代理管理

有关 create-proxy、update-proxy、get-proxy-list、get-dynamic-proxy-traffic 和 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。

补丁管理

有关 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。对于 create-browser，请提供 proxyid 或 user_proxy_config。如果用户创建浏览器配置文件时未指定代理，请将 user_proxy_config 设置为 {"proxy_soft":"no_proxy"}。对于 update-browser，仅在更改配置文件代理时提供 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 服务进行自动化。

深入文档

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

参考文档	描述	使用时机
references/tool-intent-map.md	MCP/CLI 工具名称与中英文 intent、triggers 对照表（与 toolIntentMetadata.ts 同源）。	根据用户的自然语言选择对应的 CLI 命令或 MCP 工具（尤其是 open-browser）。
references/browser-profile-management.md	open-browser、close-browser、create-browser、update-browser、delete-browser、get-recycle-bin-list、restore-recycle-bin、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 参数。	任何浏览器配置文件操作（打开、创建、更新、删除、回收、列出、移动、Cookie、UA、缓存、共享、状态）。
references/group-management.md	create-group、update-group、get-group-list 参数。	创建、更新或列出浏览器分组。
references/member-management.md	create-member、update-member、reset-member-password、delete-member、get-member-list、get-member-group-list 参数。	创建、更新、列出或删除团队成员和成员分组。
references/application-management.md	check-status、get-application-list 参数。	检查 API 是否可用或列出应用（类别）。
references/proxy-management.md	create-proxy、update-proxy、get-proxy-list、get-dynamic-proxy-traffic、delete-proxy 参数和枚举值。	创建、更新、列出或删除代理；查询团队动态代理的可用流量、套餐到期日期和每日消耗量。
references/browser-tag-management.md	get-tag-list、create-tag、update-tag、delete-tag 参数。	列出、创建、更新或删除浏览器标签。
references/browser-kernel-management.md	download-kernel、get-kernel-list 参数。	下载指定内核并查询支持的内核版本。
references/client-patch-management.md	update-patch 参数。	将 AdsPower 客户端更新到最新补丁渠道（stable/beta）。
references/user-proxy-config.md	完整的 user_proxy_config 字段列表（proxy_soft、proxy_type、proxy_host、proxy_port 等）和示例。	在不使用 proxyid 时，为 create-browser / update-browser 构建内联代理配置。
references/fingerprint-config.md	完整的 fingerprint_config 字段列表（timezone、language、WebRTC、browser_kernel_config、random_ua、TLS 等）和示例。	为 create-browser / update-browser 构建或编辑指纹配置。
references/browser-kernel-config.md	fingerprint_config.browser_kernel_config 的 type 和 version。版本必须与类型（Chrome 或 Firefox）匹配。	创建或更新浏览器时，指定或选择特定浏览器内核（Chrome/Firefox 及其版本）。
references/browser-kernel-download-management.md	download-kernel 参数（kernel_type、kernel_version）。	下载或更新特定浏览器内核版本，并轮询进度/状态。
references/ua-system-version.md	fingerprint_config.random_ua 的 ua_system_version 枚举值：指定的操作系统版本、各系统通用的“任意版本”以及省略时的行为。	创建或更新浏览器时，按操作系统限制或随机生成 UA（例如仅使用 Android，或使用“任意 macOS 版本”）。
需要确切的允许值或语义时，请使用这些内容；上方的主要技能文本仅作摘要。