用手机操控本地 AI Agent：OpenClaw + Cursor 实战

手机发一句"帮我看看 auth 模块最近改了啥"，家里电脑上的 Cursor Agent 就开始读代码、跑命令，结果推回手机。

这篇文章记录完整的搭建过程。核心思路是：用 OpenClaw 做网关，把 Cursor Agent CLI 的能力暴露给任意客户端（Kimi、飞书、Slack 等）。搭完之后不需要坐在电脑前，手机上就能指挥本地 Agent 干活。

整体架构

手机 / 网页 / IM 机器人
  │
  ▼
OpenClaw Gateway（本地网关，端口 18789）
  │
  ▼
openclaw-cursor-brain 插件
  │
  ▼
Streaming Proxy（本地代理，端口 18790）
  │
  ▼
Cursor Agent CLI（无头命令行 Agent）
  │
  ▼
Claude / GPT / Gemini（Cursor 订阅的模型）

你在手机上打字 → 消息走到本地 OpenClaw → OpenClaw 启动 Cursor Agent → Agent 用你订阅的模型处理 → 结果原路返回。全程除了模型 API 调用，其他都跑在本地。

环境信息

Fedora 42, aarch64（Asahi Linux on Apple Silicon）
Node.js 22（通过 nvm 安装）
Cursor 桌面版已安装
Cursor Pro/Business 订阅（Agent CLI 需要）

第一步：安装 OpenClaw

bash

npm install -g @anthropic-ai/openclaw

国内网络可以先切镜像：

bash

npm config set registry https://registry.npmmirror.com

部分客户端插件依赖 node-pty 原生模块，需要编译工具链：

bash

# Fedora
sudo dnf install -y gcc-c++ make

# Ubuntu / Debian
sudo apt install -y build-essential

验证：

bash

$ openclaw --version
2026.3.8

第二步：安装 Cursor Agent CLI

Cursor 有两个完全不同的可执行文件，别搞混：

文件	本质	用途
`/usr/bin/cursor`	Electron 桌面应用	打开 GUI 编辑器
`~/.local/bin/agent`	Node.js 命令行工具	无头 Agent，我们要用的

安装 CLI：

bash

curl https://cursor.com/install -fsS | bash

验证：

bash

$ which agent
/home/user/.local/bin/agent

$ agent --version
2026.02.27-e7d2ef6

踩坑提醒：如果后面把 cursorPath 错误地指向 /usr/bin/cursor，每次请求都会弹出一个桌面窗口。从 gateway 日志可以区分——无头 CLI 会显示 Output format: "stream-json"，桌面版显示 "json"。

第三步：Agent CLI 认证

CLI 和桌面版的登录是各自独立的。桌面版已经登录了也没用，CLI 会报：

Error: Authentication required. Please run 'agent login' first.

在 Cursor IDE 的内置终端里运行（不要在外部终端或 Agent 模式里运行，会卡住）：

bash

agent login

Cursor 会接管 OAuth 流程，完成后验证：

bash

$ agent -p --trust "回复 ok"
ok

看到输出就说明认证成功了。

桌面版的 session token（state.vscdb 里的 JWT）和 CLI 需要的凭证是不同类型，不能互用。

第四步：安装桥接插件

bash

openclaw plugins install openclaw-cursor-brain

这个插件做两件事：

让 OpenClaw 知道怎么启动 Cursor Agent CLI
在 Cursor 侧注册 MCP Server，把 OpenClaw 的所有工具（飞书、GitHub 等）桥接给 Agent

安装完重启 gateway 加载插件：

bash

openclaw gateway restart

如果 CLI 路径自动检测不到，手动指定：

bash

openclaw config set plugins.entries.cursor-bridge.config.cursorPath \
  "/home/user/.local/bin/agent"

第五步：配置

选模型

查看可用模型：

bash

curl -s http://127.0.0.1:18790/v1/models | python3 -c \
  "import sys,json; [print(m['id']) for m in json.load(sys.stdin)['data']]"

通常能看到 45 个左右，覆盖 Claude、GPT、Gemini 等系列。

推荐用 sonnet-4.6-thinking——带思考链，多轮对话的上下文保持和复杂推理都明显优于不带 thinking 的版本：

bash

openclaw config set agents.defaults.model.primary "cursor-local/sonnet-4.6-thinking"

各模型定位：

