HideMyAndroid Headless API

系统要求

Headless API 让您无需任何应用界面，即可通过 ADB 或任意自动化工具完全控制 HideMyAndroid。此为 高级版 专属功能。

• 高级账户 — Headless API 仅限高级版使用。
• 应用版本 1.2.8 或更高。
• Root + LSPosed — 与 HideMyAndroid 所需的配置相同。请参阅 安装指南。
• ADB 已连接至设备（adb devices 可列出已连接设备）。
• 设备已联网 — 仅在启用代理时需要（会进行实时检测）。

⚠️ 请确保在使用无界面模式之前，应用已获得 VPN 权限。

身份认证

在应用中打开 设置 → 开发者 → Headless API，然后开启 启用。系统会自动生成一个密钥 — 点击 复制。每个请求都需要将此密钥作为 token 参数传入。

请妥善保管密钥 — 任何拥有该密钥且能访问 ADB 的人都可以控制您的配置文件。重新生成 将生成新密钥（旧密钥立即失效）；退出登录将清除密钥。

在本文档中，请将 <your_access_token> 替换为您的密钥，将 <profile_id> 替换为 profile.create 返回的 id。

发起请求

共有两种传输方式，根据值中是否包含冒号 : 来选择

content call 会在冒号处分割每个 --extra 参数，因此无法传递 JSON — 这也是 JSON 值需要通过广播发送的原因。

响应说明。 成功时返回 ok=true（content call）或 result=0（广播）；失败时会附加 error_code 和 error_message。请参阅 错误代码。每个方法都需要传入 token。点击下方任意操作可展开其参数、请求与响应详情。

状态

adb shell content call --uri content://com.wowsoftware.hidemyandroid.headless --method status --extra token:s:<your_access_token>

Bundle[{data={"premium":true,"featureEnabled":true,"freshnessOk":true,"activeProfileId":"a1b2c3d4-...","version":"1.2.8"}, ok=true}]

配置文件

adb shell content call --uri content://com.wowsoftware.hidemyandroid.headless --method profile.list --extra token:s:<your_access_token>

Bundle[{data=[{"id":"a1b2...","name":"Demo","isActive":true,"createdAt":1717000000000,"updatedAt":1717000500000}], ok=true}]

adb shell content call --uri content://com.wowsoftware.hidemyandroid.headless --method profile.get --extra token:s:<your_access_token> --extra id:s:<profile_id>

Bundle[{data={"id":"a1b2...","name":"Demo","isActive":false,"hookFlags":{"hook_wifi":true,...},"proxy":{"enabled":false,...},"deviceMock":{"enabled":false,...},"sim":{"enabled":false,"simCards":[]},"gmails":[],"targetApps":["com.whatsapp"]}, ok=true}]

adb shell content call --uri content://com.wowsoftware.hidemyandroid.headless --method profile.create --extra token:s:<your_access_token> --extra name:s:Demo

Bundle[{data={"id":"a1b2c3d4-..."}, ok=true}]

adb shell content call --uri content://com.wowsoftware.hidemyandroid.headless --method profile.update --extra token:s:<your_access_token> --extra id:s:<profile_id> --extra name:s:"My Profile"

adb shell am broadcast -a com.wowsoftware.hidemyandroid.HEADLESS_UPDATE -p com.wowsoftware.hidemyandroid -e token <your_access_token> -e id <profile_id> -e hookFlags '{"hook_wifi":false,"hook_nearby_bluetooth":false}'

adb shell content call --uri content://com.wowsoftware.hidemyandroid.headless --method profile.delete --extra token:s:<your_access_token> --extra id:s:<profile_id>

Bundle[{data={}, ok=true}]

激活

配置文件只有在激活状态下才会执行伪装。激活操作会强制停止目标应用，使其以新身份重新启动。

adb shell content call --uri content://com.wowsoftware.hidemyandroid.headless --method profile.setActive --extra token:s:<your_access_token> --extra id:s:<profile_id>

Bundle[{data={"id":"a1b2...","isActive":true}, ok=true}]

