LinkShell EN

LinkShell 文档

LinkShell 分两部分：电脑上的 Host（可用 Mac、Windows 桌面 App 或 CLI 管理），和手机上的 App。下面按顺序走一遍。

安装

Mac · Apple Silicon Mac · Intel

独立 Mac App 需要 macOS 13 及以上，内置运行环境，无需另外安装 Node。打开 App 即可登录、管理服务与更新；下面是可选的命令行安装方式。

Windows · 安装器 Windows · ZIP

Windows 桌面版需要 Windows 10 1809+ / Windows 11 x64，内置 CLI、Host 和 Node；窗口与 Mac 是同一个 Electron 应用，不需要 WebView2 Runtime。安装器和便携 ZIP 均未签名，可能出现「未知发布者」或 SmartScreen 提示。

CLI 方式需要 macOS 或 Linux、Node.js 22.13 或更新版本（独立 Mac App 已内置）。

$ npm i -g linkshell-cli
# 或
$ brew install LiuTianjie/linkshell/linkshell
# 或
$ curl -fsSL https://liutianjie.github.io/LinkShell/install.sh | sh

要用的 Agent 需要你自己安装并在电脑上登录好（比如 claude、codex login、gemini、copilot login）。手机 App：iPhone · Android APK。

Mac 桌面版与更新

总览和设置提供“登录 / 注册”、当前账号和退出登录。登录会打开系统浏览器，完成后自动刷新；官方网关需要 iTool 会员。账号已登录与网关在线是两个独立状态。关闭窗口后 App 留在菜单栏，退出界面不会停止后台服务。

App、CLI、Host 和 Node 整体更新。自动检查只检查版本，安装需确认，可能中断正在运行的任务；完成后恢复本 App 托管的 Host，保留机器身份、配对和历史。已有 npm / Homebrew 安装不会被覆盖。设置可选安装终端命令，该命令随 App 更新。

本机数据默认在 ~/.linkshell，不在 App 内。完整说明见 桌面版使用说明。

启动 LinkShell

$ linkshell host --daemon   # 后台运行
$ linkshell host status     # Agent、会话、网关状态
$ linkshell host stop

host 用你登录 shell 的环境变量启动 Agent，所以 PATH、代理、API key 这些和在终端里一样。会话和历史保存在 ~/.linkshell，重启电脑不需要重新配对。

连接手机

Pro：官方网关

$ linkshell login
$ linkshell host stop && linkshell host --daemon

在 App 里用同一个账号登录，电脑会自动出现在「电脑」页，不需要扫码。了解 iTool 会员。

自建网关：配对

$ linkshell host --gateway wss://gw.example.com --daemon
$ linkshell pair

终端里会出现二维码和 6 位配对码。在 App 的「电脑 → 添加电脑」里扫码或输入配对码。网关地址会保存下来，之后启动 host 不用再写 --gateway；--gateway off 可以关掉。

自建网关

网关只转发加密数据，不需要多少资源。任选一种：

# 在服务器上用 CLI
$ linkshell gateway --port 8787 --daemon
# 或 Docker
$ docker run -d --name linkshell-gateway -p 8787:8787 \
    -v linkshell-gateway:/data nickname4th/linkshell-gateway

公网上请在前面加一层 HTTPS 反向代理（Caddy、Nginx 都行），然后用 wss://你的域名。只在家里用的话，可以直接把网关跑在这台电脑上，用 ws://局域网IP:8787。

在电脑终端里用

$ linkshell claude [参数]   # Claude Code，可交给手机
$ linkshell codex [参数]    # Codex，和手机同步

参数原样传给 Agent（比如 linkshell claude --resume <id>）。Claude 在电脑上运行时，手机能实时看到进度；在手机上发消息就接管，终端会显示「已由手机接管」，按任意键收回。

Claude 在收到第一条消息之前不会保存会话，所以一个还没发过消息的会话不能交给手机。

