MatrixFlow 开放接口

把指纹浏览器窗口、AI 助手、代理与环境管理全部开放：本地 HTTP API 给脚本和外部系统用，MCP 让 Claude Desktop / Cursor / Codex 直接接管窗口，AI 助手负责理解自然语言、执行并核验。

本地 API · http://127.0.0.1:19527 鉴权头 · X-MatrixFlow-Token MCP · stdio + 本地 API Swagger · /api-docs 只监听本机，不暴露公网

1本地服务指南

启动与监听

启动客户端后，本机自动监听 http://127.0.0.1:19527。仅监听回环地址，外网无法访问；Token 相当于本机管理权限，请勿外发。

获取 Token

Windows%APPDATA%\@matrixflow\desktop\local-api-token.txt
macOS~/Library/Application Support/@matrixflow/desktop/local-api-token.txt
界面客户端「AI 助手 → 🔌 MCP 接入」可一键查看并复制地址 / Token

健康检查

健康检查 / 服务信息
curl -H "X-MatrixFlow-Token: <token>" http://127.0.0.1:19527/api/v1/matrixflow/local-api/info
curl -H "X-MatrixFlow-Token: <token>" http://127.0.0.1:19527/api/v1/agent-board/snapshot

Swagger 交互文档

浏览器打开 http://127.0.0.1:19527/api-docs 即可在线调试全部接口。

2API 常见问题（先看）

现象原因与处理
401 UnauthorizedToken 不对或客户端未启动：重新复制 Token，并确认 MatrixFlow 正在运行
连接被拒绝客户端没开（本地端口只在客户端运行时存在）
窗口打不开代理不通 / 安全软件拦截：先在客户端手动点「启动」看具体报错
结果里没有预期数据统一信封是 {success, data}，先看 success 再看 data
想直接点击/输入页面页面级操作走「AI 助手」或「MCP 工具」，本地 HTTP 不提供裸页面操作端点（设计如此）

3请求参数与响应格式

通用请求

除注明外均使用 JSON 请求体，鉴权头 X-MatrixFlow-Token 必带。

通用响应信封

成功 / 失败
{"success": true, "data": { ... }}
{"success": false, "error": { "code": "VALIDATION_ERROR", "message": "platform must be one of ..." }}

SDK 示例（Node 18+）

