HeadlessX v2.1.2 常用 CLI 命令与工具详解

HeadlessX 的"命令行"是两条轨道：headlessx CLI（官方 npm 包 @headlessx-cli/core，面向日常操作）与 REST API + curl（面向程序化调用，也是 CLI 底层走的通道）。本文按"认证 → 状态 → 抓取 → 批量 → 搜索/YouTube → 代理/配置"的实操顺序，把高频命令全部跑一遍——所有命令在标准部署（见《HeadlessX v2.1.2 Docker Compose 部署指南》）的真实服务上执行，输出逐行取自实测。

一、环境信息

项目	说明
软件版本	HeadlessX v2.1.2（API 服务），CLI v0.1.24
部署形态	标准部署（7 个服务全部运行，部署方法见本专栏部署篇）
服务器	Ubuntu 22.04.4 LTS，API 端口 38473，控制台 34872
测试目标	https://example.com / https://quotes.toscrape.com

二、工具概览

工具	安装/形态	适用场景
headlessx CLI	`npm install -g @headlessx-cli/core`（宿主机 Node.js ≥ 18）	交互式日常操作：抓取、排队、查状态
REST API	服务自带，curl 调用	程序化集成、运维巡检、自动化脚本
MCP 端点	服务自带（`POST /mcp`，SSE 流式）	供 MCP 客户端（AI 助手）接入

CLI 的全部子命令（headlessx --help 实测输出）：

Usage: headlessx [options] [command]

HeadlessX command-line client for website, search, YouTube, and jobs workflows.

Options:
  -V, --version             output the version number
  -k, --api-key <key>       HeadlessX API key
  --api-url <url>           HeadlessX API URL
  -h, --help                display help for command

Commands:
  init [options] [action]   Clone, update, and configure HeadlessX under
                            ~/.headlessx.
  start                     Start the initialized HeadlessX runtime.
  stop                      Stop the initialized HeadlessX runtime without
                            deleting data.
  restart                   Restart the initialized HeadlessX runtime.
  logs [options] [service]  Show runtime logs for the initialized HeadlessX
                            workspace.
  doctor [options]          Inspect local HeadlessX prerequisites, env files,
                            models, and reachability.
  login [options]           Store HeadlessX API credentials locally.
  logout                    Remove stored credentials.
  config                    View or update local headlessx configuration.
  status [options]          Show CLI and backend status.
  scrape [options] <url>    Run a direct website scrape against the HeadlessX
                            website routes.
  map [options] <url>       Discover links on a site through
                            /api/operators/website/map.
  crawl [options] <url>     Create a queue-backed crawl job.
  google [options] <query>  Run a Google AI Search scrape through HeadlessX.
  tavily                    Run Tavily search and research workflows.
  exa                       Run Exa search workflows.
  youtube                   Run YouTube extraction and save flows.
  jobs                      Inspect or control HeadlessX jobs.
  operators                 Inspect the current HeadlessX operators catalog.
  help [command]            display help for command

其中 init/start/stop/restart/logs 六个是"运行时管理"子命令，面向用 CLI 从零拉起部署的场景（在 ~/.headlessx 工作区克隆仓库并管理运行）；本文的部署已在部署篇完成，这些命令保持原样不重复执行，实际部署与启停以部署篇为准。

三、前置条件

HeadlessX 已部署并运行（curl http://localhost:38473/api/health 返回 status: online）；
有内部管理键（部署 .env 中 DASHBOARD_INTERNAL_API_KEY 的值），用于创建用户键；
调用 CLI 的机器已装 Node.js ≥ 18（node --version 实测 v24.21.0），执行：

npm install -g @headlessx-cli/core

added 9 packages in 889ms

四、认证与 Key 管理

4.1 双键模型

键	来源	能做什么	不能做什么
内部管理键	部署 .env 的 `DASHBOARD_INTERNAL_API_KEY`	控制台服务端代理、`/api/keys` 管理命令	不能抓取、不能访问 MCP 端点（显式拒绝）
用户键	`POST /api/keys` 创建（`hx_` 前缀）	全部业务面：抓取、队列、日志、MCP	不能管理其他键之外的敏感管理面

