HTTP 与 WebSocket 服务

在 设置 → 连接 → HTTP / WebSocket服务 中，可以让脚本、快捷指令或其他设备调用这台电脑上的 Quicker。HTTP API 支持运行动作、复制、粘贴、模拟输入及打开网址或文件；WebSocket 供已有客户端保持连接使用。

这里配置的是 Quicker 内置 HTTP API。组合动作里的「HTTP服务器」模块用于临时提供文件夹网页和文件传输，不能代替本页的 API 开关与访问令牌。

本文适用于提供该设置页和 HTTP API 的 V2 版本。如果界面仍显示旧的手机 APP 设置，请先更新到包含此功能的版本。旧的“连接手机APP”菜单和二维码窗口已移除。

当前设置入口位于 连接 分组，与「软件连接」并列；原有端口、令牌、验证码和访问范围配置会保留。

先完成一次调用​

要允许局域网设备通过 HTTP 调用 Quicker，请在 设置 → 连接 → HTTP / WebSocket服务 完成下面的开关、地址和令牌设置，再从另一台设备测试。仅复制调用示例不能代替启用服务。

1. 打开设置页，在“基础设置”确认服务端口及是否启用安全连接。
2. 仅在这台电脑调用时，关闭“允许其他设备访问”；从其他设备调用时保持开启，并在“连接地址所用 IP”中选择可访问的局域网 IP。
3. 在“HTTP API”下点击“生成令牌”，然后启用 HTTP API。
4. 点击 应用设置，确认“运行状态”显示服务正在监听、HTTP 已开启。
5. 点击 复制调用命令 ▾，选择实际使用的终端，将命令粘贴到该终端运行。

默认示例会把 Hello from HTTP API 写入 运行 Quicker 的电脑 的剪贴板。返回 ok: true、status: completed 表示复制已完成。

复制的地址和命令使用当前编辑值。修改端口、安全连接、IP 或令牌后，应先应用设置，再调用；复制本身不会保存或启动服务。命令含有访问令牌，分享示例时请替换令牌。

基础设置​

修改端口、安全连接或监听范围会重启共用服务，并影响现有连接。局域网调用还需要设备之间网络可达，且防火墙允许所选端口。

HTTPS 域名与地址​

安全连接使用 Quicker 提供的域名和证书。例如电脑 IP 为 192.168.5.50、端口为 668 时：

关闭安全连接时，使用 http://IP:端口/api/exec 或 ws://IP:端口/ws。优先复制设置页显示的地址；使用 HTTPS 时不要自行将域名换成数字 IP，否则可能无法通过证书校验。

域名需要能够正常解析，更新证书需要联网。运行状态会显示证书有效期。证书不可用时不会自动降级为明文连接。局域网访问请使用可信网络；HTTP 访问令牌和 WebSocket 验证码仍需分别配置。

HTTP 调用命令​

下面使用本机默认 HTTPS 地址。将 REPLACE_WITH_YOUR_TOKEN 替换为设置页复制的令牌；从另一台设备调用时，将地址替换为服务电脑的局域网调用地址。

PowerShell（Windows）​

打开 PowerShell，粘贴整段执行。请求体按 UTF-8 编码，也适用于中文文本。

$body = '{"operation":"copy","data":"Hello from HTTP API","wait":true}'
Invoke-RestMethod -Method Post -Uri 'https://127-0-0-1.lan.quicker.cc:668/api/exec' -Headers @{ Authorization = 'Bearer REPLACE_WITH_YOUR_TOKEN' } -ContentType 'application/json; charset=utf-8' -Body ([System.Text.Encoding]::UTF8.GetBytes($body))

curl（Windows CMD）​

在 Windows 命令提示符中执行下面这一行。CMD 使用双引号，JSON 内部的双引号需要保留下面的转义写法。

curl.exe --request POST "https://127-0-0-1.lan.quicker.cc:668/api/exec" --header "Authorization: Bearer REPLACE_WITH_YOUR_TOKEN" --header "Content-Type: application/json" --data-raw "{\"operation\":\"copy\",\"data\":\"Hello from HTTP API\",\"wait\":true}"

curl（Bash / macOS / Linux）​

这些设备通常需要调用 Windows 电脑的局域网地址，下面的 IP 仅为示例。

curl --request POST 'https://192-168-5-50.lan.quicker.cc:668/api/exec' --header 'Authorization: Bearer REPLACE_WITH_YOUR_TOKEN' --header 'Content-Type: application/json' --data-raw '{"operation":"copy","data":"Hello from HTTP API","wait":true}'

“原始 HTTP 请求”适合查看方法、请求头和正文，或在 HTTP 调试工具中分别填写这些内容，不能直接当作终端命令执行。请按实际工具选择命令格式；不要将 Markdown 链接的 [地址](地址) 整体粘贴进 URL。

