从第一个窗口，到
一整支浏览器矩阵

下面这条路径覆盖了日常 80% 的使用场景：装客户端 → 建环境 → 配代理 → 启动 → 导入登录态 → 让 AI 接管。完整走一遍大约 5–10 分钟，窗口启动时间取决于代理与网络。

1 2 3 4

图 1 · 控制台首页。截图使用演示账号与文档专用 IP，不对应任何真实用户。

第一次使用的检查清单

• 客户端版本为 2.1.16 或更新（设置 → 关于）。
• 账号已登录，套餐配额够用（免费版 20 个环境、每天 20 次执行、3 次 AI）。
• 至少有一个代理检测成功，能看到出口 IP 与延迟。
• 环境能从「启动中」稳定进入「运行中」。
• 关闭窗口后能看到「云端已保存」，换设备登录态才不会丢。

MatrixFlow 是桌面客户端：指纹内核、窗口和本地 API 都运行在你的电脑上，云端只负责账号、配置与快照同步。请始终从 官网下载页获取安装包。

Windows（Windows 10 64 位及以上）

• 安装路径建议使用不含空格和中文的英文目录，例如 D:\MatrixFlow，这样 MCP 与 Skill 脚本调用更不容易出错。
• 若 SmartScreen 提示「Windows 已保护你的电脑」，确认安装包来自官网后，点「更多信息 → 仍要运行」。
• 不要同时运行多个安装版实例；重复安装前先退出正在运行的客户端。

macOS（macOS 12 及以上）

• M 系列芯片下载 arm64，Intel 芯片下载 x64。下载后解压，双击「一键安装.command」，按提示完成安装，App 会出现在「应用程序」中。
• 如果系统提示「来自身份不明的开发者」，到「系统设置 → 隐私与安全性」，在安全提示下方点「仍要打开」，再确认一次。
• 首次启动后同样允许它访问网络；如果你使用公司网络或代理软件，请把 127.0.0.1 加入直连/绕过列表。

系统要求与数据位置

更新与版本

客户端会检测新版本并提示更新；也可以重新下载安装包覆盖安装。覆盖安装不会丢窗口配置，登录态随窗口快照保存在云端。当前文档对应 2.1.16；如果你看到的界面与截图略有差异，以客户端内实际文案为准，并优先升级到最新版。

升级后建议做一次自检：打开「设置 → 关于」确认版本，启动一个环境，关闭并等待「云端已保存」，再打开确认位置、代理和登录态都正常。

安装失败排查

账号用于同步环境配置、代理、工作流与窗口快照。Windows 和 macOS 可以同时登录同一账号；网页版用于查看与管理云端配置，真正启动本地指纹窗口仍需桌面客户端。

注册与登录

套餐与配额

周期与价格

订阅支持 1 / 3 / 6 / 12 / 24 个月。周期越长单价越低，12 个月是大多数人的推荐档，24 个月单价最低。下表为当前套餐页价格，结算时以页面显示为准。

图 2 · 订阅页：选择套餐与计费周期，右侧可查看当前用量。页面为演示数据。

升级、续费与生效

• 在「订阅 / Billing」页选择套餐和周期，完成支付后刷新页面即可生效，不需要退出账号再登录。
• 管理员在后台调整套餐后，成员端同样只需刷新或重新进入页面获取最新权益。
• 配额按自然日重置；当天用完后相关操作会被拒绝，升级套餐或等次日恢复。具体重置时间以订阅页说明为准。
• 团队协作与共享工作流属于 Business 及以上权益，席位数与共享范围以购买页为准。

账号安全

• 不要多人共用同一个账号密码；团队请按订阅提供的席位管理。
• 在公共电脑使用后请退出登录，并清理本地数据目录中的 Token 文件。
• 客服不会向你索要密码或邮箱验证码。任何索要验证码的消息都应视为诈骗。
• 分享截图前，遮住邮箱、环境名称、代理地址与 Cookie 内容。

一个「环境」就是一个完全独立的浏览器配置：独立的 Cookie、缓存、历史、书签、代理与指纹。你可以把它理解成一台只属于某个账号的浏览器；多个环境之间互不影响，才能安全地做多账号矩阵。

1 2 3 4 5