4.2 创建用户键（实测）

curl -s -X POST http://localhost:38473/api/keys \
  -H "x-api-key: hx-dash-internal-b5b8f2e2453a5ab9519c57d006e446ff" \
  -H "Content-Type: application/json" \
  -d '{"name":"ops-demo","note":"docs test key"}'

{"success":true,"data":{"apiKey":"hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96","name":"ops-demo"}}

⚠️ 用户键明文只在创建响应里出现一次，服务端只存哈希，请当场保存。后续统一用 hx_e9a2...f7c96 这把键。

键列表查询（用户键即可查自己，管理键可查全部）：

curl -s http://localhost:38473/api/keys -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96"

{"success":true,"keys":[{"id":"13a4bd0f-370c-49f8-b7ce-7e02cf199b6a","name":"ops-demo","prefix":"hx_e9a2","last_used_at":"2026-10-24T00:49:25.684Z","is_active":true,"created_at":"2026-10-24T00:45:05.987Z"}]}

4.3 CLI 登录

headlessx login --api-key hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96 --api-url http://localhost:38473

✓ Login successful.
Config stored at: /opt/data/quzuo/tmp/headlessx/clihome/.config/headlessx
API URL: http://localhost:38473

（存储路径一行随执行用户的 HOME 目录变化：本例因测试隔离把配置目录重定向到了测试用户目录，标准服务器上默认在 ~/.config/headlessx。）登录后所有 CLI 命令自动带键，无需重复传参。

4.4 MCP 端点的双键行为（实测）

用内部管理键访问 MCP 会被显式拒绝：

curl -s -X POST http://localhost:38473/mcp \
  -H "x-api-key: hx-dash-internal-b5b8f2e2453a5ab9519c57d006e446ff" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}'

{"jsonrpc":"2.0","error":{"code":-32001,"message":"DASHBOARD_INTERNAL_API_KEY cannot be used for MCP access"},"id":null}

换成用户键，正常完成 MCP 初始化握手（SSE 响应，截取）：

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"headlessx-mcp-server","version":"1.0.0"}}}

五、系统与状态工具

5.1 服务健康快照（免认证）

curl -s http://localhost:38473/api/health

实测（格式化，关键字段）：

{
  "status": "online",
  "engines": { "headfox": "available", "playwright": "available", "browser": "ready" },
  "capabilities": { "website": true, "search": false, "youtube": true },
  "captchaModels": { "classification": false, "detection": false },
  "searchProviders": { "tavily": false, "exa": false },
  "maxConcurrency": 5,
  "currentConcurrency": 0
}

巡检口诀：status 看 online，engines.browser 看 ready，capabilities 看哪些面可用（search: false 只是没配搜索键）。

5.2 CLI status（一键体检）

登录后执行 headlessx status，实测分节（截取）：

## Auth
- **Configured:** yes
- **Detail:** API key available for authenticated operator routes.

## Reachability
### Api
- **Ok:** yes
- **Detail:** 200 OK
- **Url:** http://localhost:38473/api/health

## Health
- **Status:** online
- **Service:** HeadlessX V2 Pro Backend (Headfox JS)
- **Browser:** Headfox JS (Camoufox-powered Firefox)

## Integrations
### Tavily
- **Success:** yes
- **Status:** online
- **Configured:** no

## Queue
- **Success:** yes
### Metrics
- **Queue Name:** headlessx-jobs
- **Redis Target:** redis://redis:6379
- **Available:** yes

一条命令覆盖：认证状态、API 可达性、健康快照、集成模块状态、队列可达性。

5.3 运营目录与仪表盘（curl）

运营面目录（CLI 等价命令 headlessx operators list）：

curl -s http://localhost:38473/api/operators/status -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96"

实测（格式化截取；完整返回含 12 个运营面，未配置键的显示 configuration_required，规划中的显示 coming_soon）：