在手机上用

  • 新建会话：选 Agent 和项目目录，直接开始。
  • 回答提问：Codex（含 Desktop 异步提问）、Claude、Cursor 和 Grok 的结构化问题会显示「需要用户输入」，可在手机卡片中作答或跳过。Cursor 支持选择，其他类型按 Agent 提供的能力支持文字回答。
  • 忙的时候发消息：消息在输入框上方排队，可以调整顺序、取回编辑、立即发送（Codex 和 Claude 直接插进当前这一轮，其他 Agent 先停下当前这一轮）；停止时排队的文字会放回输入框。
  • 分叉与 worktree：每条回复下方可以「从这里分叉」，会话菜单里可以分叉整个会话；新建会话或分叉时可以选择放进新的 git worktree（在 ~/.linkshell/worktrees/ 下，独立分支），删除会话时没有改动的 worktree 会一起清掉。
  • 旁支对话：会话菜单里的「旁支对话」，或直接输入 /side（Codex）、/btw（Claude、Grok）加问题。Codex 在只读的临时分叉里回答，可以查看文件；Claude 和 Grok 只依据对话回答。旁支只保存在电脑上，关掉就没了，不写进会话。
  • 命令面板：输入 /、点击输入框的命令按钮，或从会话菜单打开命令面板，搜索 Agent 的命令与 skills；草稿会保留。
  • 持续目标：Codex 和 Claude Code 支持 /goal，也可从菜单进入目标页面。Codex 可设置预算、暂停和继续；Claude 可设置或清除完成条件。需电脑上的 Agent 支持相应能力。
  • 后台任务：/tasks 或标题旁的入口可查看回复结束后仍运行的命令、输出和退出码。Codex 支持单任务停止；Claude Bash / Monitor 目前只支持查看，停止请在电脑端操作。
  • 屏幕适配：iPhone Duo 和普通 iPhone 都会根据可用空间调整聊天、输入框和操作区。
  • 工作流、子 Agent 与文件：会话标题旁的按钮列出工作流和子 Agent；输入框上方可回到后台工作流；会话和终端的菜单里可以浏览项目文件。
  • 设置：输入框下方可以换模型、思考强度、权限模式（取决于 Agent 提供了哪些）。
  • Agent 连接与工具：从「电脑」里的 Agent 设置完成登录、配置 MCP 服务和附加目录，也可以添加自定义 ACP 连接。支持编辑建议的 Agent 可以在文件页提出修改，预览后再应用；具体功能取决于 Agent 提供的能力。
  • 整理：长按会话可以重命名、归档、删除；从首页底部进入已归档，也可以搜索查找。Codex 归档同步到原生记录，查看历史不会解除归档；Claude 和其他 Agent 的归档仅保存在 LinkShell。不再使用的电脑，在账号页的「我的电脑」里长按移除。
  • 会话恢复：电脑端 CLI 0.10.19 会重新核对任务状态，避免已结束的任务一直显示运行中。原始记录缺失或读取失败时会显示原因，并保留已经缓存的消息；重新打开可重试。
  • Apple Watch：2.3.33 加入独立腕表连接。在腕表「连接设置」登录邮箱/密码账号或输入电脑配对码，查看会话、处理简单审批并发送短消息；也可切换 iPhone 配套模式。独立连接在 App 前台运行，需要 Gateway 0.6.20 或更新版本。
  • 终端、预览、屏幕：在「电脑」页开终端、打开本地端口（可全屏），或看电脑屏幕，并用触控板和键盘控制它。屏幕工具条上有快捷操作（复制、粘贴、切换应用、调度中心、截图、F 键，也可以添加自己的）和「发送文字」（写好一段再发，可以带上手机剪贴板）。支持 Apple 芯片和 Intel Mac，需要 macOS 13 及以上，独立 App 请按芯片选择下载，CLI helper 自动适配架构；两项权限由 linkshell setup 带你打开，单独设置用 linkshell screen。

远程桌面的画面与连接