图 3 · 环境列表。演示账号为 ops@example.com，代理 IP 为文档专用地址。

新建环境

点右上角「+ 新建环境」，填写以下信息：

环境操作

状态与等待时间

如果列表显示「已停止」但窗口还看得见，通常是状态同步延迟：切换一次页面或等几秒刷新即可。窗口实际是否运行，以桌面上的窗口和「运行中」列表为准。

窗口位置与尺寸记忆

窗口拖到哪里、拉成多大，关闭后都会被记住；下次启动时首帧就落在原来的位置和尺寸，不会先居中再跳回去。多显示器用户如果把窗口拖到副屏后拔掉副屏，窗口可能出现在可视区域之外，重新接上显示器或调整显示布局即可。

批量操作与分组

• 勾选多行后，顶部出现批量操作栏：批量启动、批量关闭、批量删除、批量改分组。
• 批量启动建议一次 2–4 个，等这一批进入「运行中」再启动下一批；同时拉起太多窗口会造成 CPU 与内存尖峰，反而更慢。
• 批量关闭不会丢数据，但请等所有窗口都显示「已停止」再关机或切换设备。
• 分组用于把窗口按团队、地区、平台归类；删除分组不会删除窗口，组内窗口会变成「未分组」。
• 批量删除不可恢复，执行前先确认没有选中正在运行或仍需保留的环境。

资源规划（经验值）

网站不只读取 Cookie，还会读取你的系统、浏览器、时区、语言、屏幕、显卡与字体。MatrixFlow 为每个环境生成一套独立的指纹，并保证页面能读到的各个字段互相对得上，不会出现「UA 写 macOS、navigator 却是 Windows」这种穿帮。

自动生成

新建环境时默认自动生成指纹，覆盖以下字段：

手动调整

编辑环境 →「高级指纹」，可以修改操作系统、语言、时区、屏幕尺寸、User-Agent、WebRTC / Canvas / WebGL 模式，也可以点「随机化」重新生成一套。调整时请遵守三条原则：

1. 保持内部一致。不要只改 UA 不改系统，也不要给 macOS UA 配 Windows 的 platform。优先整套切换，而不是逐项手改。
2. 与代理地区匹配。美国代理配美国时区、英文或中文都可，但不要让时区落在与出口 IP 明显冲突的地区。
3. 登录后不要频繁大改。已有登录态的账号突然更换系统、分辨率、时区，容易触发二次验证。大改建议新建环境并重新导入 Cookie。

如何验证

• 在环境内打开任意指纹检测页面，确认系统、UA、时区、语言、屏幕、WebGL 渲染器彼此一致。
• 同时确认出口 IP 的国家/地区与时区不冲突；代理章节有检测方法。
• 如果检测页面显示的语言与你设置的不一致，检查是否被网站自身的语言偏好覆盖。

代理决定窗口从哪个 IP 访问网站。MatrixFlow 支持 HTTP 与 SOCKS5 代理（可带账号密码），保存后自动检测出口 IP、国家、城市和延迟，并把检测结果直接显示在列表里。

1 2 3 4

图 4 · 代理管理。图中 IP 均为 RFC 5737 文档专用地址，不对应真实代理。

添加代理

列表里显示什么

• 出口 IP：网站实际看到的 IP，不是代理服务器的入口地址。
• 国家 / 城市：国内 IP 显示「国家 + 城市」（如「中国 山东」），海外 IP 通常显示国家（如「美国」）。
• 延迟：从本机到代理出口的握手耗时，受物理距离影响，不是软件能消除的。
• 检测结果与绑定信息来自同一次检测，避免出现「列表显示香港、点进去显示澳大利亚」的不一致。

选择与使用建议

常见问题

Cookie 就是网站的登录凭证。把已登录浏览器里的 Cookie 导入新环境，可以跳过重复登录，也能在换设备时快速恢复会话。MatrixFlow 支持多种常见导出格式，并会把导入结果如实告诉你：共多少条、成功多少条。

三个导入入口

支持的格式

[
  {
    "name": "sessionid",
    "value": "REPLACE_WITH_YOUR_COOKIE",
    "domain": ".example.com",
    "path": "/",
    "httpOnly": true,
    "secure": true,
    "sameSite": "Lax",
    "expirationDate": 1790000000
  }
]