HTTP 请求参数​

向 POST /api/exec 发送 JSON，并携带 Authorization: Bearer 令牌 和 Content-Type: application/json。请求体直接包含以下字段，无需 id、method 或 params 包装。

字段名和类型应按表填写，例如使用布尔值 true，而非字符串 "true"。不接受未知字段、重复字段或字符串字段的 null 值；请求正文最多 32000 字节。

输入和粘贴操作会影响服务电脑上的目标窗口，测试前请确认焦点。文件路径也以服务电脑为准。

例如运行动作并等待最多 10 秒：

{
  "operation": "action",
  "action": "替换为动作ID",
  "data": "传给动作的输入参数",
  "wait": true,
  "maxWaitMs": 10000
}

返回结果与等待​

执行完成时返回：

{"ok":true,"result":{"status":"completed"}}

动作有返回值时，result.data 中还会包含返回字符串。wait: false 则只确认请求已受理：

{"ok":true,"result":{"status":"accepted"}}

accepted 不代表执行成功。 需要结果时使用 wait: true。动作失败、取消或无法启动，会返回 ok: false，错误原因位于 error.code 和 error.message。

等待超时示例：

{"ok":false,"error":{"code":"WAIT_TIMEOUT","message":"等待超时，操作可能仍在运行，请勿自动重试。"}}

maxWaitMs 只限制等待时间，超时或客户端断开不会撤销已开始的操作。不要因等待超时自动重试，否则可能重复运行动作或输入内容。当前没有事件订阅、后台结果查询或按请求 ID 取消的接口。

执行失败和等待超时也可能返回 HTTP 200，调用方必须检查 JSON 中的 ok，不能只看 HTTP 状态码。

WebSocket 与已有客户端​

启用 WebSocket 服务后，在客户端使用设置页复制的 /ws 地址及对应验证码。HTTP 访问令牌和 WebSocket 验证码是两种不同凭据，不能相互替代；HTTP 的 JSON 执行请求也不能直接当作 WebSocket 消息发送。

已有 WebSocket 客户端继续使用原有消息协议，但要核对共享端口、安全连接和访问范围。修改验证码或关闭 WebSocket 后，应让客户端断开重连；如果需要立即清退全部旧连接，请退出并重新启动 Quicker。

2.3.23 · 文件接收目录​

在同一设置页的 WebSocket 分组填写 文件接收目录，使用绝对路径；留空仍保存到系统“文档”目录下的 Quicker\_recv。目录只保存在本机，不随账号同步，也不移动已经接收的文件；保存后从下一个接收文件开始使用，不支持环境变量写法。

连续接收的文件会合并通知。组合动作的 WebSocket 步骤向客户端发送二进制文件时显示发送进度；这与本页的接收目录设置是两项独立功能。

WebSocket 服务还可提供“文档”目录下 Quicker/_websocket 中的静态文件。仅开启 HTTP API 时不会开放该静态文件目录。

2.3.31 · 文件接收后处理与批量复制​

:::info 版本与客户端支持 以下协议扩展从 2.3.31 起可用。服务电脑需运行 2.3.31 或更高版本；不发送新字段时，仍然只保存文件并显示接收通知，不会自动复制。这些能力需要发送端配合，未新增电脑端全局开关，也不改变原有通知的点击行为。 :::

接收单个文件并复制或定位​

客户端先发送文件头 JSON，再发送文件内容的二进制消息。可用 afterReceive 指定保存成功后的操作：

{
  "messageType": 2,
  "serial": 1000,
  "operation": "sendfile",
  "data": "照片.jpg",
  "afterReceive": "copyFile;selectInExplorer"
}

多个操作用分号分隔，按书写顺序执行；不区分大小写，忽略空项和首尾空白，重复操作只执行第一次。未知操作会在文件头阶段被拒绝。多个剪贴板操作会依次覆盖，最终保留最后一个成功写入的内容。

省略 afterReceive 或传入空字符串，保持原有行为。操作只在文件保存成功后执行，不自动发送粘贴按键；原有 pasteimage 仍表示复制图片后立即向当前窗口粘贴，不接受非空 afterReceive 操作列表。

文件头会先收到 message: "waiting for file..." 的接纳响应。有操作时，响应中的 extData.afterReceive 会确认识别到的操作列表；旧版可能忽略新字段，不能仅凭传输成功认定后处理已执行。

二进制保存完成后，再收到最终响应。replyTo 对应请求的 serial，data 是服务电脑上保存后的完整路径：