模型	速度	推理能力	适用场景
`auto`	—	—	不想选，让 Cursor 决定
`sonnet-4.6`	快	一般	简单单轮问答
`sonnet-4.6-thinking`	中等	强	日常推荐
`opus-4.6-thinking`	慢	最强	复杂架构分析

工作空间

指定 Agent 的工作目录，决定它能读写哪些文件：

bash

openclaw config set agents.defaults.workspace "/home/user/Documents/my-project"

不设置的话 Agent 无法访问项目文件。

局域网访问

默认只监听本机。要从手机访问，需要开局域网：

bash

openclaw config set gateway.bind "lan"

不能直接填 0.0.0.0，配置校验只接受枚举值。

安全令牌

局域网开放后务必设置 token，防止未授权访问：

bash

openclaw config set gateway.auth.mode "token"
openclaw config set gateway.auth.token "你的自定义密码"

每次改完配置后运行 openclaw gateway restart 生效。

第六步：修复会话记忆

这是一个已知问题。不修复的话，Agent 每条消息都是全新对话，记不住任何上下文。

问题

Cursor Agent CLI 支持通过 --resume <session_id> 恢复历史对话。但桥接插件的 streaming proxy 有个 bug：OpenClaw 发请求时不带 session ID，proxy 找不到 session key，于是每次都启动全新的 agent 进程。

从 proxy 日志可以确认——session=none(none) 说明 session 没有建立：

[chatcmpl-xxx] stream request: session=none(none), msg="你好"
[chatcmpl-xxx] stream request: session=none(none), msg="我叫什么"

修复（改一行代码）

编辑 proxy 源码：

bash

~/.openclaw/extensions/openclaw-cursor-brain/mcp-server/streaming-proxy.mjs

找到 resolveSessionKey 函数（大约在第 369 行），把最后一行改掉：

javascript

// 改前：
return { key: null, src: "none" };

// 改后：
return { key: "default", src: "fallback" };

重启 gateway：

bash

openclaw gateway restart

修复后的效果

第一条消息：创建新 session，agent 返回 session_id，proxy 存入 ~/.openclaw/cursor-sessions.json
后续消息：proxy 用 --resume 恢复 session，agent 能看到完整历史
日志变为 session=default(fallback)

Agent 的对话历史存在 SQLite 数据库里（~/.cursor/chats/<hash>/<session_id>/store.db），和 Cursor IDE 里的 Agent 对话用的是同一套机制。

注意：插件更新会覆盖这个修改，每次 openclaw plugins install openclaw-cursor-brain 后需要重新应用。

清空历史

如果需要从头开始：

bash