# Netscape HTTP Cookie File
.example.com	TRUE	/	TRUE	1790000000	sessionid	REPLACE_WITH_YOUR_COOKIE

导入时发生什么

• 不会自动开窗：导入只写入环境存储，速度快，也不会触发网站风控。
• 逐条合并，不覆盖已有 Cookie：同名 Cookie 以现有为准，避免误把正在使用的会话冲掉。需要覆盖时，先重置环境或手动清理旧 Cookie。
• 返回真实计数：例如「共 10 条 / 成功 10 条」。如果成功数少于总数，检查域名、格式和过期时间。
• 可选验证登录：勾选后客户端会打开窗口检查登录状态；这一步会启动窗口，耗时与正常启动相同。

跨设备登录态

关闭窗口时，客户端会把本次会话的标签页与 Cookie 上传为快照。换到另一台设备登录同一账号，打开同一环境就能恢复登录态。关键动作是等「云端已保存」出现后再切换设备；如果关窗后立刻关机或断网，快照可能没传完。

1. 关闭窗口，等待状态变为「已停止」且出现「云端已保存」。
2. 在新设备登录同一账号，打开同一环境。
3. 确认标签页、登录状态与窗口位置都恢复；如个别站点掉登录，重新导入一次最新 Cookie。

导入成功却没登录？

「工作流」用可视化节点编排浏览器步骤：打开网页、点击、输入、滚动、取文本、截图、条件、循环、HTTP 请求、JS 脚本等；「RPA 任务」把工作流变成可定时、可绑定窗口自动运行的任务。工作流适合固定流程，AI 助手适合需要理解和判断的任务，两者可以配合。

1 2 3 4 5

图 5 · 工作流列表。演示数据，不对应真实账号。

创建工作流的三条路径

常用节点

发布前先预检

「质量预检」会检查未连接的节点、缺少必填参数的步骤、明显的流程断点。预检通过不代表一定能跑通，还要在测试环境完整执行一次：

• 启动页能在绑定环境中正常打开，登录态有效。
• 每个点击/输入节点都有唯一、稳定的选择器，并配有等待。
• 新标签页、弹窗、iframe 有对应的切换或等待节点。
• 失败分支会截图并记录原因，不会静默跳过。
• 重复执行不会重复提交（例如发布前先检查是否已发布）。

运行与观察

• 在绑定窗口打开设计器后运行，执行中的标签页会自动切到前台，你能看见每一步正在操作什么。
• 工作流或 AI 打开的新标签页会自动接管为当前活动页，后续步骤继续在新页执行。
• 同一窗口同一时间只跑一个任务；不同窗口可以并行，建议同时 2–4 个。
• RPA 任务可以立即执行，也可以按计划定时运行；执行结果与失败原因在任务列表查看。
• 修改后使用「保存 / 强制保存」写入云端，避免只存在本地草稿。

调试对照表

很多业务依赖 Chrome 扩展：翻译、选品、采集、客服工具等。扩展中心支持在线安装与离线安装，并可以按窗口分配，避免每个环境都手动装一遍。

两种安装方式

分配到窗口

1. 安装完成后，在扩展列表点「分配到窗口」。
2. 选择目标环境，或直接「全部分配」。
3. 下次启动这些环境时，扩展会自动加载，无需重复安装。
4. 停用、卸载同样在扩展中心完成；卸载后重新启动窗口生效。

兼容性与安全

• 优先选择 Manifest V3 扩展；过旧的 MV2 扩展可能无法加载。
• 部分扩展会读取页面内容、Cookie 或网络请求，可能与指纹伪装或站点风控冲突。新扩展先在单独测试环境验证。
• 只安装你信任的扩展。一个恶意扩展可以在你所有已登录的站点上操作，危害不低于泄露密码。
• 扩展安装失败时，先确认网络能访问商店，或改用离线包；仍失败时查看客户端错误提示。

AI 助手不是只会聊天的侧边栏，而是能直接操作浏览器窗口的执行者：它会先读取页面真实状态，再计划、执行，完成后强制核验。核验不到就标「未确认」，不会假装成功。你可以让它开窗、点击、输入、滚动、读文本、截图、导入 Cookie、跑工作流，也可以把一整批窗口交给它巡检。