{
  "success": true,
  "data": {
    "operators": [
      {
        "id": "website",
        "name": "Website",
        "tagline": "Universal web extraction",
        "description": "Extract HTML, render JavaScript, capture screenshots, crawl pages, and map links with enterprise-grade stealth technology.",
        "category": "website",
        "features": ["Extract", "Crawl", "Map"],
        "playgroundHref": "/playground/operators/website/scrape",
        "apiBasePath": "/api/operators/website",
        "order": 10,
        "available": true,
        "comingSoon": false,
        "state": "active",
        "reason": null
      },
      {
        "id": "google",
        "name": "Google Search",
        "tagline": "SERP & Intelligence",
        "category": "search",
        "features": ["Organic Results", "Featured Snippets", "PAA", "Maps"],
        "playgroundHref": "/playground/operators/google/ai-search",
        "apiBasePath": "/api/operators/google/ai-search",
        "order": 20,
        "available": true,
        "comingSoon": false,
        "state": "active",
        "reason": null
      }
    ]
  }
}

仪表盘统计与请求日志：

curl -s http://localhost:38473/api/dashboard/stats -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96"
curl -s "http://localhost:38473/api/logs?limit=3" -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96"
curl -s http://localhost:38473/api/logs/stats -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96"

实测（原样，logs 仅展示首条日志的完整结构，其余两条以 … 省略）：

// /api/dashboard/stats
{"totalJobs":3,"failedRate":"0.0%","runningBrowsers":1,"maxConcurrency":5,"browserHeadless":true,"proxyEnabled":false,"systemLoad":86}
// /api/logs
{"success":true,"pagination":{"page":1,"limit":3,"total":3},"logs":[{"id":"ae64dc0e-5a18-45c7-9060-87596fb18062","api_key_id":null,"profile_id":null,"url":"https://example.com","method":"POST","status_code":200,"duration_ms":28878,"error_message":null,"error_screenshot_path":null,"created_at":"2026-10-24T00:47:14.744Z","api_key":null}, … ]}
// /api/logs/stats
{"success":true,"stats":{"totalRequests":3,"successfulRequests":3,"failedRequests":0,"successRate":"100.0","avgLatency":"27.41"}}

日志逐条记录 URL、方法、状态码、耗时，是排障第一现场。

六、网站抓取工具

6.1 CLI scrape（最快上手）

headlessx scrape https://example.com

实测输出（提取到的正文 Markdown，节选）：

Example Domain

This domain is for use in documentation examples without needing permission. This is not a service; avoid relying on it for testing and monitoring purposes.