网页和桌面工作台的「我的电脑」以统一大小的网格卡片展示电脑和实时 CPU、内存。八种监控样式混排，每台电脑记住自己的样式，也可单独更换；支持搜索和自定义名称。打开电脑后可切换显示器、调整清晰度和全屏观看，离线电脑仍保留卡片。负载数据需要 Host 0.4.83 或更新版本。

在手机上打开 Mac 桌面，可以切换显示器、横屏或全屏查看、双指缩放。触控板模式适合精确移动指针，「点哪点哪」适合直接点击；右键、滚动、拖拽和常用 Mac 快捷键都可使用，也能把手机上写好的长文字或剪贴板内容发送过去。完整控制支持 macOS 13 及以上，Linux 支持观看。

在「连接信息」中选择流畅 1280、标准 1920、高清 2560 或原生宽度（最高 3840，不超过源屏幕）。iOS 适配最高 120 Hz 显示，实际画质、帧率和延迟取决于两端设备、源显示器、网络、电量和温控。连接不佳时可能降低画质；需要重新建立连接时可点击重试。

切换显示器或清晰度会沿用已经建立的屏幕连接。在 App 或网页工作区内离开屏幕页时暂停采集，两分钟内返回可复用连接继续观看。进入后台、隐藏网页标签或断线后会释放连接，下次重新建立；旧版电脑端仍按原有方式重连。

稳定 120 fps、稳定 4K/60 和真机弱网效果仍待验证。完整技术链路、回退规则和已知问题见 远程桌面架构与链路图。

iPhone Duo 与自适应布局

从 App 2.3.7 起，LinkShell 支持 iPhone Duo 的可用区域和折叠信息。宽度足够时，打开「改动」或「预览」可以与对话并排；折叠区域会参与内容与操作区的布局计算。较窄的窗口与普通 iPhone 使用单栏布局。布局变化时保留会话和工具面板的状态。

Duo 布局已通过模拟器交互验证；实际显示取决于系统报告的尺寸和姿态。

在手机上用 Computer Use

在手机会话里告诉 Codex 你想做什么，让它操作电脑上的浏览器或桌面应用。操作画面会在浮窗中实时预览，你可以边看边补充要求，继续推进任务。

  • 边聊边看：小窗不随聊天滚动，可以拖到一边、点击放大，也可以收起成图标或关闭；关闭后在会话菜单点「显示电脑画面」恢复。
  • 回来接着看：回合结束后保留最后画面，重新进入会话会恢复预览状态。

目前支持 macOS 上的 Codex，需已配置兼容的 Computer Use 工具，并使用支持此功能的电脑端和手机 App。请在 Mac 上允许 LinkShell 录制屏幕，可运行 linkshell screen 完成设置。

命令一览

linkshell setup
首次设置：启动 LinkShell、打开屏幕的两项权限、连接手机
linkshell host [--daemon] [--gateway <url>]
启动 LinkShell；status、stop
linkshell pair
通过网关配对手机
linkshell devices
列出已配对的手机；remove 移除一台
linkshell screen
设置看屏幕和控制屏幕（macOS 的两项权限）
linkshell login / logout
Pro 账号（官方网关）
linkshell claude / codex
在终端里启动 Agent，可与手机共享
linkshell gateway [--port] [--daemon]
运行自己的网关；status、stop
linkshell doctor
检查环境和连接
linkshell upgrade
升级到最新版

常见问题

App 显示「电脑暂时连不上」

确认电脑没睡眠、linkshell host status 里网关是已连接，然后运行 linkshell doctor。连接恢复后 App 会自动重连。

Agent 显示「未登录」

在电脑终端里给那个 Agent 登录一次（claude 里的 /login、codex login、copilot login 等），LinkShell 用的就是那份登录。

从 1.x 升级

2.0 的 App 和电脑端协议都换了，需要两边一起升级，再重新配对一次。1.x 的 App 和 linkshell start 已不再支持。