界面导览

1 2 3 4 5

图 6 · AI 助手真实任务截图：创建一个名为「窗口巡检」的定时任务。已脱敏。

模型与推理强度

模型菜单由服务端下发的模型库驱动，默认为 DeepSeek 系列的多模态 Flash 模型，能直接看截图；需要更强推理时可切换到 Pro 模型。模型库会更新，如果列表里没有你预期的模型，点「同步」重新拉取，或升级到最新客户端。

权限级别

权限决定 AI 在执行敏感动作前是否停下来问你。它在输入框上方切换，高风险任务建议逐次确认。

如何写好指令

把指令想成给一位新同事派活：在哪个窗口做、做什么、有什么限制、怎么算完成。四要素齐全，成功率最高。

[窗口] + [目标] + [约束] + [验收标准]

在 3 号窗口（小红书）：
发布一篇笔记，标题「...」，正文「...」，封面用我上传的图。
发布前把预览截图给我确认；不要修改账号资料。
发布后复制笔记链接，并核对标题与正文是否一致。

• 一次一个目标。长任务拆成几步，每步完成后再发下一条，排错更容易。
• 明确「不要做什么」。例如「不要发布」「不要修改头像」「不要关闭其他窗口」。
• 给出验收标准。链接、标题文本、截图、条数、表格，都是可核验的结果。
• 数据放在消息里。标题、正文、Cookie、列表直接粘贴，不要让 AI 猜。
• 批量任务说明失败策略。例如「失败继续下一个，最后汇总失败列表」。

@ 技能菜单

在输入框输入 @ 会打开技能菜单，这是 Codex 风格的技能/脚本选择器，分为四组：

使用 @ 技能的好处是：AI 不必每次从零规划，而是按技能里写好的步骤、选择器和校验规则执行，结果更稳定、更可复现。技能里的说明越清楚，执行越不容易跑偏。

图片与截图

点输入框左侧的回形针上传图片。多模态模型可以直接读取截图中的界面结构、文字和按钮位置，适合以下场景：

• 指位置：「按我上传的截图，点击右上角「发布」按钮，进入编辑页后停下。」
• 对样式：「把这篇文章的排版做成截图里的样子，标题字号和间距保持一致。」
• 读数据：「把截图表格里的 10 行数据转成 CSV。」
• 做比对：「对比发布前后的两张截图，告诉我哪些字段变了。」

截图前建议：截完整窗口而不是只截一个按钮；用箭头或方框标出目标；一次只问一件事；把邮箱、Cookie、代理密码、订单号等敏感信息打码。图片会随请求发送给所配置的模型服务，请勿上传你不希望离开本机的数据。

执行看板

看板把每个 AI 任务展开成一张卡片，记录状态、计划、每一步的工具调用与结果、重试次数、失败原因和最终核验。它解决的是「AI 说做完了，到底做没做」的问题。

看板实时刷新，不需要手动刷新页面。任务结束后可以清理已完成卡片；正在运行的任务可以从卡片或对话里取消。

技能安装

Skill（技能）是一组写给 AI 的操作说明与脚本，通常包含 SKILL.md 和若干可执行脚本。安装后，AI 会按技能里的流程与校验规则工作，而不是每次自由发挥。

1 2 3

图 7 · 技能市场。发布前请确认技能中不含密钥、Cookie 或客户数据。

三种安装方式

多窗口批量操作

AI 可以按编号或名称依次操作多个窗口。批量任务的关键是控制并发、明确顺序、定义失败处理。

• 并发 2–4 个是大多数机器的舒适区；6 个以上容易把内存和 CPU 压满，反而拖慢每个任务。
• 同一窗口只跑一个任务。并行操作同一个窗口会互相抢焦点，结果不可预测。
• 分批启动。先开第一批，进入「运行中」后再开下一批，避免瞬间拉起所有内核。
• 说清失败策略。「失败继续下一个并记录」还是「失败立即停止」，结果完全不同。
• 要求汇总。让 AI 最后输出一张表：窗口号、结果、失败原因、链接/截图。