rm -f ~/.openclaw/cursor-sessions.json
rm -f ~/.openclaw/agents/main/sessions/*.jsonl
rm -f ~/.openclaw/agents/main/sessions/sessions.json
openclaw gateway restart

第七步：启动并验证

bash

openclaw gateway

检查关键日志：

[gateway] Cursor Agent found at /home/user/.local/bin/agent     ← CLI 路径正确
[gateway] Output format: "stream-json"                          ← 无头 CLI（非桌面版）
[gateway] Discovered 45 cursor-agent models                     ← 认证成功（0 说明没登录）
[gateway] Cursor Brain setup complete                           ← 插件加载完成
[gateway] Provider "cursor-local" synced (45 models, port 18790)
[gateway] agent model: cursor-local/sonnet-4.6-thinking         ← 当前模型
[gateway] listening on ws://0.0.0.0:18789                       ← 网关就绪

本地测试

bash

# 健康检查
curl -s http://127.0.0.1:18790/v1/health | python3 -m json.tool

json

{
    "status": "ok",
    "cursor": true,
    "sessions": 0,
    "consecutiveFailures": 0
}

测试会话记忆

bash

# 第一条：建立 session
curl -s -X POST http://127.0.0.1:18790/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer local" \
  -d '{"model":"sonnet-4.6-thinking","stream":false,
       "messages":[{"role":"user","content":"记住：我叫 test-user"}]}'

# 第二条：测试 resume
curl -s -X POST http://127.0.0.1:18790/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer local" \
  -d '{"model":"sonnet-4.6-thinking","stream":false,
       "messages":[{"role":"user","content":"我叫什么名字？"}]}'

如果第二条能答出 test-user，说明 session 修复生效了。

性能参考

Sonnet 4.6 模型实测（含 CLI 启动开销）：

任务	首次（新 session）	后续（resume）
极简回复	~5s	~3s
工具调用（读文件、跑命令）	~10s	~7s
代码生成	~11s	~8s

resume 比新建 session 快 30-40%，因为跳过了初始化。

第八步：接入 Kimi（手机端）

到这里核心链路已经通了。接下来把 Kimi 接上，就能在手机上用了。

方式一：Kimi Claw 关联本地实例（推荐）

打开 kimi.com，找到 Kimi Claw 入口
选择「关联已有实例」
输入 Gateway 的 WebSocket 地址：ws://<你的局域网 IP>:18789
输入你设置的 auth token
关联成功后，Kimi 网页端和手机 App 都能直接对话

手机和电脑需要在同一局域网（或通过 Tailscale / frp 打通）。

方式二：IM 插件桥接

不想用 Kimi 的话，可以装 IM 客户端插件：

客户端	安装命令
飞书	`openclaw plugins install @openclaw/feishu`
Telegram	`openclaw plugins install @openclaw/telegram`
Discord	`openclaw plugins install @openclaw/discord`
Slack	`openclaw plugins install @openclaw/slack`

装完在对应 IM 里给机器人发消息即可，手机端同样可用。

典型使用场景

出门在外排查问题：

看看 auth 模块最近的报错，分析下原因

Agent 在你的项目目录里跑 git log、读源码、分析报错，结果推回手机。

通勤路上想方案：

分析当前项目的数据库查询，找出最慢的 3 个

结果等你到电脑前再 review。

随时问代码：

解释 src/middleware/auth.ts 中 JWT 验证的完整流程

答案基于你的真实项目源码。

注意事项

Agent 带 --trust 和 --force flag，手机端发的指令可以直接修改文件
生产环境务必配置 auth token
确保手机能访问电脑的局域网 IP

完整配置参考

~/.openclaw/openclaw.json 核心部分：

json

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "cursor-local/sonnet-4.6-thinking"
      },
      "workspace": "/home/user/Documents/my-project",
      "compaction": {
        "mode": "safeguard"
      }
    }
  },
  "gateway": {
    "mode": "local",
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "YOUR_TOKEN"
    }
  },
  "plugins": {
    "entries": {
      "openclaw-cursor-brain": {
        "enabled": true,
        "config": {
          "cursorPath": "/home/user/.local/bin/agent"
        }
      }
    }
  }
}

models.providers.cursor-local 由插件自动生成，不需要手写。客户端插件（kimi-claw 等）的配置按各自文档添加到 plugins.entries。

常见问题

现象	原因	解决
每次请求弹出 Cursor GUI 窗口	`cursorPath` 指向了桌面版 `/usr/bin/cursor`	改为 `~/.local/bin/agent`
`Authentication required`	CLI 和桌面版认证独立	在 Cursor IDE 内置终端运行 `agent login`
`Discovered 0 models`	CLI 未认证	登录后 `openclaw gateway restart`
Agent 记不住上下文	proxy 的 session key 为 null	修改 `resolveSessionKey`，见第六步
`gateway.bind` 设 `0.0.0.0` 被拒	只接受枚举值	用 `"lan"`
Agent 无法访问项目文件	未配置工作空间	设置 `agents.defaults.workspace`
health 显示 `consecutiveFailures` 非零	历史请求失败被记录	`openclaw gateway restart` 重置
长对话中 Agent 越来越"健忘"	`compaction` 压缩了旧消息	gateway 日志搜 `compaction triggered` 确认

附录：内部机制

以下内容不影响使用，供感兴趣的读者参考。

插件自动配置

openclaw-cursor-brain 安装后自动写入两处配置（不需要手动改）：

~/.cursor/mcp.json —— 在 Cursor 侧注册 MCP Server，让 Agent 能调用 OpenClaw 的工具：

json

{
  "mcpServers": {
    "openclaw-gateway": {
      "command": "node",
      "args": ["<plugin-path>/mcp-server/server.mjs"],
      "env": {
        "OPENCLAW_GATEWAY_URL": "http://127.0.0.1:18789",
        "OPENCLAW_GATEWAY_TOKEN": "<token>"
      }
    }
  }
}

openclaw.json 的 cliBackends —— 告诉 Gateway 怎么 spawn Agent：

json

{
  "cliBackends": {
    "cursor-cli": {
      "command": "/bin/bash",
      "args": ["-c", "export SHELL=/bin/bash && cd <workspace> && exec <cursorPath> \"$@\"",
               "_", "-p", "--output-format", "json", "--trust", "--approve-mcps", "--force"],
      "sessionArg": "--resume",
      "sessionMode": "existing"
    }
  }
}

CLI Flag 含义

Flag	作用
`-p`	从 stdin 读取 prompt（管道模式）
`--trust`	信任工作目录，跳过安全确认
`--approve-mcps`	自动批准 MCP Server 连接
`--force`	强制执行，不弹交互确认
`--output-format json`	JSON 输出，便于 Gateway 解析
`--resume <id>`	恢复已有 session

插件管理命令

命令	说明
`openclaw cursor-bridge doctor`	健康检查（CLI 路径、Gateway 连接、Token、MCP）
`openclaw cursor-bridge status`	查看当前配置
`openclaw cursor-bridge setup`	重新执行自动配置
`openclaw cursor-bridge uninstall`	完整卸载（含配置清理）

不要用 openclaw plugins uninstall cursor-bridge，那只删注册项，不清理 mcp.json 和 cliBackends 残留。

MCP 工具发现

MCP Server 启动时自动扫描所有 OpenClaw 插件，注册可用工具。两个内置工具始终存在：

openclaw_invoke —— 按名称调用任意工具
openclaw_discover —— 列出所有可用工具

新装的 OpenClaw 插件会被自动发现，无需手动配置。

会话存储细节

Cursor Agent CLI 的每个 session 对应一个 SQLite 数据库：

~/.cursor/chats/<workspace_hash>/<session_id>/store.db

内部用 content-addressed Merkle tree 存储对话：blobs 表保存每条消息（JSON，SHA-256 为 key），meta 表保存会话元数据（当前根节点、创建时间等）。和 Cursor IDE 里的 Agent 对话用的是同一套存储格式。

OpenClaw 自己也有一层 session（~/.openclaw/agents/main/sessions/*.jsonl），记录所有客户端消息。但真正让 Agent 保持上下文的是 Cursor CLI 的 SQLite session。

桥接插件通过 ~/.openclaw/cursor-sessions.json 维护 session key 到 Cursor session ID 的映射：

请求进来 → resolveSessionKey() 拿到 key
  → 查 cursor-sessions.json 找对应的 session_id
    → 有：agent --resume <session_id>（恢复历史）
    → 无：agent（新建 session），完成后保存映射

跨平台路径

平台	CLI 路径	mcp.json
Linux / macOS	`~/.local/bin/agent`	`~/.cursor/mcp.json`
Windows	`%LOCALAPPDATA%\Programs\cursor\...\agent.exe`	`%USERPROFILE%\.cursor\mcp.json`

用手机操控本地 AI Agent：OpenClaw + Cursor 实战 ​

整体架构 ​

环境信息 ​

第一步：安装 OpenClaw ​

第二步：安装 Cursor Agent CLI ​

第三步：Agent CLI 认证 ​

第四步：安装桥接插件 ​

第五步：配置 ​

选模型 ​

工作空间 ​

局域网访问 ​

安全令牌 ​

第六步：修复会话记忆 ​

问题 ​

修复（改一行代码） ​

修复后的效果 ​

清空历史 ​

第七步：启动并验证 ​

本地测试 ​

测试会话记忆 ​

性能参考 ​

第八步：接入 Kimi（手机端） ​

方式一：Kimi Claw 关联本地实例（推荐） ​

方式二：IM 插件桥接 ​

典型使用场景 ​

注意事项 ​

完整配置参考 ​

常见问题 ​

附录：内部机制 ​

插件自动配置 ​

CLI Flag 含义 ​

插件管理命令 ​

MCP 工具发现 ​

会话存储细节 ​

跨平台路径 ​

用手机操控本地 AI Agent：OpenClaw + Cursor 实战

整体架构

环境信息

第一步：安装 OpenClaw

第二步：安装 Cursor Agent CLI

第三步：Agent CLI 认证

第四步：安装桥接插件

第五步：配置

选模型

工作空间

局域网访问

安全令牌

第六步：修复会话记忆

问题

修复（改一行代码）

修复后的效果

清空历史

第七步：启动并验证

本地测试

测试会话记忆

性能参考

第八步：接入 Kimi（手机端）

方式一：Kimi Claw 关联本地实例（推荐）

方式二：IM 插件桥接

典型使用场景

注意事项

完整配置参考

常见问题

附录：内部机制

插件自动配置

CLI Flag 含义

插件管理命令

MCP 工具发现

会话存储细节

跨平台路径