adb shell content call --uri content://com.wowsoftware.hidemyandroid.headless --method profile.deactivate --extra token:s:<your_access_token>

Bundle[{data={}, ok=true}]

目标应用

目标应用是配置文件将要伪装的应用程序。

adb shell content call --uri content://com.wowsoftware.hidemyandroid.headless --method profile.getApps --extra token:s:<your_access_token> --extra id:s:<profile_id>

Bundle[{data=[{"packageName":"com.whatsapp"}], ok=true}]

adb shell content call --uri content://com.wowsoftware.hidemyandroid.headless --method profile.addApp --extra token:s:<your_access_token> --extra id:s:<profile_id> --extra packageName:s:com.whatsapp

Bundle[{data=[{"packageName":"com.whatsapp"}], ok=true}]

adb shell content call --uri content://com.wowsoftware.hidemyandroid.headless --method profile.removeApp --extra token:s:<your_access_token> --extra id:s:<profile_id> --extra packageName:s:com.whatsapp

Bundle[{data=[], ok=true}]

配置

以下是通过 profile.update 发送的配置值。创建配置文件时的默认值：

⚠️ 包含 enabled:false 的配置将被 保存但不生效 — 值会被保存以便日后启用，但在 enabled:true 之前不会执行任何伪装。地理位置伪装（hook_geo_*）需要一个已设置 enabled:true 且通过实时检测的代理。

hookFlags

默认：全部开启。 格式为 "flag": true|false 的映射表。一次更新会 替换整个映射表 — 未填写的标志将恢复为开启状态。

proxy

默认：关闭。 启用 enabled:true 后，应用将通过代理建立真实连接，读取其位置信息，并为 hook_geo_* 标志填充国家/纬度/经度/时区。实时检测最长耗时约 8 秒；检测失败的代理将返回 PROXY_INVALID 且不会被保存。

adb shell am broadcast -a com.wowsoftware.hidemyandroid.HEADLESS_UPDATE -p com.wowsoftware.hidemyandroid -e token <your_access_token> -e id <profile_id> -e proxy '{"enabled":true,"host":"10.0.0.1","port":1080,"protocol":"SOCKS5"}'

deviceMock

默认：关闭。 模拟设备为其他型号。设置 "enabled":true 并填写以下任意字段 — 所有字段均为可选字符串（默认为空），每个字段对应一个 Android Build 属性：

adb shell am broadcast -a com.wowsoftware.hidemyandroid.HEADLESS_UPDATE -p com.wowsoftware.hidemyandroid -e token <your_access_token> -e id <profile_id> -e deviceMock '{"enabled":true,"manufacturer":"Samsung","brand":"samsung","model":"SM-S918B","device":"dm3q","product":"dm3qxxx","board":"kalama","hardware":"qcom","buildId":"UP1A.231005.007","buildIncremental":"S918BXXU3CWK9","buildType":"user","buildTags":"release-keys","buildFingerprint":"samsung/dm3qxxx/dm3q:14/UP1A.231005.007/S918BXXU3CWK9:user/release-keys","deviceName":"Galaxy S23 Ultra"}'

sim

默认：关闭。 伪装 SIM 卡/运营商信息。设置 "enabled":true 并在 simCards 中提供最多两张 SIM 卡信息。每张 SIM 卡包含以下字段：

networkType 仅接受以下值：

adb shell am broadcast -a com.wowsoftware.hidemyandroid.HEADLESS_UPDATE -p com.wowsoftware.hidemyandroid -e token <your_access_token> -e id <profile_id> -e sim '{"enabled":true,"simCards":[{"slotIndex":0,"carrierName":"AT&T","countryIso":"us","mcc":"310","mnc":"410","operatorCode":"310410","networkType":"LTE"},{"slotIndex":1,"carrierName":"T-Mobile","countryIso":"us","mcc":"310","mnc":"260","operatorCode":"310260","networkType":"NR 5G"}]}'

gmails