依次检查 1–5 号窗口：
1. 启动窗口，等待页面加载完成；
2. 读取当前页面标题、登录账号名、代理出口国家；
3. 截图保存；
4. 关闭窗口。
每个窗口完成后再处理下一个；失败不要重试超过 1 次。
最后输出表格：窗口号 / 是否登录 / 标题 / 出口国家 / 结果。

指令库

下面这些指令可以直接改用。把窗口号、网址和内容替换成你的实际值；首次执行建议用「请求批准」。

工具只是放大器，稳定的矩阵来自纪律：环境隔离、代理稳定、登录态可控、操作有核验。下面四套流程覆盖从新号上线到换机交接。

Playbook A · 新环境 30 分钟上线

Playbook B · 每日矩阵巡检

把重复检查交给 AI，人只看异常。建议每天固定时间执行一次，配额有限时优先检查高价值账号。

依次检查 1–10 号窗口，每个窗口：
- 启动并等待加载完成（最多 60 秒）；
- 记录页面标题、登录账号、代理出口国家；
- 截图；
- 关闭并等待云端保存。
失败继续下一个，每个窗口最多重试 1 次。
最后输出：正常列表、异常列表（窗口号 + 原因）、建议优先处理的 3 项。

• 巡检前确认配额足够：每次启动、关闭与 AI 调用都可能计入执行/AI 次数。
• 把「异常」定义清楚：打不开、未登录、出口国家不符、页面出现验证码，都算异常。
• 巡检结束抽查 1–2 张截图，确认 AI 没有把错误页当成正常页。

Playbook C · 内容发布流水线

1. 素材先齐：标题、正文、封面、话题、@ 对象、发布时间，全部放在一条消息里。
2. 先在测试环境跑一遍：用「请求批准」权限，确认每一步选择器正确，预览截图符合预期。
3. 一次只发一个账号：发布成功后核对链接、标题、封面；确认无误再复制到下一个账号。
4. 控制频率：同一账号不要短时间连续发布；不同账号之间留出间隔。
5. 留证据：保存发布成功截图、链接与时间，便于复盘和申诉。
6. 失败不硬重试：先判断是否已经发布成功，避免重复内容；必要时人工检查。

Playbook D · 换机与团队交接

1. 旧设备关闭所有窗口，确认全部「已停止」且「云端已保存」。
2. 为关键环境创建快照，命名包含日期，例如「2026-10-19 交接」。
3. 新设备登录同一账号，等待配置同步完成。
4. 打开环境，检查标签页、登录态、代理与窗口位置；逐个验证，不要一次全开。
5. 确认无误后，再在旧设备退出登录。不要在同步完成前清理旧设备数据。

团队交接时，优先使用分组、备注与共享工作流，而不是共用账号密码。谁负责哪些环境、哪些工作流可以共享，应在备注或团队规范里写清楚。

批量操作的节奏

客户端启动后会在本机监听 http://127.0.0.1:19527。它只绑定回环地址，外网无法访问；请求需要携带本地 Token。适合把 MatrixFlow 接进你自己的后台、采集脚本或自动化平台。

获取 Token

• 客户端「AI 助手 → MCP 接入」可以一键查看并复制地址与 Token。
• 也可以读取本地文件：
  Windows %APPDATA%\@matrixflow\desktop\local-api-token.txt
  macOS ~/Library/Application Support/@matrixflow/desktop/local-api-token.txt

第一次请求

TOKEN=$(cat "$HOME/Library/Application Support/@matrixflow/desktop/local-api-token.txt")
curl -s -H "X-MatrixFlow-Token: $TOKEN" \
  http://127.0.0.1:19527/api/v1/matrixflow/local-api/info

