> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openkova.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 远程访问与移动端

> 桌面端网关、配对码换 token、三种网络接入方式，以及 Expo 构建的移动 App。

扣瓦的移动端不是"另写一套客户端"，而是**桌面端开一个网关，
手机和浏览器当视口**。对话、工具执行、文件都还在桌面那边，
所以手机断网时桌面照常干活，重连后能接上。

## 工作原理

<Steps>
  <Step title="桌面端开启远程网关">
    在设置 → 远程里打开网关。sidecar 通过 `axum` 起一个 HTTP + WebSocket 服务，
    把会话与工具调用桥接出来。
  </Step>

  <Step title="用配对码换 token">
    首次连接时输入配对码，服务端签发 token。token 存入系统钥匙串
    （iOS Keychain / Android Keystore），之后免输入。
  </Step>

  <Step title="走 WebSocket 连上 sidecar">
    移动 App 与远程网页端连的是同一个 `/ws` 端点、原语相同的协议。
    桌面端的会话流、工具调用、检查点在另一端原样呈现。
  </Step>
</Steps>

## 三种网络接入

<Columns cols={3}>
  <Card title="局域网直连">
    默认可用。桌面和手机在同一 Wi-Fi 下，
    直接连桌面机的局域网地址。适合家里和办公室。
  </Card>

  <Card title="Cloudflare Tunnel">
    公网接入且不需要公网 IP。
    仓库支持补充 Cloudflare 网关 ID 等凭据字段来走认证流程。
  </Card>

  <Card title="Tailscale">
    同样免暴露公网，走私有网络地址。
  </Card>
</Columns>

其他任何 WebSocket 客户端也能接入——协议是公开的 NDJSON over WS。

## 安全须知

<Warning>
  远程接入默认面向可信网络。使用前请确认：

  * 配对码只在局域网内当面传输，不要贴到公开渠道；
  * 当前 token **长效不过期**，撤销只能靠桌面端的「撤销所有设备」；
  * 端到端加密尚未落地，隧道/中继链路上的流量目前是明文 WS。
    如果要走公网，请优先选 Tailscale 这类私有网络方案。
</Warning>

## 移动 App

<CardGroup cols={2}>
  <Card title="技术选型">
    Expo SDK 57 + React Native 0.86 + `@assistant-ui/react-native`。
    刻意**不**用 Tauri mobile，而是复用桌面网关的 `/ws` 协议，
    与浏览器网页端同源。
  </Card>

  <Card title="依赖隔离">
    移动端依赖装在 `apps/mobile/node_modules`
    （`install.hoistingLimits = "workspaces"`）。
    RN 0.86 只能配 react 19.2.3，与桌面的 react 19.3 各持一份，
    避免 hoisting 互相抬版本导致 Metro 双实例。
  </Card>
</CardGroup>

```bash theme={null}
# 桌面端先开远程网关并允许局域网访问，然后：
bun run dev:mobile        # Expo 开发
bun run typecheck:mobile  # 类型检查
bun run test:mobile       # 单元测试
bun run build:mobile:web  # web 静态导出 → apps/mobile/dist
```

移动端还内置了**演示模式**，不连真实网关也能浏览界面。

## 远程网页端的功能边界

浏览器网页端是三端里功能最全的一个（它跑在桌面环境里），
但仍有一些边界：

* 不能安装 / 卸载插件——插件市场是桌面本地行为；
* 不能改系统级设置与凭据管理，这些走 Rust 宿主的系统钥匙串；
* 系统级能力（窗口控制、终端、截图）需要桌面宿主在场。

## Agent 始终跑在桌面

这一点值得单独说，因为它决定了远程访问在体验上意味着什么。

<Columns cols={2}>
  <Column title="执行位置不变">
    模型调用、工具执行、文件读写全在桌面侧的 sidecar 里。
    手机连的是一个视口，不是一个被降级过的第二套实现。
    桌面关机了，手机就只是一个连不上的壳。
  </Column>

  <Column title="所以 agent 不会被打断">
    手机息屏、切后台、掉 Wi-Fi，都不影响桌面上正在跑的任务。
    重新连上后看到的是同一个回合的延续。
  </Column>
</Columns>

这也是远程审批在路线图里而不是现在的原因：
审批请求属于执行路径的一部分，要做到"推到手机上等你放行"，
得先解决断线补拉与会话状态对齐——否则批准一个你看不到上下文的操作是危险的。

<Note>
  当前形态下，审批卡会出现在你正在使用的那个客户端上。
  在桌面发起并在桌面批准是安全的；在手机上批准则要清楚自己批的是什么。
  这一层的安全性依赖于配对设备本身可信，而不是每次都重新鉴权。
</Note>

## 还没做的

移动端真正的短板在"离开电脑"这件事上，目前还没有：

* 推送通知（任务完成、等待审批、定时任务结果到手机）；
* 生物识别解锁与 token 轮换；
* 离线草稿与弱网下的排队发送、流中断续播；
* 窄屏交互打磨（手势、附件选择、会话列表重排）。

这些都在[路线图](/reference/roadmap)里。当前形态适合"手机当随身遥控器，
真正干活的还是桌面"，而不是反过来。

<Card title="下一步" icon="arrow-right" href="/developers/architecture">
  理解这些功能各自跑在哪一层。
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.