JavaScript
const BASE = "http://127.0.0.1:19527";
const TOKEN = "<从客户端复制>";
const api = (p, init) => fetch(BASE + p, {
  ...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");
await api(`/api/v1/profiles/${list.data[0].id}/open`, { method: "POST", body: "{}" });
await api("/api/v1/matrixflow/agent/chat", {
  method: "POST",
  body: JSON.stringify({ sessionId: "demo", messages: [{ role: "user", content: "打开 3 号窗口，读取页面标题" }] })
});
Python（requests）
import requests
BASE = "http://127.0.0.1:19527"
H = {"X-MatrixFlow-Token": "<token>", "Content-Type": "application/json"}
print(requests.get(f"{BASE}/api/v1/profiles", headers=H, params={"page": 1, "pageSize": 50}).json()["data"])
print(requests.get(f"{BASE}/api/v1/ai-models", headers=H).json()["data"]["version"])

4浏览器窗口接口

方法路径说明
GET/api/v1/profiles窗口列表（page / pageSize）
POST/api/v1/profiles新建窗口（name / platform / startupUrl / groupId / proxyId / notes / fingerprint / cookies）
DELETE/api/v1/profiles/:id删除窗口（先停止再删除，不可恢复）
POST/api/v1/profiles/:id/open启动窗口并等内核就绪（建议超时 ≥60s）
POST/api/v1/profiles/:id/close关闭窗口（快路径立即关，后台完成快照）
GET/api/v1/profiles/running正在运行的窗口（含当前 URL / 出口 IP / 国家）

POST /api/v1/profiles 参数

参数类型必填说明
namestring是窗口名称
platformstring否CUSTOM / TIKTOK / FACEBOOK / INSTAGRAM / AMAZON / YOUTUBE / TWITTER / GOOGLE 等
startupUrlstring否自定义启动地址；永远作为第二个标签页，第一个标签页固定为产品导航页
groupId / proxyIdstring否所属分组 / 绑定代理
fingerprintobject否自定义指纹（os / userAgent / timezone / language / screen / webRTC / canvas / webGL / fonts）；不传则自动随机（默认中文）
新建窗口 + 启动
curl -X POST "http://127.0.0.1:19527/api/v1/profiles" \
  -H "X-MatrixFlow-Token: <token>" -H "Content-Type: application/json" \
  -d '{"name":"小红书9","platform":"CUSTOM","startupUrl":"https://www.xiaohongshu.com"}'
# {"success":true,"data":{"id":"cmu...","seqId":9,"fingerprint":{...}}}

curl -X POST "http://127.0.0.1:19527/api/v1/profiles/cmu.../open" \
  -H "X-MatrixFlow-Token: <token>" -d '{}'
# {"success":true,"data":{"status":"RUNNING",...}}；未就绪会如实返回失败原因

5浏览器分组接口

分组走云端接口（需要登录态 Bearer Token，客户端内部已托管）：

方法路径说明
GET/profile-groups分组列表（含每个分组内窗口数）
POST/profile-groups新建分组（name）
PATCH/profile-groups/:id重命名分组
DELETE/profile-groups/:id删除分组（组内窗口变为未分组）
PATCH/profiles/:id改窗口（groupId 移到目标分组，空串 = 移出分组）

6会话快照接口（跨设备登录态）

方法路径说明
GET/api/v1/window-sync/snapshots快照列表
POST/api/v1/window-sync/snapshots手动创建快照
POST/api/v1/window-sync/snapshots/:id/restore恢复某窗口的标签页 / Cookie / 登录态
DELETE/api/v1/window-sync/snapshots/:id删除快照

7工作流 / RPA 接口

方法路径说明
GET/api/v1/matrixflow/workflows工作流列表
POST/api/v1/matrixflow/workflows/sync同步工作流到云端
POST/api/v1/matrixflow/workflows/init初始化工作流
POST/api/v1/matrixflow/workflows/hard-save强制保存工作流 JSON
POST/api/v1/matrixflow/workflows/rename重命名工作流
POST/api/v1/matrixflow/automa/open在绑定窗口打开 Automa 设计器
GET/api/v1/automation/tasksRPA 任务列表
POST/api/v1/automation/tasks/:id/run立即执行 RPA 任务
GET/api/v1/matrixflow/rpa/target-tabs绑定窗口的标签页列表
POST/api/v1/matrixflow/rpa/create-tab新建标签页
POST/api/v1/matrixflow/rpa/update-tab更新标签页
POST/api/v1/matrixflow/rpa/remove-tab关闭标签页
POST/api/v1/matrixflow/rpa/execute-script在窗口内执行脚本
POST/api/v1/matrixflow/rpa/send-message向窗口发送消息

8AI 助手接口

方法路径说明
POST/api/v1/matrixflow/agent/chat下一条自然语言任务（内部：计划 → 执行 → 核验）
POST/api/v1/matrixflow/agent/chat/cancel取消当前会话任务
GET/api/v1/ai-models后台模型库 + 当前选择 + 推理强度
POST/api/v1/ai-models/sync立即拉取最新模型清单
GET/api/v1/agent-board/snapshot所有任务卡（状态 / 计划 / 每步结果 / 核验）
GET/agent-board/eventsSSE 实时事件流（带 token 参数）
POST/api/v1/agent-board/cancel停止指定任务
POST/api/v1/agent-board/clear清理已结束任务卡

agent/chat 请求体

请求体
{
  "sessionId": "my-job-1",
  "messages": [
    { "role": "user", "content": "打开 3 号窗口，海外版小红书养号 10 分钟" }
  ]
}

多模态：content 支持 [{type:"text"},{type:"image_url",image_url:{url:"data:image/png;base64,..."}}]，V4.1 Flash 会直接看图。

9微信远程接口

方法路径说明
GET/api/v1/wecom/status微信远程绑定状态
GET/api/v1/wecom/log最近消息日志
POST/api/v1/wecom/rotate轮换绑定
POST/api/v1/wecom/unbind解绑
POST/api/v1/wecom/open-media打开媒体文件

10MCP 接入（Claude Desktop / Cursor / Codex）

客户端「AI 助手 → 🔌 MCP 接入」一键复制下面的配置，粘到 Claude/Cursor/Codex 的 mcpServers 即可。

mcpServers 配置
{
  "mcpServers": {
    "matrixflow": {
      "command": "<本机 node 路径>",
      "args": ["<安装目录>/resources/agent-skills/matrixflow-browser-control/scripts/matrixflow-mcp.mjs"],
      "env": {
        "MF_LOCAL_API": "http://127.0.0.1:19527",
        "MF_LOCAL_API_TOKEN": "<从客户端复制的 Token>"
      }
    }
  }
}

MCP 工具

mf_list_windows列出所有窗口（序号 / 名称 / ID / 平台 / 状态）
mf_open_window打开窗口并跳转到指定网址
mf_close_window关闭窗口
mf_agent_chat下一条自然语言任务（复用 AI 助手全部能力）
mf_agent_cancel取消进行中的任务

更细的页面操作（点击/输入/滚动/读文本/截图/发笔记/养号）直接通过 mf_agent_chat 用自然语言下发，或安装完整 Skill 后使用其内置脚本。

11附录

HTTP 状态码

状态码含义处理
200/201成功读取 data
400参数不合法按 error.message 修正
401Token 缺失或错误重新复制 Token
404资源不存在用列表接口确认 ID / 序号
409并发冲突等当前任务结束或换窗口
500服务内部错误看 error.message；仍失败重启客户端

并发与限制

  • 只监听 127.0.0.1，Token 等于本机权限，请勿外发。
  • 同一窗口同一时间只跑一个任务；多窗口建议并发 2-4 个（6 个以上容易把内存压满）。
  • 单条 AI 任务默认上限 8 分钟 / 300 步；发布、注册类脚本单次最长 7 分钟。
  • 窗口启动 15-45 秒（取决于代理），接口超时建议 ≥60 秒。
页面级操作（点击 / 输入 / 滚动 / 读文本 / 截图 / 发笔记）不做裸 HTTP 端点——统一走「AI 助手」或「MCP 工具」，保证操作前读页面、操作后强制核验，不会出现“假成功”。