$token = (Get-Content "$env:APPDATA\@matrixflow\desktop\local-api-token.txt" -Raw).Trim()
Invoke-RestMethod -Headers @{ "X-MatrixFlow-Token" = $token } `
  http://127.0.0.1:19527/api/v1/matrixflow/local-api/info

成功时返回统一信封：{"success": true, "data": { ... }}；失败时 success 为 false，并在 error 中给出 code 与 message。

Node.js 最小客户端

const BASE = "http://127.0.0.1:19527";
const TOKEN = process.env.MF_LOCAL_API_TOKEN;

const api = (path, init = {}) => fetch(BASE + path, {
  ...init,
  headers: {
    "X-MatrixFlow-Token": TOKEN,
    "Content-Type": "application/json",
    ...(init.headers || {})
  }
}).then((r) => r.json());

const list = await api("/api/v1/profiles?page=1&pageSize=50");
console.log(list.data.map((p) => `${p.seqId} ${p.name}`));

await api(`/api/v1/profiles/${list.data[0].id}/open`, {
  method: "POST",
  body: "{}"
});

接口分组

并发与超时

• 启动窗口建议客户端超时设为 60–90 秒；代理慢时需要更久。
• 同一窗口同一时间只执行一个自动化任务；不同窗口可并行 2–4 个。
• AI 任务有默认步数与时长上限（当前约为 300 步 / 8 分钟，以客户端实际配置为准）；长流程请拆分成多个任务。
• 并发冲突通常返回 409，等当前任务结束后重试，不要无脑循环。

查看完整 API 文档 →

MatrixFlow 自带一个 MCP 服务脚本，通过 stdio 把本地 API 包装成标准 MCP 工具。配置好之后，Claude Desktop、Cursor、Codex 等支持 MCP 的客户端就能直接列出窗口、打开/关闭窗口，或把自然语言任务交给 MatrixFlow 的 AI 助手。

{
  "mcpServers": {
    "matrixflow": {
      "command": "/opt/homebrew/bin/node",
      "args": [
        "/Applications/MatrixFlow.app/Contents/Resources/agent-skills/matrixflow-browser-control/scripts/matrixflow-mcp.mjs"
      ],
      "env": {
        "MF_LOCAL_API": "http://127.0.0.1:19527",
        "MF_LOCAL_API_TOKEN": "<从客户端 MCP 接入复制的 Token>"
      }
    }
  }
}

Windows 的 command 填本机 node 路径（例如 C:\\Program Files\\nodejs\\node.exe），args 填安装目录下的 resources\\agent-skills\\matrixflow-browser-control\\scripts\\matrixflow-mcp.mjs。路径中有空格时，JSON 字符串本身不需要额外转义空格，但反斜杠要写成双反斜杠。

只暴露 5 个工具

在 Agent 里怎么用

• 「列出所有窗口，告诉我哪些正在运行。」
• 「打开 3 号窗口到 https://example.com，等加载完成后读取标题。」
• 「让 MatrixFlow 的 AI 助手在 2 号窗口检查登录状态，并汇总成表格。」
• 「取消 2 号窗口正在跑的任务。」

排查

客户端自带 matrixflow-browser-control 技能，包含 SKILL.md 与一组脚本。把技能装进 Codex 后，Codex 可以像 AI 助手一样控制窗口；不接 Agent 时，也可以直接在终端运行 mf-browser.mjs，做确定性的批量操作。

技能位置

• macOS：/Applications/MatrixFlow.app/Contents/Resources/agent-skills/matrixflow-browser-control/
• Windows：<安装目录>\resources\agent-skills\matrixflow-browser-control\

安装到 Codex

mkdir -p ~/.codex/skills
cp -R "/Applications/MatrixFlow.app/Contents/Resources/agent-skills/matrixflow-browser-control" ~/.codex/skills/

xcopy /E /I /Y "<安装目录>\resources\agent-skills\matrixflow-browser-control" "%USERPROFILE%\.codex\skills\matrixflow-browser-control"

装好后在 Codex 里直接说「打开 3 号窗口，读取页面标题」，它会读取 SKILL.md 并按脚本执行。也可以让 MatrixFlow 的 AI 助手自己安装外部技能，见 技能安装。

先自检

cd "/Applications/MatrixFlow.app/Contents/Resources/agent-skills/matrixflow-browser-control/scripts"
node mf-browser.mjs doctor   # 检查客户端、Token、窗口与技能版本
node mf-browser.mjs status   # 当前连接状态

常用命令

命令示例

node mf-browser.mjs list
node mf-browser.mjs open 3 https://www.example.com
node mf-browser.mjs title 3
node mf-browser.mjs text 3 2000
node mf-browser.mjs screenshot 3 /tmp/shot.png
node mf-browser.mjs eval 3 "document.title"

Windows 下把输出路径换成 D:\shot.png 这类本地路径。命令的具体参数以技能目录中的 SKILL.md 与 --help 为准；不同版本的脚本可能新增命令。

什么时候用脚本，什么时候用 AI

绝大多数问题集中在四类：代理不通、内存不足、登录态过期、状态同步延迟。下面按现象给出处理顺序。

窗口一直停在「启动中」

正常启动需要 15–45 秒，代理慢或首次加载会更久。超过 90 秒仍未就绪，按顺序检查：

1. 在客户端手动启动同一环境，看是否给出具体错误（代理认证失败、内核退出、端口占用）。
2. 到「代理管理」重新检测该代理；确认出口 IP、国家与延迟正常。
3. 关闭几个不用的窗口，释放内存；8GB 机器同时开 4 个以上窗口容易卡住。
4. 检查安全软件是否拦截了浏览器内核；必要时把 MatrixFlow 加入白名单。
5. 仍失败时重启客户端，并记录环境名称、时间与错误提示，联系支持。

Windows 上「关闭中」很久不结束

关闭窗口时客户端要先结束页面、收集标签页与 Cookie，再上传快照。页面有未保存表单、弹窗、下载任务，或代理/网络异常时，这一步可能变慢。可以这样处理：

1. 先等 60–90 秒，不要连续点关闭或强制结束进程。
2. 如果窗口还可见，手动关闭页面上的确认弹窗、取消未完成的下载，再点一次关闭。
3. 检查任务管理器中是否有残留的浏览器内核进程；只结束与该环境对应的进程，不要结束整个客户端。
4. 升级到最新版 2.1.16；关闭流程与状态同步在持续优化。
5. 超过 2 分钟仍卡住，重启客户端；重启后确认该环境是否已变为「已停止」，再决定是否重新打开。

列表显示「已停止」，但窗口还在

这是状态同步延迟，不影响窗口实际使用。切换一次页面、等待几秒或刷新列表即可。判断窗口是否真的在运行，以桌面窗口和「运行中」接口/列表为准。

代理检测失败或很慢

• 检测失败：核对主机、端口、账号密码；确认代理服务在线、没有 IP 白名单限制。
• 检测慢：延迟是物理距离与线路质量决定的，换更近的地区或更好的线路。
• 检测成功但窗口打不开：先用普通浏览器验证该代理能否访问目标站；部分站点会封锁数据中心 IP。

Cookie 导入成功但没登录

导入成功只代表格式解析通过，不代表会话仍有效。优先检查：Cookie 是否过期、域名是否匹配、是否缺少 httpOnly/secure/sameSite。最稳的做法是从仍处于登录状态的浏览器导出完整 JSON，重新导入；必要时重置环境后再导入。

AI 说「未确认」是什么意思

它完成了动作，但读回页面时没有找到预期结果。可能是页面还没加载完、结果在另一个标签页、网站文案与预期不同，或操作实际失败了。打开执行看板看最后一步与核验内容；让 AI 重新读取一次，或手动确认。不要直接重跑，避免重复提交。

AI 能绕过验证码、支付或实名吗

不能，也不应该。遇到验证码、支付确认、实名认证、短信验证等环节，AI 会停下或标记需要人工处理。请人工完成这些步骤后再继续自动化。试图绕过平台安全机制可能导致账号被封，甚至违反法律。

模型列表为空或没有最新模型

• 确认客户端已登录且网络正常。
• 在模型菜单点「同步」，重新拉取服务端模型库。
• 升级到最新客户端；旧版本可能缓存了过期列表。
• 公司网络若拦截模型服务域名，需要放行。

网页版和客户端有什么区别

网页版适合查看与管理云端配置、订阅和团队信息；指纹窗口、本地 API、MCP 与 Skill 都运行在桌面客户端里。需要真正启动窗口时，请安装并使用客户端。

同一账号能在两台电脑同时登录吗

可以登录，但同一环境的窗口不要在两台设备上同时操作。关窗快照是「后写覆盖先写」，同时操作会互相覆盖登录态。换设备前先在本机关窗并等待「云端已保存」。

关窗后换设备，登录态没同步

通常是快照还没上传完成。回到旧设备，打开该环境再关闭一次，等右上角出现「云端已保存」；新设备重新进入环境。仍不同步时，重新导入一次最新 Cookie。不要在两台设备上反复开关同一个环境。

批量启动多少个窗口合适

16GB 内存建议同时 2–4 个；24GB 可到 5–8 个，但要分批启动。8GB 机器不建议超过 3 个。窗口数量不是越多越好，代理带宽、CPU 和网站风控都会成为瓶颈。

删除环境能恢复吗

不能。删除会停止窗口、删除云端配置并清理本地数据与缓存。需要保留时，先创建快照或导出 Cookie。误删后只能重新创建环境并重新登录。

本地 API 返回 401 或连接被拒绝

• 401：Token 缺失或错误。重新从客户端复制，确认请求头名称是 X-MatrixFlow-Token，没有多余空格或换行。
• 连接被拒绝：客户端没启动，或本地端口未就绪。先启动客户端，再请求 /api/v1/matrixflow/local-api/info。
• 超时：启动窗口的请求可能超过 60 秒，调大客户端超时。

MCP 工具没有出现

先确认配置 JSON 合法、node 与脚本路径存在、客户端正在运行，然后重启 MCP 宿主。仍不行时在终端手动执行脚本看错误；Token 错误会表现为 401，客户端未启动会表现为连接被拒绝。

升级套餐后权益没生效

刷新页面或重新进入订阅页；管理员改套餐后成员端也需要刷新。还不行时退出到登录页再进入。若支付成功但套餐未变，保留订单号联系支持。

数据存在哪里，卸载会删除吗

Windows 在 %APPDATA%\@matrixflow\desktop，macOS 在 ~/Library/Application Support/@matrixflow/desktop。常规卸载通常不会主动删除这个目录；重装后仍可读取。需要彻底清理时，先确认已不需要本地登录态与 Token，再手动删除。

MatrixFlow 能同时操作很多账号、读取页面、执行脚本。请把下面几条当作使用前提，而不是可选的建议。

本地 API Token

• Token 等同于本机管理权限。只保存在自己的电脑上，不要发到聊天、工单、截图或代码仓库。
• 本地 API 只监听 127.0.0.1，不要尝试把它暴露到公网或做端口转发。
• 怀疑泄露时，停止客户端并更换 Token（以客户端提供的方式为准），同时检查本机是否有未知脚本在调用 API。
• 在脚本中使用环境变量读取 Token，不要把 Token 打印到日志。

账号、Cookie 与代理凭据

• Cookie 可以直接登录账号，按密码级别保护；不要导入来源不明的 Cookie。
• 代理账号密码、邮箱验证码、支付信息都不要交给 AI 或粘贴到对话里。
• 团队成员使用各自席位，不要共用账号密码；交接时用分组、备注与快照，而不是发 Cookie 文件。
• 截图分享前遮住邮箱、环境名、代理地址、Cookie 与订单信息。

AI 与数据边界

• AI 的指令、页面内容与截图会发送给你配置的模型服务。不要让它读取你不希望离开本机的页面。
• 需要 AI 看截图时，先裁剪或打码；只提供完成任务所需的最小信息。
• 高风险操作（发布、删除、付款、修改账号设置）使用「请求批准」，并在执行看板核对每一步。
• AI 可能理解错或页面可能变化；涉及金钱、法律、医疗等后果的操作，必须人工复核。

Skill 与 MCP 的供应链风险

• Skill 和 MCP 服务都能在本机执行代码、操作浏览器。只安装你信任的来源。
• 安装前阅读 SKILL.md 与脚本，确认没有上传 Cookie、密码或页面数据的行为。
• MCP 配置含 Token，不要提交到 Git；配置文件权限限制为当前用户可读。
• 不再使用的 Skill、MCP 服务与 API Token 及时移除。

合规使用

• 只操作你拥有或获得明确授权的账号与数据。
• 遵守目标平台的用户协议、robots 规则与当地法律法规；不要用自动化制造垃圾内容、虚假互动、诈骗或规避平台处罚。
• 不要用指纹浏览器从事侵犯他人隐私、绕过访问控制或其他违法活动。
• 涉及个人信息时，遵循最小必要原则，不采集、不存储与业务无关的数据。