该域名仅用于文档示例，无需获得许可。这并非一项服务，请勿将其用于测试和监控目的。

 [Learn more](https://iana.org/help/example-domains)

常用参数（headlessx scrape --help，节选）：--format <markdown|html|text>、--screenshot、--output <path>、--json。

6.2 REST 抓取四件套（curl）

原始 HTML（scrape/html，Playwright 渲染后回传）：

curl -s -X POST http://localhost:38473/api/operators/website/scrape/html \
  -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

实测（原样，html 字段为完整渲染后 HTML，此处截断展示）：

{"url":"https://example.com","html":"<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"utf-8\">…<title>Example Domain</title>…</head><body>…<p lang=\"en\">This domain is for use in documentation examples without needing permission. This is not a service; avoid relying on it for testing and monitoring purposes.</p>…</body></html>","stats":{"duration":34166,"statusCode":200}}

渲染后 DOM（scrape/html-js，等 JS 执行完的 DOM 字符串，适合单页应用）：

curl -s -X POST http://localhost:38473/api/operators/website/scrape/html-js \
  -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

实测响应结构与 scrape/html 相同（url + html + stats，本例 stats.duration 28604 毫秒）。

Markdown 正文（scrape/content，走内置 HTML→Markdown 微服务）：

curl -s -X POST http://localhost:38473/api/operators/website/scrape/content \
  -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

实测（原样，markdown 多语种正文截断展示）：

{"url":"https://example.com","markdown":"Example Domain\n\nThis domain is for use in documentation examples without needing permission. This is not a service; avoid relying on it for testing and monitoring purposes.\n\nهذا النطاق مُخصص للاستخدام في أمثلة التوثيق دون الحاجة إلى إذن. هذه ليست خدمة، يُرجى تجنب الاعتماد عليها لأغراض الاختبار والمراقبة.\n\n该域名仅用于文档示例，无需获得许可。这并非一项服务，请勿将其用于测试和监控目的。\n\n…","title":"Example Domain","metadata":{"keywords":[]}}

整页截图（scrape/screenshot，二进制 JPEG 直出）：

curl -s -X POST http://localhost:38473/api/operators/website/scrape/screenshot \
  -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","fullPage":true}' \
  -o example.jpg
file example.jpg

example.jpg: JPEG image data, JFIF standard 1.01, resolution (DPI), precision 8, 1366x772, components 3

（88 KB 真图；1366×772 与浏览器窗口默认尺寸一致。）

站点链接测绘（scrape/map）：

curl -s -X POST http://localhost:38473/api/operators/website/map \
  -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","limit":5}'

{"success":true,"type":"map","data":{"url":"https://example.com","title":"Example Domain","summary":{"total":0,"internal":0,"external":0,"sitemap":0,"page":0,"both":0},"links":[],"generatedAt":"2026-10-24T00:47:15.925Z"}}

（请求体里带了 limit: 5；返回的 summary 按内链/外链/sitemap 等维度计数，example.com 无链接所以全为 0；对真实站点会返回链接数组。）CLI 等价命令：headlessx map https://example.com。

七、批量采集工具（队列作业）

单页抓取是同步直返；crawl 走 Redis 队列异步执行，提交后拿 job_id 轮询。

7.1 提交 crawl（curl）

curl -s -X POST http://localhost:38473/api/operators/website/crawl \
  -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://quotes.toscrape.com","limit":10}'

{"success":true,"job":{"id":"36517871-50cb-4596-928d-eb83210e280f","type":"crawl","status":"queued","target":"https://quotes.toscrape.com","progress":null,"result":null,"error":null,"attemptsMade":0,"maxAttempts":3,"cancelRequested":false,"createdAt":"2026-10-24T00:47:29.859Z","updatedAt":"2026-10-24T00:47:29.859Z","startedAt":null,"completedAt":null}}

⚠️ 参数名是 limit（页数上限 1-100）、maxDepth（0-4），不是 maxPages——实测传 maxPages 会被静默忽略并按默认 limit: 10 执行（请求体经严格校验，未知字段直接丢弃）。

7.2 查询作业（curl）

curl -s http://localhost:38473/api/jobs/36517871-50cb-4596-928d-eb83210e280f \
  -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96"

进行中（原样；注意作业对象直接返回，状态是 active）：

{"id":"36517871-50cb-4596-928d-eb83210e280f","type":"crawl","status":"active","target":"https://quotes.toscrape.com","progress":{"step":3,"total":6,"status":"active","message":"Page opened (page 3 of 10) • https://quotes.toscrape.com/author/Albert-Einstein"},"result":null,"error":null,"attemptsMade":1,"maxAttempts":3,"cancelRequested":false,"createdAt":"2026-10-24T00:47:29.859Z","updatedAt":"2026-10-24T00:47:56.874Z","startedAt":"2026-10-24T00:47:29.985Z","completedAt":null}

完成后（原样，result.data.pages 内含每页 URL/深度/标题/Markdown，此处仅保留 summary 展示结构）：

{"id":"36517871-50cb-4596-928d-eb83210e280f","type":"crawl","status":"completed","target":"https://quotes.toscrape.com","progress":{"step":6,"total":6,"status":"completed","message":"Prepared 10 crawled pages"},"result":{"url":"https://quotes.toscrape.com","data":{"pages":[ … 每页含 url、depth、title、excerpt、markdown、linkCount、statusCode … ],"summary":{"seedUrl":"https://quotes.toscrape.com","generatedAt":"2026-10-24T00:49:34.995Z","failureCount":0,"pagesCrawled":10,"requestedLimit":10,"discoveredCount":10,"maxDepthReached":1},"failures":[],"combinedMarkdown":"# Quotes to Scrape\n\nSource: https://quotes.toscrape.com\n\n…"}},"type":"crawl","success":true,"duration":125000,"error":null,"attemptsMade":1,"maxAttempts":3,"cancelRequested":false,"createdAt":"2026-10-24T00:47:29.859Z","updatedAt":"2026-10-24T00:49:34.998Z","startedAt":"2026-10-24T00:47:29.985Z","completedAt":"2026-10-24T00:49:34.995Z"}

作业列表与队列指标：

curl -s "http://localhost:38473/api/jobs?limit=5" -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96"
curl -s http://localhost:38473/api/jobs/metrics -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96"

// /api/jobs/metrics
{"success":true,"metrics":{"queueName":"headlessx-jobs","redisTarget":"redis://redis:6379","available":true,"counts":{"active":1,"waiting":0,"delayed":0,"completed":0,"failed":0,"paused":0}}}

7.3 CLI crawl

headlessx crawl https://quotes.toscrape.com --limit 3

实测输出（原样；CLI 打印作业回执后返回，进度用 7.2 的作业查询或 headlessx jobs list 跟踪）：

# Website Crawl

- **Success:** yes
## Job
- **Id:** a76764cb-c04c-4c18-a78d-1fbe5ff1c7cf
- **Type:** crawl
- **Status:** queued
- **Target:** https://quotes.toscrape.com
- **Progress:** null
- **Result:** null
- **Error:** null
- **Attempts Made:** 0
- **Max Attempts:** 3
- **Cancel Requested:** no
- **Created At:** 2026-10-24T00:55:21.255Z
- **Updated At:** 2026-10-24T00:55:21.255Z
- **Started At:** null
- **Completed At:** null

该作业 36 秒后完成，结果摘要（作业查询接口返回，截取）：pagesCrawled: 3、requestedLimit: 3、maxDepthReached: 1、failureCount: 0——--limit 3 精确生效。若想让 CLI 自己轮询到终态再一次性打印，加 --wait（帮助原文：Poll until the job reaches a terminal state，可配 --poll-interval <seconds>）；-o result.json 可把整包结果落盘。CLI 等价查询：headlessx jobs list。

八、搜索与 YouTube 工具

8.1 状态检查（先看再调）

curl -s http://localhost:38473/api/operators/tavily/status -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96"
curl -s http://localhost:38473/api/operators/exa/status -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96"
curl -s http://localhost:38473/api/operators/youtube/status -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96"
curl -s http://localhost:38473/api/operators/google/ai-search/cookies/status -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96"

实测汇总（原样）：

// tavily/status
{"success":true,"data":{"status":"online","configured":false,"service":"tavily-v1"}}
// exa/status
{"success":true,"data":{"status":"online","configured":false,"service":"exa-v1"}}
// youtube/status
{"success":true,"data":{"status":"online","configured":true,"service":"yt-dude-v1","ffmpeg_available":true,"temp_dir":"/app/tmp/yt-engine","job_ttl_hours":12}}
// google/ai-search/cookies/status
{"success":true,"data":{"status":"required","ready":false,"required":true,"running":false,"launchMode":null,"hasDisplay":false,"usingVirtualDisplay":true,"activePages":0,"profileDir":"/app/apps/api/data/browser-profile/default","usesSharedProfile":true,"startedAt":null,"message":"Build cookies once …"}}

解读：Tavily/Exa 服务在线但 configured: false（未配键，运营面目录里对应显示 configuration_required）；YouTube 引擎就绪且 ffmpeg_available: true（job_ttl_hours: 12 与配置参数一致）；Google AI 搜索需要先在控制台保存 Google 登录态（status: required，登录态存指纹浏览器用户目录并用 CREDENTIAL_ENCRYPTION_KEY 加密）。

8.2 YouTube 提取实测与超时

curl -s -X POST http://localhost:38473/api/operators/youtube/info \
  -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=jNQXAC9IVRw"}' \
  --max-time 60

本例实测 45 秒后按配置的 YT_ENGINE_TIMEOUT_MS 超时返回：

{"success":false,"error":{"code":"YOUTUBE_ENGINE_FAILED","message":"YouTube engine request timed out"}}

引擎服务本身 online（见 8.1），但服务器出口网络不可达 YouTube。CLI 等价命令 headlessx youtube info <url>；搜索面 CLI：headlessx tavily search <query>、headlessx exa <子命令>、headlessx google <query>，均要求对应键/登录态先配置好。

九、代理与配置工具

curl -s http://localhost:38473/api/proxies -H "x-api-key: hx_e9a271e7c086cb0f3ff3c2f9c49c0bbefc31fd02441f7c96"

{"proxies":[]}

代理池为空（未添加代理，运行态 proxyEnabled: false 与之呼应）。运行态配置的查看与修改（GET/PATCH /api/config，13 项浏览器行为参数）实测记录见本专栏《HeadlessX v2.1.2 配置参数详解》第六节；CLI 本地配置用 headlessx config（查看/更新的是 CLI 自身的连接配置，与服务端配置是两回事）。

十、注意事项

用户键只在创建响应出现一次，服务端只存 SHA-256 哈希；丢了只能吊销重建；
crawl 参数是 limit/maxDepth，未知字段（如 maxPages）会被静默忽略，提交前用响应里的 requestedLimit 复核；
MCP 接入必须用用户键，内部管理键被显式拒绝（实测见 4.4）；
截图/JPEG 等二进制端点要加 -o 落盘，直接看终端会输出乱码；
搜索/YouTube 面先查 status 再调用：configured: false/offline/required 时调用必失败，别浪费重试；
CLI 的 init/start/stop 子命令面向"CLI 自己拉起部署"的场景，与本系列部署篇的部署方式是两条路径，同一台服务器选其一，别混用管理入口。

十一、常见问题

Q1：curl 返回 401/403？

检查 x-api-key 头：值前有没有多余空格、是不是把内部管理键当业务键用了（管理键只能调 /api/keys 等管理面）。用 headlessx status 的 Auth 节确认 CLI 键已配置。

Q2：crawl 一直 queued 不动？

Worker 进程没在跑（crawl 全靠它消费队列）。到部署篇第十章用日志命令看 worker 是否存活；恢复后积压作业会自动继续。

Q3：headlessx 命令不存在？

npm install -g @headlessx-cli/core 的全局 bin 目录不在 PATH（npm config get prefix 查看，确认 <prefix>/bin 在 PATH 中）。CLI 要求 Node.js ≥ 18。

Q4：抓取某些站点很慢或超时？

反爬强度高的站点建议：运行态开 proxyEnabled 并添加代理（/api/proxies）、stealthMode 保持 advanced、或对单页用 scrape/html-js 并配 waitForSelector。同步抓取默认超时 60 秒（运行态 browserTimeout）。

Q5：YouTube 全部失败但 youtube/status 是 online？

引擎进程活着不代表它能出网。本例出口不可达 YouTube，/api/operators/youtube/info 按超时返回 YOUTUBE_ENGINE_FAILED。这类问题与 HeadlessX 配置无关，先解决服务器出网或给引擎单独配可达出口。

十二、参考链接

部署方法：《HeadlessX v2.1.2 Docker Compose 部署指南》
配置参数：《HeadlessX v2.1.2 配置参数详解》
组件选型：《HeadlessX v2.1.2 介绍与选型指南》
CLI 包主页：https://www.npmjs.com/package/@headlessx-cli/core
官方 API 文档：https://github.com/saifyxpro/HeadlessX/blob/main/docs/api-endpoints.md