默认：空。 虚拟 Google 账号列表 — 仅接受 @gmail.com 地址。新列表将覆盖旧列表；[] 可清空列表。由于不含 :，可直接使用 content call：

adb shell content call --uri content://com.wowsoftware.hidemyandroid.headless --method profile.update --extra token:s:<your_access_token> --extra id:s:<profile_id> --extra 'gmails:s:["[email protected]","[email protected]"]'

完整示例

从零开始的完整配置流程：

# 1. create a profile — copy the returned id into <profile_id> below
adb shell content call --uri content://com.wowsoftware.hidemyandroid.headless --method profile.create --extra token:s:<your_access_token> --extra name:s:Demo

# 2. add a target app
adb shell content call --uri content://com.wowsoftware.hidemyandroid.headless --method profile.addApp --extra token:s:<your_access_token> --extra id:s:<profile_id> --extra packageName:s:com.whatsapp
# 3. add the virtual Gmail accounts
adb shell content call --uri content://com.wowsoftware.hidemyandroid.headless --method profile.update --extra token:s:<your_access_token> --extra id:s:<profile_id> --extra 'gmails:s:["[email protected]","[email protected]"]'

# 4. enable + set the device mock
adb shell am broadcast -a com.wowsoftware.hidemyandroid.HEADLESS_UPDATE -p com.wowsoftware.hidemyandroid -e token <your_access_token> -e id <profile_id> -e deviceMock '{"enabled":true,"manufacturer":"Samsung","brand":"samsung","model":"SM-S918B","device":"dm3q","product":"dm3qxxx","board":"kalama","hardware":"qcom","buildId":"UP1A.231005.007","buildIncremental":"S918BXXU3CWK9","buildType":"user","buildTags":"release-keys","buildFingerprint":"samsung/dm3qxxx/dm3q:14/UP1A.231005.007/S918BXXU3CWK9:user/release-keys","deviceName":"Galaxy S23 Ultra"}'

# 5. enable + set the SIM mock (two cards, full fields)
adb shell am broadcast -a com.wowsoftware.hidemyandroid.HEADLESS_UPDATE -p com.wowsoftware.hidemyandroid -e token <your_access_token> -e id <profile_id> -e sim '{"enabled":true,"simCards":[{"slotIndex":0,"carrierName":"AT&T","countryIso":"us","mcc":"310","mnc":"410","operatorCode":"310410","networkType":"LTE","phoneNumber":"+12025550123","iccid":"8901410123456789012","imsi":"310410123456789"},{"slotIndex":1,"carrierName":"T-Mobile","countryIso":"us","mcc":"310","mnc":"260","operatorCode":"310260","networkType":"NR 5G","phoneNumber":"+12025550456","iccid":"8901260987654321098","imsi":"310260987654321"}]}'

# 6. enable + set the proxy (tested live, ~8s)
adb shell am broadcast -a com.wowsoftware.hidemyandroid.HEADLESS_UPDATE -p com.wowsoftware.hidemyandroid -e token <your_access_token> -e id <profile_id> -e proxy '{"enabled":true,"host":"10.0.0.1","port":1080,"protocol":"SOCKS5"}'

# 7. activate (restarts the target app)
adb shell content call --uri content://com.wowsoftware.hidemyandroid.headless --method profile.setActive --extra token:s:<your_access_token> --extra id:s:<profile_id>

# 8. verify
adb shell content call --uri content://com.wowsoftware.hidemyandroid.headless --method profile.get --extra token:s:<your_access_token> --extra id:s:<profile_id>

错误代码

请求失败时返回 ok=false 并附带以下 error_code 值（广播返回 result=1）：

提示与常见问题