{
  "messageType": 4,
  "replyTo": 1000,
  "isSuccess": true,
  "message": "ok",
  "data": "D:\\Recv\\20261104_123456789_照片.jpg",
  "extData": {
    "afterReceiveSuccess": true,
    "afterReceiveResults": [
      {"operation": "copyFile", "isSuccess": true, "message": "ok"},
      {"operation": "selectInExplorer", "isSuccess": true, "message": "ok"}
    ]
  }
}

最终响应的 isSuccess 表示文件是否保存成功。后处理失败时，文件仍保留，extData.afterReceiveSuccess 为 false，失败项在 afterReceiveResults 中说明原因，后续操作继续执行。不要因后处理失败重复传输文件。未指定操作时不附加这组后处理结果。

一次复制多个接收文件​

每个文件的 afterReceive 独立执行；逐个使用 copyFile 不会累计文件列表。客户端可以收集一批文件最终成功响应中的 data，让用户选择后，再发送一次 copyFiles：

{
  "messageType": 2,
  "serial": 2000,
  "operation": "copyFiles",
  "data": ["D:\\Recv\\a.jpg", "D:\\Recv\\b.pdf"]
}

data 必须为非空路径数组，每项为服务电脑上存在、可访问的文件绝对路径，不接受目录。全部校验通过后，一次写入文件剪贴板，重复路径忽略。成功返回 isSuccess: true，失败返回 isSuccess: false 和原因。原有 copy 仍复制文本。

客户端自己决定一批文件何时发送完毕；接收通知的自动合并不代表一个完整批次。这些命令只用于 WebSocket，不能直接发送到 HTTP /api/exec。

将文件交给动作处理​

压缩、移动、上传等特殊需求，可复用已有 action 命令。data 是传给动作的字符串，例如将路径列表编码为 JSON 字符串，由动作解析：

{
  "messageType": 2,
  "serial": 2001,
  "operation": "action",
  "action": "替换为动作ID",
  "data": "[\"D:\\\\Recv\\\\a.jpg\",\"D:\\\\Recv\\\\b.pdf\"]",
  "wait": true
}

wait: true 沿用已有的等待动作执行结果语义。若动作会修改文件或产生外部操作，请根据动作实际返回结果判断，避免重复执行。

设置保存在哪里​

这些设置按当前账号保存在 本机账号数据目录的 data/local-settings.json 中，属于本地账号设置。端口、安全连接、访问范围、两个服务的开关与凭据均不随账号同步到其他电脑；换电脑后需要重新配置。HTTP 令牌在本机加密保存，不能靠复制文件让另一台电脑直接使用同一密文。

首次建立本地设置时会沿用已有的 WebSocket 配置。设置文件损坏、无法读取或版本不受支持时，会保留原文件并停止服务，页面提示错误；请先处理文件问题再重启，不要将此状态理解为成功恢复默认设置。

重置 HTTP 令牌后需要应用设置，旧令牌随后无法用于新请求；已经开始的操作不会因此撤销。更多账号目录与同步说明见 账号、登录与数据同步。

常见问题​

连接失败或 HTTPS 握手失败​

先确认运行状态显示服务正在监听、地址与应用后的设置一致。局域网调用检查 IP、网络和防火墙；HTTPS 还需检查域名解析、系统时间和证书状态。

如果使用代理，可以在 curl 命令中加入 --noproxy "*"，让这次请求直接连接。例如：

curl.exe --noproxy "*" --request POST "https://127-0-0-1.lan.quicker.cc:668/api/exec" --header "Authorization: Bearer REPLACE_WITH_YOUR_TOKEN" --header "Content-Type: application/json" --data-raw "{\"operation\":\"copy\",\"data\":\"Hello from HTTP API\",\"wait\":true}"

代理可能把解析到局域网的目标交给远端代理连接，导致无法到达本机服务。若绕过代理后恢复正常，可在代理软件中为 lan.quicker.cc 及其子域名配置直连；同时确认所选 IP 确实可达。schannel 握手错误本身不能单独证明是代理问题，不应以关闭证书校验代替排查。

返回端口格式错误或 Bad hostname​

确认 URL 是纯地址，没有 [地址](地址) 形式的 Markdown 包装；在 CMD 中使用上面的 CMD 示例，不要使用 Bash 的单引号命令。

HTTP 错误状态​

此接口未开放跨域访问，不能假设任意网页中的 JavaScript 都能直接调用。优先使用脚本、快捷指令或 HTTP 客户端。

与其他网络功能有什么区别​

• 本页服务让外部调用 Quicker，不需要云端推送服务转发。
• 软件连接通过 Bridge 让 Quicker 调用第三方软件，使用独立的连接服务。
• 组合动作中的 HTTP 服务和 WebSocket模块用于编写动作内的网络逻辑，独立于本页内置服务的开关和接口。