• 广播命令没有任何效果？ 请确认命令中包含了 -p com.wowsoftware.hidemyandroid — Android 会拦截不带此参数的广播。
• 值在 : 后被截断？ 该值包含冒号，content call 会在冒号处截断。请改用 HEADLESS_UPDATE 广播发送该值。
• JSON 广播未生效（Windows 上常见）？ 在桌面 Shell 与设备 Shell 之间传递时，am broadcast 命令中的 JSON 引号（hookFlags、proxy、deviceMock、sim）很容易被转义处理，导致 am 解析出错（值可能被识别为 dat=… 数据 URI）从而不生效。可靠的解决方法是避免在命令行中直接传入 JSON — 将整个工作流放入一个 .sh 文件（单引号可保留所有 JSON 内容完整），然后推送到设备上运行。脚本在 设备上 运行，因此还可以捕获新建的配置文件 id 并在后续步骤中复用：
  bash Copy

  # setup.sh — the full example as one runnable script (runs on the device)
  URI=content://com.wowsoftware.hidemyandroid.headless
  PKG=com.wowsoftware.hidemyandroid
  K=<your_access_token>
  
  # 1. create a profile and capture its id
  ID=$(content call --uri $URI --method profile.create --extra token:s:$K --extra name:s:Demo | grep -o '"id":"[^"]*"' | head -n1 | sed 's/.*"id":"//;s/"//')
  echo "profile id: $ID"
  
  # 2. add a target app
  content call --uri $URI --method profile.addApp --extra token:s:$K --extra id:s:$ID --extra packageName:s:com.facebook.katana
  
  # 3. add the virtual Gmail accounts
  content call --uri $URI --method profile.update --extra token:s:$K --extra id:s:$ID --extra 'gmails:s:["[email protected]","[email protected]"]'
  
  # 4. enable + set the device mock
  am broadcast -a $PKG.HEADLESS_UPDATE -p $PKG -e token $K -e id $ID -e deviceMock '{"enabled":true,"manufacturer":"Samsung","brand":"samsung","model":"SM-S918B","device":"dm3q","product":"dm3qxxx","board":"kalama","hardware":"qcom","buildId":"UP1A.231005.007","buildIncremental":"S918BXXU3CWK9","buildType":"user","buildTags":"release-keys","buildFingerprint":"samsung/dm3qxxx/dm3q:14/UP1A.231005.007/S918BXXU3CWK9:user/release-keys","deviceName":"Galaxy S23 Ultra"}'
  
  # 5. enable + set the SIM mock (two cards)
  am broadcast -a $PKG.HEADLESS_UPDATE -p $PKG -e token $K -e id $ID -e sim '{"enabled":true,"simCards":[{"slotIndex":0,"carrierName":"AT&T","countryIso":"us","mcc":"310","mnc":"410","operatorCode":"310410","networkType":"LTE","phoneNumber":"+12025550123","iccid":"8901410123456789012","imsi":"310410123456789"},{"slotIndex":1,"carrierName":"T-Mobile","countryIso":"us","mcc":"310","mnc":"260","operatorCode":"310260","networkType":"NR 5G","phoneNumber":"+12025550456","iccid":"8901260987654321098","imsi":"310260987654321"}]}'
  
  # 6. enable + set the proxy (tested live, ~8s)
  am broadcast -a $PKG.HEADLESS_UPDATE -p $PKG -e token $K -e id $ID -e proxy '{"enabled":true,"host":"10.0.0.1","port":1080,"protocol":"SOCKS5"}'
  
  # 7. activate (restarts the target app)
  content call --uri $URI --method profile.setActive --extra token:s:$K --extra id:s:$ID
  
  # 8. verify
  content call --uri $URI --method profile.get --extra token:s:$K --extra id:s:$ID

  然后将文件推送到设备并运行：
  bash Copy

  adb push setup.sh /data/local/tmp/setup.sh
  adb shell sh /data/local/tmp/setup.sh

  不含 JSON 的普通 content call 命令可直接在命令行输入，无需脚本。在 Git Bash 中，请在 adb 命令前加上 MSYS_NO_PATHCONV=1，以防止设备路径被重写。
• 修改未生效？ 目标应用必须重启 — 激活配置文件时会自动完成此操作。
• 信任的代理仍返回 PROXY_INVALID？ 设备需要联网才能完成检测，超时上限约为 8 秒，响应较慢的代理可能会超时。