---
title: 使用说明
nav: 使用说明
summary: 手机上每种颜色、每条线、每个按钮是什么意思；命令、附件、语音、快捷键、设置；审批卡、管理员密码卡、密钥卡；上下文过半了怎么办。
order: 14
---

# 使用说明

这页按手机屏幕上能看到的东西，一样一样讲。还没装好或者还没配对，先看 [安装](/docs/install/) 和 [手机上怎么用](/docs/phone/)。

不想看也没关系：直接问 Agent J「这个颜色是什么意思」「怎么发文件」。它读的就是这一份说明。

## 第一次使用：两个遥控器和第一条消息

装好以后，帮你安装的那个 Agent 会带你把这台电脑加进你的席位，然后配两个遥控器，这两个是必须的：

1. **这台电脑的浏览器**：在这台电脑上打开 m.agentj.app 配对，最快，也方便你在大屏幕上看清楚每一步。
2. **你的主力手机**：每天带在身边的那一台，先添加到主屏幕，再从主屏幕图标里扫码配对。

其他手机、平板、电脑不急。以后想用了，跟 Agent J 说一声「再配一台」，它会带你配。

所有遥控器都连着同一个 Agent，看到的是同一段对话：在手机上说了一半，回到电脑浏览器上接着说就行。遥控器是给你一个人的几台设备用的；同事要用，就各开一个席位，像公司里每人一张办公桌，见[席位、Agent 和主机](/docs/what/#desk)。几个人共用同一台电脑也行，每人一个席位，见[一台电脑多人使用](/docs/multi-seat/)。

第一个遥控器配好后，窗口里第一条消息是 Agent J 发的。它会介绍自己是你的董事长助理，是你和所有工作流、所有 Agent 之间唯一的入口，建议以后都在这个窗口里跟它说话。接着它会分几小步带你认识这个窗口：屏幕颜色、额度线和水位、语音和附件、审批卡，最后告诉你还差哪个遥控器没配。每一步你回一句「好」或「下一步」它再讲下一步；不想看了就说「跳过」。

这条欢迎消息只发一次。之后再配的设备，只会收到一句「这台也连上了」。两个必做的遥控器没配齐之前，Agent J 偶尔会在回复末尾提醒一句，配齐以后就不再提。在电脑上运行 `agentj onboarding`，也能看到还差哪一步。

## 背景颜色：Agent 现在在干什么

整个屏幕的颜色只说一件事：**你电脑上那个主 Agent 现在的状态**。它在后台调动的其他 Agent、定时任务，都不改这个颜色。

| 颜色 | 意思 | 你要做什么 |
|---|---|---|
| 绿色 | 等你下一句 | 想说就说 |
| 蓝色，顶上有一道光在跑 | 正在工作 | 等它；也可以接着发，消息会排队 |
| 橙色，边缘一明一暗 | 有一个操作等你批准 | 看卡片，批准或拒绝 |
| 紫色 | 有一个问题等你回答 | 选一个答案，或者取消后直接打字 |
| 灰色 | 没连上电脑、还不确定状态，或者已经「全部停下」 | 看顶上那行字 |

![绿色：等你下一句](idle.zh.webp)

![蓝色：正在工作](working.zh.webp)

![橙色：等你批准](approval.zh.webp)

![紫色：等你回答一个问题](question.zh.webp)

![灰色：电脑没连上](offline.zh.webp)

- 左上角的图标跟着状态变。点一下换字号（中 → 大 → 中 → 小），按住跳到第一条未读（没有未读时提示「没有未读」）。字号记在这台手机上，刷新后不变。
- 输入框空着时，按住灰色的发送按钮，会弹出「提示音音量」条，上滑变大、下滑变小，松手就定了。
- 顶上那行小字用文字再说一遍状态，比如「正在工作」「请你批准一个操作」。
- 状态一变，手机会轻轻震一下。

## 三条线：额度和上下文

- **顶上标题栏下面那条细线**（右边写着 weekly）：你 AI 账号的本周额度用了多少，越长用得越多。
- **输入框上方那条细线**：5 小时额度用了多少。
- **背景里慢慢升高、带波纹的水面**：这段对话占了多少上下文，也就是 Agent 一次能记住的内容。水越高，越接近装满。压缩以后，水面落回底部。

点一下顶上或输入框上方那条线（或者线旁边的数字），屏幕中间会弹出「用量」方框，列出具体的百分比，例如：周 58% · 5 小时 34% · 上下文 64%，还写着这些数字是多久以前报上来的。点「知道了」、点方框外面或按 Esc 就关掉。点一下顶上或输入框上方那条线，会弹出具体的百分比，比如：周 58% · 5 小时 34% · 上下文 64%。

本周额度后面的括号里写着现在是 7 天重置周期里的第几天。「用量」方框里还有一条「重置周期」，写着还有多久重置、几点重置；每一项下面一行小字说明按现在的速度到重置时大概用到多少。数字平时不发光：本周额度用得比平均速度（每天约 14%）快时，会微微发一点蓝光，方框里已用的那段变成浅蓝；任何一项用到 80% 以上发淡橙色的光，90% 以上发橙红色的光，说明余量紧张了。拿不到重置时间的服务商不显示第几天。

这两条额度线一直都在，也当作页面上下的分隔线。线旁边没有文字，就是这一项现在没有数据，通常是：①你的套餐本身没有这个窗口的限额（例如 ChatGPT Pro 200 美元档，OpenAI 只下发周窗口和点数余额，没有 5 小时窗口）；②服务商没有提供用量查询（例如火山方舟、阿里百炼的 Coding Plan，用量请到它们的控制台看）；③暂时拿不到数据。都不影响正常使用，换了模型或 AI 编程工具后一有数据就会自动显示。

![水位过半：背景里的水面已经升到一半以上](water-high.zh.webp)

### 水位过半了怎么办

上下文快满的时候，Agent 会开始忘掉最早的细节。水位过半后，Agent J 会在某次回复的最后提醒你一句（一段对话只提醒一次）。

1. 方便的时候说一句「压缩一下」，或者在 ≡「全部命令」里点 `/compact`，或者直接发 `/compact`。
2. **不用自己先做准备。** Agent J 收到压缩命令后，会先把正在做的事、已经定下的决定、待办和要用到的文件路径写进一份交接文件，写好了再压缩。
3. 压缩完，它先读这份交接文件，再接着干。

如果交接没写成，比如 Agent 卡住了，压缩照常进行。手机上会提示一行「交接没来得及写，已经直接压缩了。」

交接文件路径固定、可以在手机上直接复制：共享模式是 `~/.local/state/agentj/handoff/compact.md`，Agent J 自己的主对话是 `<工作目录>/.agentj/handover/compact.md`。压缩完如果你没再发消息，Agent J 会自己提醒 Agent 先读交接再接着干，手机上显示一行「压缩好了，我在翻交接笔记，马上接上思路」。详见文档里的压缩与交接一页。

输入 `/clear` 会开一段新对话。开之前先问你一声；在你发出下一条消息之前还能「撤销清空」。新对话一开始，按钮就换成一行「来不及撤销了：新对话已经开始，旧对话存在这台电脑上。」，旧对话仍存在电脑上。想保留进度时用 `/compact`，别用 `/clear`。开新对话、压缩完成这类状态提示会用你设定的称呼（默认「董事长」），想换就运行 `agentj config set owner.address 老板`。

## 心跳：Agent 自己醒来看一眼

空闲满一段时间（默认 60 分钟），Agent J 会叫醒电脑上的 Agent，看看后台任务和你的待办。一切正常，手机上什么都不会出现；有事要告诉你，会收到一页简短的消息，标着**心跳检查**。想改就说一句「以后每 30 分钟看一次」「每天早上 7:30 叫醒你看一眼」或「别再定时叫醒了」，也可以在设置 → 心跳里改：空闲多久醒来从下拉框选（30 分钟到 24 小时，或者自定义），还能打开「每天固定时间唤醒」。每次心跳都会用掉一次模型调用。详见文档里的心跳一页。

## 一条消息一页，左右滑着看

每一页上面是你说的话，下面是 Agent 的回复。往右滑看更早的，往左滑看更新的；右上角的 1 / 1 是第几页、一共几页。翻页要手指一按下就快速横划；按住不动超过三分之一秒再拖，就是在选字，不会翻页，拖选区两头的小柄也不会。回复很长往下滚时，顶上的名字、负载线和机器人一直固定在卡片顶部。

页头横着分成三等份。双击左边 1/3，回到第一条（最早的一条）；双击右边 1/3（页码），回到最新。中间 1/3 留给未读。你上次看完之后又来了回复，页头正中会出现一个闪烁的小圆标，里面是未读的条数。点它跳到第一条未读，再一张张往后翻，翻到最新，圆标就消失。没有未读时圆标不显示，点中间也没反应。在电脑上按 `u`，也是跳到第一条未读。未读在你自己的全部遥控器之间同步：任何一台看到某条回复，其他遥控器上这条及此前的未读提示也会消失；离线遥控器回来会先同步。升级后已有的回复都算已读，不会一打开就是 99+；哪台遥控器的已读没送到电脑，它会自己补发。只有一点例外：这台遥控器正停在旧页、新回复刚到，它自己还没翻到这条，那么就算另一台已经看过，这台的页码照样闪、圆标照样显示，翻到那条才消失。静默回合不算。

你翻到旧消息时，不管是自己发了一条，还是 Agent 来了新回复，页面都停在原来那一页、原来的位置，不会跳走；新回复只让右上角的页码闪动，你接着往后读就行。只有本来就停在最新一页时，发出去的消息才会翻到新的一页。

回复下面一排按钮，从左到右：

| 按钮 | 作用 |
|---|---|
| 书本 | 全屏阅读（双击回复也行），里面可以调字号 |
| 喇叭 | 朗读这一条，用手机自己的语音读，文字不发给别人 |
| 箭头 | 分享这一条，走手机自带的分享 |
| 两张纸 | 复制整条回复 |
| 弯箭头 | 回复这一条，引用会出现在输入框上方 |

在回复里选中一段文字，就会引用这一段来回复。再选别处会再加一段，不会覆盖，最多 5 段（可以来自不同的回复，翻页或全屏阅读里选都算），在输入框上方并排；点一段的文字看全文，点它的时间跳回原文并高亮，右上角 ✕ 删这一段，最右边 ✕ 或 Esc 全部清空。剪贴板里始终是最后一次选中的文字。

发出去的消息带了两段以上引用时，消息卡上的引用先折叠成一行：写着一共引用了几段、第一段的开头和还剩几段，跟发送前输入框上方的样子一致。点这一行展开全部引用，每段点一下仍能跳回原文；再点一次顶上那行就收起来。只引用一段时照旧直接显示。

回复卡左下角单独有一个白色圆形按钮（圆里一个带缺口的圈和斜出的箭头），是「分享成网页报告」：把对话里的结论做成一个好看的网页发给别人。点一下，输入框里会放好 `/web-page-report`，光标停在后面，不会自动发送。你可以接着补一句，比如「只分享定价那部分，给公司同事看，7 天有效」；也可以什么都不写直接发，Agent 会先问你：分享整段对话、某几个主题还是只这一条，谁能看（公开、访问码、只限公司邮箱、任意邮箱登录），多久有效，要不要隐去名字和数字。说清楚了它就不再问。在更早的一条回复上点，这一条会作为引用一起发过去，Agent 就知道从哪里开始。电脑上还没装网页报告技能时，Agent 会先问你要不要从广场装上。

按住这个圆形按钮不放，会从下面弹出「快捷技能键」：先写着它现在绑定的是什么、点一下会做什么，下面列出手机 `/` 菜单里的全部命令和技能（一键执行的命令、你自己的命令、Agent 的技能），可以搜索。它可以换成任何你常用的：选一个，再点「确认绑定」，以后这个按钮就是它，图标不变。绑定命令（比如 `/status`、`/compact`）后，点一下直接执行；`/clear` 这种会清空对话的，照旧先弹确认，不会因为是快捷键就跳过。绑定技能后，点一下会把这个技能放进输入框，你补一句再发，Agent 就对这条回复执行它。列表最上面的「恢复默认」换回分享成网页报告。也可以让 Agent 帮你改，或在电脑上运行 `agentj config set ui.card_hot_action status`。

回复卡左上角是你给 Agent 起的名字。按住名字不放，会弹出改名的方框，和在电脑上运行 `agentj name` 一样，手机和电脑上都会换成新名字。右上角有时会站着几个跳舞的像素小机器人：每个机器人是一个正在后台替你干活的 Agent，比如一个工作流 CEO，或者主 Agent 临时派出去的助理。来了新活就蹦出一个新的，干完的鞠个躬飘走。手机上最多并排 6 个，再多显示 +N。点一下机器人，屏幕中间弹出一个方框，写着有几个 Agent 在干活、谁在替你监控，并列出全部：每一行是它的机器人、是谁、在干什么（完整的任务标题，太长的在行尾用省略号）。点某一行，打开这个 Agent 自己的卡片：它在哪里干活、干了多久、最近一步做了什么，后台派单还有报告路径和报告第一行；卡片只用来看，点「返回」回到列表。Claude Code、Codex、OpenCode 派出去的子 Agent 都会这样显示。主 Agent 没在回复时也照样显示；后台明明在干活却没有机器人，说明那件活没登记，让 Agent 用 `agentj busy run` 包装后再跑。方框底下有个「换个样子」按钮：点一下，等于你亲自给 Agent 发了一条消息说想定制外观，它会先问你想把机器人、配色、logo 或发送按钮改成什么样，做好后先校验，通过了才换上。直接按住机器人不放也是一样。按 ESC 或点方框外面就关掉。机器人图鉴和显示规则见[后台小机器人](/docs/robots/)。

名字下面那条细灰线是负载线：一段亮色（浅色）在线上来回滑，滑得越快说明电脑越忙。快的时候，不急的话可以等一等再发。点一下这条线，屏幕中间会弹出说明，写着现在的综合负荷，下面分五行写 CPU、内存、GPU、硬盘、网络各用了多少：硬盘是读写有多忙和还剩多少空间，网络是现在每秒收发多少。没有显卡或读不到时写「—（未检测到）」。这五项只在方框开着时每 2–3 秒量一次，关掉就停，不给电脑添负担。最后是闲置、正常、很忙各是什么速度（大约 6 秒、3 秒、1 秒滑一趟）。和电脑断开时它不动。

Agent 回复里的内容会自动排好版：

- **代码**带颜色高亮，太宽可以左右滑；代码块右上角有复制按钮。文字里带底色的一小段命令（行内代码）点一下就复制，提示「已拷贝」，可以直接贴到终端里跑。
- **数学公式**（LaTeX）显示成公式。命令不会被当成公式：`$HOME`、`$(…)` 照原样显示；系统卡（比如目标结束报告）里不显示公式。
- **流程图**（mermaid）直接画成图。
- **它提到的图片、音频、视频、PDF、网页和其他文件**，只要在它的工作文件夹里，就直接显示在回复里：图片点开看大图，音频视频直接播放，网页在一个安全的预览框里打开（预览里不运行任何脚本）。每张文件卡片下面一排图标：预览、下载、分享、转发到邮箱、转发到 Telegram。小文件出现在屏幕上就自动加载，大文件点一下才加载（按钮上写着大小），开了省流量或用蜂窝网络时都不自动加载。点「预览」全屏查看：PDF、Word（docx）、Excel（xlsx）、CSV 表格、Markdown、代码和文本都能直接看；PPT 这类暂时看不了的，会提示你下载。电脑上选中卡片按空格键预览，再按空格或 Esc 关闭。预览打开时，左右方向键（手机上左右滑）切换这条回复里的上一个、下一个文件，顶部显示「第几个 / 共几个」；图片放大后单指拖动是移动图片，不会切走。点「下载」按文件原名保存（中文、空格、表情符号都没问题），屏幕上会提示「已交给浏览器下载」；iPhone 主屏幕上的 App 里，点「下载」会弹出分享面板，选「存储到文件」。
- 太大的文件、工作文件夹以外的文件不会发到手机上，回复里写一行原因。音频、视频、图片照常发，文件名是中文、带下划线或很长都没关系。凭据文件（比如 `.env`、`.pem`、私钥）和写着真实密钥的文本不会当普通文件发，而是在手机上弹出密钥领取卡，用 Face ID 领取；没弹卡时，那一行会写清原因和怎么拿到它。网上的图片链接不会自动打开。

![回复里的图片、公式和高亮的代码](rich.zh.webp)

![往下翻：流程图、可以下载的文件，和一行没有发出的说明](rich-more.zh.webp)

### 搜索聊天记录

右上角「设置」左边的放大镜（电脑上按 `⌘K` / `Ctrl+K`）打开搜索：在屏幕中间的深色卡片里输入关键词，会同时搜你发的话、引用、附件名和 Agent 的回复。空格隔开多个词，要全部出现才算；不分大小写、全角半角和繁简。

结果默认按相关度排：命中越多、出现在你发的话里、在开头或第一行、整句或完全一样的排在前面，最近的稍微靠前；也可以切到「按时间」。每条写着是谁发的、什么时候，以及命中的那一小段，命中的词会标出来。手机上已有的记录马上出结果，更早的、只在电脑上的记录稍后补上。

点一条结果，卡片关掉，直接翻到那一页，那一页会闪一下。再点放大镜，回到刚才的结果，停在原来的位置。每次搜索都留成一页（最多 20 页），在卡片里左右滑（电脑上按 `←` `→`，或点顶上的 `‹` `›`）切换之前的搜索，顶部写着「第 N/共 M 次搜索：关键词」。这些搜索只存在这台手机上，和草稿一样加密保存，清空会话（`/clear`）或解除配对时一起清掉。

在电脑上也能搜：`agentj history search 关键词`。

## 发消息

- 打字，点「发送」或按回车。Agent 还没收到之前，可以点「取消发送」撤回。
- Agent 正忙（蓝色）时也可以发，消息会排队，轮到了再交给它。
- **没网也能发。** 手机断网时照常发，消息先加密存在这台手机上，页面显示「网络恢复后自动发送」；网络一回来，按顺序自动发出，不会重复。电脑中途重启也不会把同一条执行两遍：重启前没办完的那条，手机上会标一句说明，需要的话您再手动发一次。

![没网时发的两条消息在输入框上方排队](offline-queue.zh.webp)
- 在输入框开头打 `/`，会弹出能用的命令。

### 接续 Codex App 会话

电脑上的 Codex App 打开会话时，手机会从本机记录显示它实际使用的模型，并提示当前只读。发送被原生写入权拒绝时，消息不会投递，也不会自动新开会话。完全退出 Codex App 后重发，可尝试接着同一会话；仅切到 New chat 或等一轮回答结束不保证释放写入权。不要承诺两个独立客户端能同时写这个会话，也不要删写锁、注入桌面私有管道或改权限。

手机提示有别的程序在用这个会话时，会说是谁：Agent J 自己上次留下的后台进程会自动清理，接着发；ChatGPT App 里的 Codex、Codex App 或终端里的 codex 要你先把它退出；实在查不到是谁，也会照实告诉你。

### Codex 的权限：默认直接跑在电脑上

接 Codex 时，只要你没在 `~/.codex/config.toml` 的最前面写过 `sandbox_mode`，Agent J 就让它像你在终端里一样直接干活：能联网、能装东西、能改你家目录里的文件。危险操作（花钱、删除、发送、密钥等）照样先到手机上等你批准。

- 你自己写了 `sandbox_mode`（比如 `workspace-write`），就照你的来；超出范围的操作会直接拒绝，提示里会告诉你怎么放开。
- `sandbox_mode` 要写在文件最前面（第一个 `[ ]` 之前）。追加在文件末尾，往往落进了最后一个 `[ ]` 表里，Codex 不认。手机上发 `/status`，或在电脑上跑 `agentj doctor`，会提示「写了但没生效」。让 Agent 改就行，它会用 `agentj codex-sandbox` 写对位置；改完重启 Agent J，同一段对话马上按新设置。
- 接续 Codex App 会话时，按这条对话在 Codex App 里的权限来；你没在 App 里选过（还是默认权限），就按上面的规则。因为权限被拒的话，去 Codex App 把这条对话的权限改成「完全访问」，再从手机重发。

## 附件：文件、图片、拍照

![附件和引用：输入框上方是待发的附件，再往上是你要回复的那一条](attach.zh.webp)

- 输入框上方三个按钮：「文件」「相册」「拍照」。也可以直接粘贴图片；在电脑浏览器里，把文件拖进来就行。
- 按住「文件」：把剪贴板里的文字贴到输入框光标处，超过 2000 字就变成一个 .txt 附件。按住「相册」：把剪贴板里的图片加成附件。iPhone 上可能会先弹一个「粘贴」小气泡，点一下就行。
- 一次最多 10 个附件，每个不超过 200 MB，任何类型的文件都行。录音和视频会在电脑上转成文字，原件一起交给 Agent。太长的一段文字粘进来，会自动变成附件。
- 附件加密后直接送到你的电脑，放在 Agent 的工作文件夹里，30 天后自动清掉。

## 语音：单击锁定，按住说、松开发送

![按住说话：正在录音](voice.zh.webp)

- 按住麦克风说话，松开后转写并直接发送；长录音作为附件直接发送。说一半想算了，手指明显滑出按钮（离开超过约 80 像素，或往上滑过一个按钮高）再松手就取消；手抖、轻轻挪一下不会取消，滑回来也能接着录。
- 单击或双击麦克风都锁定录音，松开手也一直录；锁定后等半秒再点一下结束，文字放进输入框，检查后发送。键盘 m 的按住转文字、双击锁定保持原样。
- 语音在**你自己的电脑上**转成文字，不经过我们。电脑上还没装语音模型时，用手机输入法自带的听写也行。
- 想让每条回复自动读出来：「设置」里打开「自动朗读」。

## ≡ 全部命令

![全部命令](commands.zh.webp)

输入框左边的 ≡ 打开「全部命令」，点一下就执行：

| 命令 | 作用 |
|---|---|
| `/compact` | 压缩上下文（会先自动写交接，见上文） |
| `/clear` | 开新对话，发下一条消息前可以撤销 |
| `/new` | 同 `/clear`（Codex 用户习惯的叫法） |
| `/model` | 看看能换哪些模型；`/model 名字` 直接换 |
| `/context` | 上下文用了多少 |
| `/cost` | 这段对话花了多少 |
| `/usage` | 套餐额度用了多少 |
| `/status` | 现在的状态 |
| `/stop` | 中断正在做的这一轮 |
| `/help` | 列出这些命令 |
| `/reset` | 重置连接：和 设置 →「紧急修复」→ ① 一样（见下文） |

「好友」组里有两个命令，点一下会填进输入框，你补完再发：

| 命令 | 作用 |
|---|---|
| `/my-agent-id` | 电脑直接回你的 Agent 号码（点一下代码块就能复制）、分享链接和「打开我的名片」按钮，不经过 AI，不花 tokens |
| `/add-friend 号码 [附言]` | 加好友，和好友页上的「加好友」一样由手机签名发出；号码抄错一位会当场提醒；不带号码就打开「加好友」 |

「一键执行」一组里换 AI 编程工具的命令（`/switch-harness`）点一下就发给主 Agent；也可以在输入框里打这条命令，后面补一句「切换到 Codex」再发。它不会马上切换，而是交给主 Agent：主 Agent 先说明要换的是哪种工具，扫描这台电脑装了哪些、用无头方式试一下各自的登录还能不能用，告诉你现在能切到哪些，你确认了才切。切换时手机会断开几秒再自动连上，新的工具会先自报家门；那边没起来，会自动切回原来的，并告诉你原因。详见 [换 AI 编程工具](/docs/switch-harness/)。
想加自己的命令？点列表里的 `/customize`（定制命令），或者直接按住 ≡ 不放：等于你给 Agent 发了一条消息说想定制 slash 命令，它会先列出现有的，再问你想加、删还是改哪一条，改好校验通过才生效。

切换前，现在这个工具会先把对话要点写进交接文件；新的工具接上后先读它，再接着干。没写成也照样切，手机上会说「这次没写成交接」。

菜单里还有「全部停下」和 Agent 自己的技能。改设置之类的其他命令，要回电脑上做。详见 [Agent 好友](/docs/friends/)。

顶上显示正在用的模型和思考强度，点一下换下一个，按住恢复默认。连着点只会改显示：某一半停手 5 秒不再点，才真正切换（等待时这一半会变淡，下方有条细线逐渐缩短）；点回原来的选项则什么都不发送。按住恢复默认、输入 `/model 名字` 都会立刻生效。

## 需要你出手的卡片

### 审批卡（橙色）

Agent 要做一件需要你点头的事时，屏幕变成橙色，下面升起一张卡片，写着它要做什么。

- 同意要**按住**「长按批准」，大约一秒，等按钮填满再松手；它在最前面，手机上在上面，电脑上在左边。不同意就点「拒绝」。按完卡片马上收起；没送到或已经超时，卡片会再弹出来说明。
- 长命令只显示两行，点「展开全部」看全部；标题右边的复制按钮复制完整命令。
- 在电脑浏览器里，按 `⌘↩`（Mac）或 `Ctrl↩`（Windows / Linux）等于长按批准，按 `Esc` 是收起。
- 2 分钟内没处理，就算拒绝。先不想管可以收起，卡片会缩成一个小标签，请求还在等你。你的遥控器全都不在线时，卡片会留 30 分钟，Agent 先做别的活，你批准后它再做这一步。
- 发邮件：发给你自己、或者收件人全在邮件白名单里，不弹卡片直接发。发给别人的卡片上，每个新收件人旁边有一个「以后发给 TA 不用再确认（加入白名单）」，默认不勾；勾上再长按批准，TA 就进了白名单——以后 TA 的来信直接处理，给 TA 发信也不再问你。

共享会话里，卡片标「查看密码或密钥」是要把凭据显示到屏幕上，标「改密码或密钥」是要改它；程序按名字读取 `.env`、笔记里提到 `.env`，都不会再弹。想更严，就在电脑上运行 `agentj config approvals strict`（`agentj config approvals standard` 改回来）。卡片只用你设置的语言显示。

只有真正危险的动作才弹卡：五类事要明确命中（`git push`、部署、付款或发消息的接口、删云上数据、写凭据文件）才问你；往普通文件写笔记（heredoc 正文里写了 deploy、密钥这些字也不算）、`--dry-run`、`list`、`status`、`systemctl --user` 起停自己的后台任务、`sleep` 轮询，都不弹。看不清的命令（程序名是 `$PY` 这样的变量），配好 Jev（电脑上的 `OPENROUTER_API_KEY`）后先问 Jev 是否与当前任务一致，概率不低于「设置」里的「Jev 判断阈值」（默认 0.70，0.50–0.95）就直接放行并记进「记录」；五类明确危险的动作不受阈值影响，一律弹卡。觉得弹窗太多，跟 Agent 说一声，它会解释并运行 `agentj config set approval.jev_threshold 0.6`（手机上弹一张确认卡）。

目标模式（`/goal`）：在 ≡ 菜单点 `/goal`，写上要做成什么、什么时候前做完。Agent 先发一张「开工授权卡」，列出目标、验收、截止时间和它要用到的危险动作（按类带上限，例如「推送到仓库 X」「花钱：只买一个域名」）；你批准一次，目标期内这些动作就不再弹卡，全部记进「记录」。范围外、电脑能撤回的动作（包括用 scp / rsync 往 `~/.ssh/config` 里起过名字的机器上传一个那边还没有的新文件）弹 10 秒倒计时卡，不点就算同意；撤不回的和疑似攻击的一律等你决定，结束时的结果卡会列出来。等你决定的卡用大白话写清谁想做什么、为什么没自动批准、不点会怎样（「已跳过这一步，其余照做」）、怎么批准，原始命令收在「详情」里。目标进行中，长按「批准，并加进目标授权」能把同类步骤一起放行（最多 20 次，目标结束就作废）；Agent 也可以用 `agentj goal grant` 再申请一项授权，只弹一张卡。`/goal status` 看进度，`/goal stop` 立刻收回授权；默认 8 小时到期。公司或团队可在「设置 → 安全」关掉「目标模式 10 秒自动批准」。

审批档位：「设置 → 安全」的「审批档位」有三档。「安全」多问几次，看不清的命令、批量批准、目标模式的倒计时都改成等你点；「中等」是默认，和以前一样；「全放行」像 Claude Code 的 `--dangerously-skip-permissions`，几乎不弹卡，全部记进「记录」，疑似被攻击（包括下载后直接运行）、动密码或密钥（包括把它们发出去）、花钱、改价仍然一条条问你。同一页还有「设了目标就不弹窗」（默认关）：打开后你自己发的 `/goal` 不弹总卡，直接开工，过程中也不弹卡，红线照样问你，结果卡照样出；要花钱或改价的目标照样先弹总卡；只认打开它的那台手机，关掉开关会结束没弹总卡就开始的目标。这两项只能在已配对的手机上签名切换（放宽时手机设了通行密钥的还要过 Face ID），Agent 自己改不了，电脑上直接改配置写成全放行也按「中等」处理；Agent 运行 `agentj config set approval.level …` 只会在你手机上弹一张确认卡。详见 [手机使用：审批档位](/docs/phone/#approval-level)。

遥控器都不在线时：卡片照常留在手机上，锁屏提醒照常发；接了 Telegram 或设好了邮箱，还会给你的 Telegram 私聊和自己的邮箱发一句不带内容的提醒（15 分钟最多一次）。20 秒后 Agent 知道你不在，先做别的活；卡片留 30 分钟，你批准后同一个请求方再做那一步就直接执行；点「全部停下」会作废没用掉的批准。详见 [遥控器都不在线时](/docs/phone/#no-remote-online)。

![收起以后：顶上留一个小标签，提醒还有一个操作等你](approval-later.zh.webp)

### 提问卡（紫色）

Agent 让你选一个答案：点选，再点「确认」。几个选项都不合适，就取消这个问题，直接打字回答。不管电脑上用的是 Claude Code、Codex、OpenCode、Kimi 还是 Qwen，Agent 都能弹这张卡（`agentj ask`），可以单选、多选，选项下面可能带一小段预览；选「其他（我在聊天框里写）」或开放题的「好，我在聊天框里回答」，就直接在输入框里打字回答。卡片没真弹出来时，Agent 不会说卡片已经弹出。

### 管理员密码卡

Agent 要用管理员身份执行一条命令（比如装一个系统软件）时，会弹出这张卡，先写它为了做什么，再写命令和会改动什么。你在卡片上输入电脑的管理员密码。密码加密后直接交给电脑执行这一条命令，**Agent 看不到你的密码**。

![管理员密码卡](sudo.zh.webp)

### 密钥卡

Agent 需要一个 API key 时，会弹出这张卡，写明要哪个 key、做什么用、存到哪里。把 key 贴进去，它会直接写进指定的位置，**不进聊天记录，Agent 也看不到**。

![密钥卡](secret.zh.webp)

没输内容就点「保存到电脑」或按回车，卡片会提示先把 key 贴进来，不会当成拒绝。「不提供」在下面单独一行，要连点两次才算拒绝。卡片 10 分钟内有效；Agent 那边的命令就算中途被打断，卡片也还在，你照常提交就会保存。

### 从手机领取自己的密钥或配置（密钥领取卡）

想把电脑上配好的东西拿到手机上用，比如代理的 SS 链接、带密码的配置文件，直接跟 Agent 说「把 SS 链接发我」就行。普通回复里的密码会被遮住，所以 Agent 会给你发一张**密钥领取卡**：

- 卡片先遮住内容，只写名字、用途、大小。点「用 Face ID 查看」，验证通过后电脑才把内容发过来。
- 文字可以点「复制」，文件可以点「下载文件」。看完点「完成」，内容就从页面清除，2 分钟后也会自动清除；聊天记录里只留一行「已领取」。
- 10 分钟内可以领，只能领一次；不需要就点「不要了」。
- 这台手机还没设 Face ID 的话，先点卡片上的「设置 Face ID」。
- 这张卡只发给你自己已配对的手机。Telegram、群聊、好友那边照样拿不到这些密钥。

### 开工卡（长程任务）

你说一句「做每周竞品简报」这类要长期跑的事，Agent 会先自查能力，再把真正要你决定的事放在**一张开工卡**上：这次要做什么、交付到哪里、多久运行一次、最多五个要你选的选项。点「确认并开始」就确认了任务书，需要的话也会同时启用定时；点「返回修改」就不开工。卡上不填密钥，确认也不等于同意付款、删除或对外发送，这些仍会逐条问你。详见 [长程任务](/docs/long-tasks/)。

详细说明见 [手机上完成管理员授权和密钥录入](/docs/phone-admin/)。

## 全部停下

在 ≡ 里点「全部停下」，再点「确定，全部停下」：正在做的事马上中断，等你批准的请求全部拒绝，批量授权收回，定时任务暂停。屏幕变成灰色，上方显示「已全部停下」，直到你点「恢复」。

![已全部停下](stopped.zh.webp)

## 设置

![设置](settings.zh.webp)

点右上角的齿轮打开「设置」，占满整个屏幕（电脑浏览器里按 `s`，或者 `⌘,` / `Ctrl+,`；按 Esc 关掉）。它是页面上唯一的菜单：「Agent 与遥控器」（Agent 的名字、「遥控器管理」、Face ID、「解除配对」），「紧急修复」（见下文），「Agent 的功能」（「模型和 API Key」、「记忆」——Agent 记住的规矩，可以删、「记录」——它最近做了什么、谁批准的、「定时任务」「好友」「Bots / 客服」「首次准备清单」），「语言」「外观」，「回复字号」「提示音音量」「自动朗读」「语音唤起」，「锁屏提醒」，「沟通渠道」里的重新绑定 Telegram、「邮件通道」「通讯录」（朋友的邮箱和电话，一键加进邮件白名单）「我的联系方式」，安全相关的「高风险提醒」「会话模式」「隔离运行」「允许使用 Docker」，网页版的「升级方式」「升级电脑上的 Agent J」、版本号、「更新并刷新」「添加到主屏幕」「键盘快捷键」，以及账号、帮助和安全、隐私、条款这些说明。改设置时手机要连着电脑。

「语言和外观」里的「输入框按钮顺序」：输入框上方的四个按钮（「文件」「相册」「拍照」和麦克风）可以换顺序，比如把麦克风放到最左边，左手拿手机时更方便说话。手机上先按住一个按钮一下，再左右拖；也可以先点一个，再点它要去的位置；电脑上直接用鼠标拖，或者选中后按 ← →。改完马上生效，并同步到你所有的遥控器；电脑上的 Agent J 版本太旧时，只保存在这台设备上。点「恢复默认」回到原来的顺序。也可以让 Agent 替你改：`agentj config set ui.composer_buttons '["mic","file","image","camera"]'`。

所有菜单——「设置」和它打开的各页、≡「全部命令」、键盘快捷键、静默记录、「这个网页版有多安全」——都是占满屏幕的深色页面，用同一套标题栏、图标和按钮。左上角的返回和 Esc 一样，回到上一级：从「设置」打开的页面回到「设置」。确认和危险操作仍然弹出居中的确认卡。

### 紧急修复

「设置」里第二项就是「紧急修复」。聊天卡住、离线、不回消息时用它，按顺序试：

- **① 重置连接**：先点这个。它会重新连接、找回原来的对话、必要时开一个新对话，最后一步是重启电脑上的 Agent J；哪一步连通了就停，每一步都显示出来。卡片变绿、显示「好了，可以回去聊天了」就修好了。开过新对话的话，原来的对话不会丢：在聊天里说「找回原来的对话」就行。≡ 里的 `/reset` 也是这一步。
- **② 请 Agent J Father 远程帮忙**：第 ① 步没用时再点。电脑先自己检查一遍，在电脑上去掉隐私信息，再把报告发给 Agent J Father，你会拿到一个工单号。客服只能建议固定的几种修复，电脑每做一步，卡片上都会显示。你不点，什么都不会发出去。
- **③ AI 账号登录失效**：Claude / Codex 登录过期时用，点进去就是「AI 登录救援」（见下一节）。

电脑上的 Agent J 不响应时，电脑上有个小小的救援守护会替它接手机：顶上显示「电脑上的 Agent J 没响应，救援守护在线」，① 和 ② 照样能用。离线提示卡上也有「紧急修复」按钮，还有一行给电脑旁边的人用的命令：`curl -fsSL https://agentj.app/rescue | sh`。详见 [手机显示灰色或断开怎么办](/docs/reconnect/)。

### 模型和 API Key

「设置」里的「模型和 API Key」最上面是选模型，下面分两块：「基座模型」按服务商一张虚线卡片，列出 Anthropic、OpenAI、火山方舟、阿里云百炼、Kimi、DeepSeek 等的 Key（标着订阅、按量或登录）；「第三方 API Key」列出电脑上的其他 Key（比如 ElevenLabs）。每行只显示名字和「未填」或打码（最多露最后 4 位），Key 本身永远不显示在页面上。右边是图标：拷贝、修改、删除；没填的只有「填写」，底部「添加」可以先起个名字再填。拷贝和删除要先过 Face ID，删除前还会再确认一次；拷贝时值直接进剪贴板。修改和填写打开的是普通密钥卡，Agent 看不到你填的值。每次拷贝、删除、修改都记进审计日志，只记名字，不记 Key。装好以后在这里把 Key 填好，就可以离开终端了。

### AI 登录救援和到期前续期

电脑上的 Claude Code 或 Codex 登录过期，Agent 就回不了话。打开 设置 →「紧急修复」→ ③「AI 账号登录失效」→「AI 登录救援」，在手机上重新登录就行，不用跑回电脑：Codex 会给你链接和设备码；Claude Code 给你授权链接，把授权码贴进密钥卡就好。

用 Claude 长期 token 时，Agent J 在换上它的那天记下日期，按一年推算到期日。这一节会写 Claude 登录还有几天到期。到期前第 7、3、1 天各提醒一次：聊天里一条提醒、一条推送，聊天顶部再出现一条红字横幅。点横幅（或这一节里的「现在续期」）→ 通行密钥确认 → 用手机浏览器打开授权链接、授权 → 把授权码贴进密钥卡。新 token 几秒钟实测通过就立刻换上，重新开始一年的倒计时；没通过就保留原来的，请你重新授权。授权链接 10 分钟有效，页面上有倒计时；过期或授权码没通过，电脑会自己换一个新链接（最多 3 轮）。授权链接只发到已配对的手机，不发 Telegram。

订阅 /login、Codex 的 ChatGPT 登录会自己续期，服务商密钥一般不过期，这些没有固定到期日。电脑每天对每个已登录的 AI 发一条不带工具的极短测试消息。登录失效（比如你在网页上退出了全部设备）就立刻提醒你去救援；只是余额不足或限流，不会让你重新登录。

## 遥控器管理

设置最下面有「下载 Agent J Brand Kit」：点一下会在新标签页打开官网的[官方 Brand Kit](/docs/robots/#brand-kit)，可以下载主 Logo 和 16 个机器人的透明 PNG（256、512、1024 三种尺寸，推荐 512），拿去做 Telegram、邮箱或其他 bot 的头像。

![遥控器管理](remotes.zh.webp)

「设置」→「遥控器管理」是单独的一页：上面是 10 台里已经用了几台；下面列出每一台手机或浏览器（在不在线、什么时候配对、最近什么时候用过、怎么加进来的，你手上这台标着「这台」），每一行都能「改名」「解绑」；「添加遥控器」会给出一个 5 分钟内有效、只能用一次的二维码和链接，新设备上会出现 6 位安全码，在这里输入后点「批准」（只能输一次）。

右上角的扫码图标（拍照按钮按住也一样）可以扫二维码：扫到新设备上的配对码，就是把它加为遥控器（两边显示同一个 6 位数，一致才点「一致，加为遥控器」）；扫到别的二维码，内容放进输入框，不会自动打开或发送。新设备不用找电脑：打开 m.agentj.app，最上面的码就是给已配对的手机扫的。「网页版」标签在「设置」→「这个网页版有多安全」里。

## 键盘快捷键

![键盘快捷键](keys.zh.webp)

在电脑浏览器或者接了键盘的平板上，按 `?` 打开快捷键表（「设置」里也有）；快捷键多了记不住，点表右上角的放大镜或按 `/` 搜关键词就行。每个点按、长按、滑动对应哪个键，全表见 [键盘快捷键和手势](/docs/shortcuts/)。常用的：

| 键 | 作用 |
|---|---|
| `Alt+Shift+J` · `j` · `←` | 上一条（更早） |
| `k` · `→` | 下一条（更新） |
| `Alt+Shift+G` · `g` | 跳到最新一条 |
| `G` | 跳到最早一条（更早的会从电脑上取） |
| `u` | 跳到第一条未读（所有遥控器同步已读），再一张张往后翻 |
| `o` · `↑` · `↓` | 展开 / 收起原话（↑ 展开，↓ 收起；没有可展开的时候 ↑ ↓ 在消息里滚一段） |
| `f` | 全屏阅读这条回复 |
| `Alt+Shift+Y` · `y` | 复制整条回复 |
| `Alt+Shift+A` · `r` | 回复这一条（引用条出现在输入框上方，焦点留在输入框，Esc 取消）；Alt+Shift+A 在输入框里也能用 |
| `Alt+Shift+O` · `s` · `⌘+,` / `Ctrl+,` | 打开设置 |
| `Alt+Shift+K` · `⌘+K` / `Ctrl+K` | 搜索聊天记录；设置页内搜索设置项（输入框里的 Ctrl+K 仍是删到行尾），再按一次关闭 |
| `i` · `Esc` | 进入输入框；在输入框里按 Esc 离开（输入的字保留） |
| `/` | 命令菜单：在输入框外按 / 直接进输入框，斜杠已经填好，命令菜单随即弹出；弹窗或设置开着时不抢 |
| `a` | 选文件发给 Agent |
| `p` | 从相册选图片 |
| `c` | 拍照 |
| 按住 `m` | 按住说话，松开直接发送（滑出取消）；键盘 m 松开仍转文字 |
| `Esc` `Esc` | 在输入框外按两下 Esc 清空文字和附件（✕ 只清文字，可以撤销）。Esc 从不打断 Agent；要停下当前任务，点停止按钮或发 /stop |
| `⌘+Enter` / `Ctrl+Enter` | 批准，等于长按批准走完（验证本人照常）；审批卡开着时优先给它，输入框里的发送让位 |

## 配对和 Face ID

![还没配对：扫电脑上的二维码](pair.zh.webp)

第一次配对：扫电脑上的二维码，再在电脑上输入手机显示的 6 位码和遥控器配对密码（见 [手机上怎么用](/docs/phone/)）。

![配对时手机显示 6 位码](pair-code.zh.webp)

### 扫不出来怎么办

- 让二维码占满画面中间的大半，手机拿稳，不要贴得太近（太近会对不上焦）。电脑屏幕调亮一点，避开反光。
- 扫了 10 秒还没反应，扫码画面上方会提示你换个办法：
  - 在浏览器标签页里：直接用手机自带的相机扫电脑上的二维码，它会打开配对页。
  - 在主屏幕图标打开的页面里：在电脑上运行 `agentj pair --link`，把打印出的链接发到这台手机，点「返回」，粘贴到配对页的输入框里。
- 这个链接就是配对密钥，5 分钟内有效，只能用一次，别发给别人。

**配对一次就够了。** 只要电脑没有解绑这台手机，以后打开就自动连上。iPhone 的 Safari 会清掉网页存的数据，从 0.17.4 起，网页会凭手机上的自动登录凭证（只有你的电脑认得，每用一次换新）悄悄连回同一台电脑，不用扫码，也不用验 Face ID。只有电脑解绑了这台手机（比如手机丢了），才需要重新扫码；这时配对页会说明自动登录已经失效。

配对成功后，手机会问你一次「用 Face ID 记住这台手机？」。点「保存」，系统会弹出 Face ID 确认。以后在这台手机的另一个地方打开 Agent J（从主屏幕打开、开一个新的无痕标签页、清过浏览器数据），配对页上会有「用 Face ID 连回电脑」：验一下 Face ID 就能直接用，**不用再扫码，也不用电脑批准**。电脑的设备列表里始终只算这一台手机。

- 不想用就点「以后再说」，照常扫码配对。
- Face ID 只证明「还是那台已经批准过的手机」，不会多给任何权限。在电脑上解绑这台手机后，它的 Face ID 记录也一起作废。
- iPhone 会通过 iCloud 钥匙串，把这个记录同步到你同一个 Apple ID 的其他苹果设备上。那些设备也能用 Face ID 连回来，但会顶替这台手机原来的位置，不会多占一个名额。
- 浏览器不支持 Face ID / 通行密钥（passkey）时，这个提示不会出现，照常扫码。

## 用一句话就行的事

Agent J 是你唯一要打交道的 Agent，很多事说一句就行，不用找按钮：

- 「接着昨天那件事」「上次那个报表做完了吗」：它会翻本机的历史记录，找到那件事接着做。
- 「重来」「换个说法」：它会换一种做法重做上一条。
- 「打开那个 xx 项目」：它会在你的工作目录里找到这个项目。
- 「压缩一下」：先写交接，再压缩。
- 「切换到 Codex」「切回 Claude Code」：换 AI 编程工具，先检查、能用才切，见 [换 AI 编程工具](/docs/switch-harness/)。
- 「我要反馈一个问题」：先问你想反馈什么；你给出内容后，它脱敏直发并告诉你编号。Agent 自己想反馈时先出稿请示。
- 「把我的名片发给老王」「老王最近说了什么」：管理 Agent 好友，见 [Agent 好友](/docs/friends/)。
- 做一件很长的事时，它会时不时用一句话告诉你进度。


- 「做每周竞品简报」这类长期要做的事：它会自查能力，只发一张开工卡让你确认，见 [长程任务](/docs/long-tasks/)。
- 「你会什么」：手机上弹出能力页，看哪些已就绪、哪些要配置。

静默回合不占聊天页。打开 ≡ → 查看静默记录，可只读查看原话；Esc 或点遮罩关闭，清空对话时同步清空。

## 从另一台电脑给席位添加遥控器

目标电脑安装完成、绑定账号且在线后，在账户页找到它的席位卡，点「添加遥控器」，确认是你本人后用手机扫码即可，不用去目标电脑的终端。确认方式二选一：通行密钥（这台电脑上没有的话，在弹窗里选「使用手机或平板」，用手机确认）；或者输入那台电脑的遥控器配对密码。用通行密钥确认后，同一会话十分钟内免重复确认；二维码五分钟内只可添加一台设备。待批准设备也可在席位卡查看、批准；席位卡「更多」里的「查看电脑上等你处理的事」只在两种时候用：电脑被「全部停下」后要恢复，或 Agent 新建的定时任务等你启用；它跟席位和付费无关，欠费也不会停掉电脑上的任务。

默认允许账户页添加；目标电脑的主人可用 `agentj remote-pair off` 关闭。离线时不排队，开机后重试；旧版本按提示运行 `agentj update apply` 或从已有手机升级。新设备来源显示「经账户页添加」，其他遥控器收到通知。

账户页配对依赖签名控制平面。配对材料只以浏览器临时公钥加密回传，后端不保存明文；签名服务被攻破仍可能增加设备，关闭开关可拒绝此路径。遥控器配对密码只在那台电脑上散列保存。在账户页输入它时，浏览器先用那台电脑临时给出的一次性公钥把它加密，只有那台电脑能解开、核对；我们的服务器只转发看不懂的密文，也不保存。连续输错 5 次，那台电脑会锁定一段时间。


Codex 报错时，先看手机上的操作提示。账号用不了当前模型时，点顶部模型名换一个；被拒绝的模型会暂时禁用，重新登录后刷新。连不上 ChatGPT 时，检查代理/VPN 后重发；登录失效时，在电脑上运行 `codex login`。原始报错经脱敏后保留在「详情」里。


### 共享 Codex 的模型与服务商（0.16.4a1）
手机发起回合时，主人配置的 `agent.model` / `agent.effort` 或手机最后一次明确选择会传给 Codex。没有手机明确选择时沿用会话自己的模型。电脑发起回合用电脑端最后一次明确选择；手机跟随实际模型，不抢改电脑的选择。顶部显示当前生效的模型；点默认后，下个手机回合使用当前 Codex 原生默认值。

手机接续已有会话时，从 Codex 读取当前生效的 `model_provider`，用协议的 `modelProvider` 切到当前服务商；不复制 key，不改写 Codex 配置。其他程序占用会话时手机只读，横幅按实际进程显示 App、终端或后台进程及可确认的 PID。退出对应程序后重发。

旧版一直沿用旧模型或旧服务商时，可在同一目录新开一个 Codex 会话，用当前默认模型与服务商，再让 Agent J 跟随新会话（如固定了旧会话，先取消固定）；也可切换独立会话。新会话的历史独立。不要让主人把 key 发进对话。


共享 Claude 在选择、启动和升级时，把工作目录里 Claude Code 实际生效的手机消息设置改成放行（组织策略 > 该目录私有的 `.claude/settings.local.json` > 该目录的 `.claude/settings.json` > `~/.claude/settings.json`），改前先备份，并在手机告知一次。用户设置或私有本地设置里的拦截就地修改；共享项目文件里的拦截从私有本地层覆盖。组织策略、`refuse` 和主人明确运行的 `agentj config claude-inbound off` 只报告、不改。已开启：手机消息不用在电脑上逐条确认；想关运行 `agentj config claude-inbound off`。改设置前就启动的会话需要 /clear 或开新会话。仅影响 Claude Code，Codex/OpenCode 无此机制。消息没被接收时，手机会说明具体原因（组织策略、项目设置、已关闭、需要 /clear、电脑正忙），重发前先检查电脑。手机的模型/额度条（`agentj config claude-statusline`）同时默认开启（主人关掉过就不开），串联在实际生效的状态栏那一层；被别的层遮住时 `agentj doctor` 会报告。

共享模式：Claude 的 `/clear`、`/compact` 等电脑当前回合结束后才执行，以原生回执确认。成功清空会归档手机旧页，新页从 0 开始；电脑直接 `/clear` 也一样。水位只读新会话/压缩后的实际数据，读数未到时显示「—」，不会把旧数当新数。超时会明确说没清成或尚未确认，先核实电脑，别重复发送。共享 Claude 不提供原生「撤销清空」按钮：旧历史仍在本机归档，恢复会话用电脑 `/resume`；独立模式仍可撤销。附加的 Codex 直接在手机上 `/clear`：下一条手机消息自动开一个新的 Codex 对话，手机旧页照常归档，发下一条之前都能点「撤销清空」；电脑上的 Codex App / 终端不会自动跟过去，新对话开好后手机会提示 `codex resume <id>`，在电脑上运行它就能接着聊。电脑上的 Codex 正在回答时不清空，等它说完再清；附加 OpenCode 的 `/compact` 可执行，清空需电脑 `/new` 后指定新 session id。Claude 自己启动的 PTY 可直接控制；既有终端需可定位到同一个会话的 Herdr 输入通道，否则提示具体原因和电脑命令。共享 `/context`、`/usage`、`/status`、`/model` 无参数读取实际数据；缺数显示「—」。

5h 线在 1% 时仍可见，0% 有起点标记；线旁边没有文字表示没有报告额度，不代表 0%。展开上方输入卡会压缩回复卡的阅读空间，底部操作按钮和输入区保持位置；长输入和长回复各自在卡内滚动。

## 共享会话

新安装默认用独立会话：Agent J 自己开一个，不动你终端里的工具。想让手机接入你电脑上正开着的那个会话，是可选的高级设置——「设置」→「会话模式」，或运行 `agentj config set agent.session_mode shared`（改回：`… independent`）。

进入或切换到共享的 Claude Code、Codex 或 OpenCode 会话时，手机会提示一次，3.5 秒后自动淡出。同一会话刷新或重连不重复提示；会话被占用、发送失败或需要你处理的提示会继续保留。

手机接的是哪个会话：默认是你工作文件夹里开着的那个 Claude Code 会话。那里同时开着好几个时，在电脑上运行 `agentj agent claude`，它会列出每个会话的名字和第一条消息，让你选一个。手机上不用做任何事。


配对页会提示浏览器和存储能力问题。请用 Safari / Chrome 普通窗口添加到主屏幕，并从同一个图标配对。菜单「设置 Face ID」在跳过邀请后仍保留；「复制网页链接」不包含一次性配对密钥。


## 分享截图

[安卓系统分享与 iPhone 剪贴板快捷指令](/docs/share-screenshot/)。分享内容先进入输入框，补一句话后再发送。

## 更新手机网页

电脑端与网页分别核对版本。其他情况发现网页有新版时，屏幕中间会弹出「服务器已升级」，点「刷新」就用上新版本；点「稍后」、按 ESC 或点方框外面先关掉，也可以之后点右上角设置图标 →「更新并刷新」。主机与网页服务器都已是同一新版时，网页等输入空闲十秒后自动刷新、保留草稿；录音和未提交卡片操作结束前不刷新。其他情况只提示。快捷键：`Alt+Shift+U` 升级主机（确认卡照旧）；`Alt+Shift+R` 更新并刷新网页。


周、月或日额度用完时，手机会提示等额度重置，或到模型服务商处升级套餐；真正的限流仍提示稍后重试。服务商的错误原文不会显示。

共享 Claude 回复在手机断线期间完成，重连后会补回已有输入页。刷新网页时先同步电脑上的最新历史，再显示是否还在等待接手。`/update` 的回执跟随当前设置里的语言；运行中切语言后无需重启电脑端。`agentj doctor` 会显示 websockets 版本，供排障使用。

网络短暂抖动会被悄悄修好：手机连接断开后一般一秒内就连回来，只有超过约 6 秒还没连上，页面才变灰并显示「连接断了，N 秒后重连…」。电脑忙、回应慢不算断线。Telegram 渠道连续三次（或两分钟）连不上 Telegram 时，对话下方会出现一行提示，恢复后自动消失。Agent J 刚启动的第一分钟里，`agentj doctor` 显示中继「正在连接」，不算故障。

本地朗读只使用这台手机的音色。云端/电脑音色保留在 `voice.tts.voice`，手机音色单独用 `voice.tts.phone_voice`（留空按回复语言选默认本地音色）。切换模式不会串用音色；指定本地音色不可用时自动回落并提示一次。iPhone 首次打开会等待本机语音加载，仍没有同语言本地语音时才提示不可用。


共享 Claude 入站：启动与 doctor 修正实际可写层为 accept；managed 只读报告。设置前启动的会话需新会话或 /clear 生效。共享模式再次启动会恢复开启，手机未确认接收前先核实电脑，别重复发送。


0.18.1：旧版已有效登记的 Telegram 沿用本机 bot 环境变量名。鸿蒙华为设备名称会正确识别；电脑在线时，主人可在账户页用通行密钥确认给遥控器改名。

给遥控器改名：长按输入消息卡左上角的来源（按住半秒），给你手上这台遥控器改名，别的遥控器和账户页马上显示新名字；别的遥控器只能由主人在账户页改名。主人改过名的遥控器，消息来源显示主人起的名字和设备类型（例如「张伟（老板）· iOS Safari」），名字后面注明「（主人改的名字）」，点一下能看到设备自己填的原名；没改过的注明「（名字是设备自己填的）」。Agent 按主人起的名字分辨是谁在说话，但这个名字只是标签，不是身份证明。双击左上角仍回到第一条。

## 第一条消息很慢、手机上没反应

新装的电脑上最常见四种原因，手机都会说明：连不上模型服务（Claude Code 自己重试约 3 分钟，重试约 10 秒仍不行时手机弹卡）；缺 bubblewrap（每次启动都会弹「沙箱不可用」卡，要用通行密钥点「本次不隔离运行」；在电脑上装 `sudo apt-get install -y bubblewrap socat` 就好）；用 root 运行又开了跳过权限（Claude Code 拒绝启动，Agent J 改用普通权限模式并提示）；模型不被支持（400，自动换成默认的 Opus 5.5 · medium 重发一次）。

`agentj agent claude`（或 codex）会预先完成工具的首次设置（引导、主题、信任工作目录、危险模式确认），只补缺的、不读 key；`agentj doctor` 的 `first-setup` 行检查。Agent 真停在终端的某个确认上时，手机会收到「在电脑上处理」卡，原样引用终端里的文字：去电脑上答掉，或运行 `agentj agent claude`，再重发。

## 沙箱失败与管理员命令

独立会话的沙箱起不来时，Agent 不会启动。手机卡片会说明原因（例如缺少 bubblewrap）和修复方法。点「本次不隔离运行」，再用主人的通行密钥验证，可只放行这次启动；下一次仍会检查沙箱。这次运行可能访问本机文件和凭据。没有设置通行密钥时，先在手机菜单中设置，未批准或超时都不会启动。

sudo 卡上的「为了做什么」和「会改动什么」标为「Agent 自述」，「为了做什么」排在最前面；写得太短、只是重复命令，或者想管理 Agent J 自己的后台服务，都不会弹卡。运行 shell 或解释器的命令会标红，必须输入管理员密码，即使已安装免密 helper。密钥卡只支持 URL 校验；`--verify-cmd` 已禁用，不会在沙箱外运行命令。定时任务和客服 bot 从原生登录存储认证，不继承主机服务的密钥环境。

### 接入 Telegram

Telegram 用的是你自己的 bot。先用密钥卡保存 bot 密钥，再在电脑上运行 `agentj channel add telegram`，或在「设置」里点「重新绑定 Telegram」。对话里会出现一个一次性的 6 位配对码（10 分钟内有效，只能用一次）。在 Telegram 私聊里给你的 bot 发 `/start 配对码`，这个私聊就成了主人，bot 会回一句「Telegram 接通了」。不需要找任何别的 bot 查 ID。别人给这个 bot 发消息，只会收到他自己的数字 ID；在群里发配对码不算数。换手机或换 Telegram 账号时，再点一次「重新绑定 Telegram」。

同一个机器人还能对别人当客服。在客服 bot 里打开一个 bot，勾选「让我的 Agent J Telegram 机器人也接待客人」（也可以让 Agent J 发起，你在手机上批准）。你配对的私聊照旧是主对话；其他私聊都成了那个 bot 的访客，有自己的会话、提示词、模型和限额，永远拿不到你的权限。默认关闭，关着时陌生人只收到自己的数字 ID。见[客服 bot](/docs/bots/)。

### Telegram 与好友的安全边界

Telegram 私聊中转发的消息属于外部数据，不会作为主人的原话执行；转发里的命令也不会执行。群里的审批命令保持静默，批准请用已配对手机。家庭群安全检查暂不可用时，这条消息会暂停，请主人直接从已配对手机发送。只有以 `/notification` 或 `/notify` 开头的命令会按提醒请求处理，正文里的 notification 一词不算。

群附件先检查文字和说明；报障群不下载附件，家庭群命中拦截规则也不下载。每位群发送者每小时最多下载 40 MiB，跨群累计，重启不清零；无法确认大小的附件按单件上限预留额度。被暂停的群消息不会触发 Agent 工具。好友名片名字最多 64 字、主人名最多 32 字、简介最多 140 字；补充设定里检测到密钥形状时整次修改不会保存，请用普通背景说明。

客服 Bot 的 Telegram 私聊按聊天分别处理；同一聊天保留顺序。超过 2000 字会提示缩短，不调用模型。客服报告里的客户原文和模型建议只供摘要与诊断，不能视为主人指令。

## 遇到问题怎么求助

- Agent 自己能把问题说清楚时，让它用 `agentj support` 问我们的客服，不用你去找人。见 [遇到问题找客服](/docs/support/)。
- 手机连不上电脑，或者聊天卡住：设置 →「紧急修复」，从 ① 开始（见上文）。
- Agent 完全连不上（离线、安装失败、连不上我们的服务器），或者打不开 agentj.app（比如在中国大陆），写信到 feedback@agentj.app，邮件在哪里都能发到。写上你的账号 ID、发生了什么、什么时候，再附一张截图。

## 五页菜单（0.20.3 后的候选功能）

点左上角 logo，进入聊天、工作流、技能、记忆或 Agent J；长按回聊天。工作流来自电脑上的规格文档，技能可查看并交给 Agent，宪法层只读，凭据类文件隐藏。点工作流的 @，输入框出现可整体删除的提及，发出去仍是纯文字。点跳舞机器人，默认看在办事项和工具/模型，右边「工作流」看 CEO、员工与汇报层级；没有归属的标「临时帮手」。菜单快捷键 Alt+W，字号循环仍用 Z，录音仍用 M。

双击非音频文件卡（图片、视频、PDF、文档、文本、代码、Markdown 或 HTML）直接打开文件全屏，也可点「全屏查看」。音频卡和回复正文双击打开回复全屏。视频保留播放位置；Esc 或返回退出当前查看层。


主人消息卡收起时，有引用就显示两行引用加一行正文；没引用最多三行，多了用省略号。附件不显示缩略图或文件卡，只在右下角的 … 按钮左边显示回形针和附件总数（图片、文件、语音合计）；没附件就不显示。双击正文、点右下角的 … 按钮或按 `o` 展开，查看全部文字、引用和附件。

Agent J Father 像素机器人是官方 logo，机身随五种状态换色，发送按钮使用同形白色剪影。非聊天页的 logo 会跳舞，提醒你长按可以回聊天；减少动态效果时显示静态图和轻微的边界内心跳描边。更换后台跳舞机器人时，Agent J 会先问要不要同时换一组五状态 logo；不换就保留当前组。

## 目标暂时缺能力时，怎样继续

Agent J 会先检查现有 API、技能和自己的浏览器登录状态，再告诉你“差什么、怎么补”，不会只说“做不到”就结束。路径依次是：

1. **官方 API。** 缺账号、授权或密钥时，一句话说清“您给我 X、Y，我就能做”，只列需要哪家的服务、去哪注册、大概费用。你同意后，它一步一步带你配置；密钥只填手机密钥卡，不发进对话或开工卡。服务费用需另行确认。
2. **没有 API 的网站。** Agent J 可以用自己的浏览器替你操作。它先检查浏览器是否装好和目标网站是否已登录；需要登录时会说“这家没有官方 API，我可以用浏览器替您操作，需要您在我的浏览器里登录一次 X 网站”，并启动登录流程。支持扫码的网站直接弹手机登录卡，二维码只走登录卡；其他网站在电脑上打开登录页，请你登录一次。检查不确定时会说明不确定，不把它当作已登录。登录不等于授权，发布、付款等操作仍需手机审批。
3. **本版缺少平台底层能力。** 它会说明缺口，提议用 /feedback-to-agentj-father 反馈给 Agent J Father，并说明能力解锁后还需你提供什么。它主动提议的反馈先给你看、获准再发；你明确发送带内容的 /feedback-to-agentj-father 时，脱敏后直接提交，不重复确认。提交成功不代表已经排期，也不承诺上线。两种缺口并存，就把两条路径都说清。

需要工作流的目标，把真正缺的选择、授权、配置汇总到一张开工卡（最多五个必须项），随后衔接密钥卡或登录卡；已有授权且能力齐的部分继续推进，只有依赖缺口的部分等待。真正违法或危险的请求仍会拒绝。

工作流页第一次打开、以及电脑上的 Agent J 启动时，会扫一遍工作根目录下一层的文件夹：按工作流设计方法整理过的（有入口文件和 documentation/ 开工文档）直接出卡片；还没登记进 CEO 花名册（documentation/ROLES.md）的，在花名册末尾补一行，只追加、不改原有内容，你删掉的行不会再被加回来。一个工作流都没找到时，显示 Agent J 自带的三个（知识库、脚本与文章、电子书），点「装上它」让 Agent J 先给你看预览再装。页面上的「初始化组织结构」会给 Agent J 发一条标准指令：按工作流设计方法整理在用的项目、登记 CEO、自检，没整理过的项目先列给你确认；不删、不搬文件。用过一次后按钮变成「复查组织结构」，再点就是查缺补漏。

工作流卡片展开后，CEO 下面列的是它的员工：只算 `.claude/agents/` 里写了 name 的员工文件（Codex 那边是 `.codex/agents/` 的 .toml），README 之类的说明文件不算；员工文件里写了 title（比如 title: 文案员）就显示这个名字。一个 CEO 还没有员工时，卡片上会出现一行小字「只有 CEO，还没有员工」，「复查组织结构」按钮也会带上数量，比如「复查组织结构（2 家只有 CEO）」。点它，Agent J 会读这家公司最近的报告、task.json 和 RUN.md，先给你列 3–7 个员工方案，你同意后才写进去（Codex 用的那份一起生成），不覆盖你改过的员工文件。派活给只有 CEO 的公司时，Agent J 也会顺带提一句，每家只提一次。

## 全屏阅读翻页与文件转发

全屏阅读时，从文字区向右快速滑动看上一条更早的回复，向左看下一条更新的回复；桌面用 ← / →。到头会轻微回弹。上下滚动、长按选字、表格和代码横向滚动、文件按钮和屏幕边缘返回保留原动作。

文件卡的纸飞机把原文件作为文档发到主人 Telegram：点击后立刻显示「发送中…」，完成后保留「已发到 Telegram」或失败原因。未配置时提示先配置；超时结果未知时先检查 Telegram，避免重复发送。密钥类文件继续禁止转发。

## 全屏阅读：页眉页脚固定，适合长时间看

全屏阅读的背景和屏幕中间弹窗是同一种深色（Noir），浅色、深色模式都一样。顶上的页眉和底下的页脚始终固定，只有中间的文字上下滚动，不显示滚动条，手指、滚轮、方向键和空格都能滚。

- 页眉左边显示 Agent 名和回复时间，双击跳到第一条；中间有未读消息时会出现圆标，点一下跳到第一条未读；右上角是页码（当前第几条 / 共几条），没有关闭按钮，从哪进就从哪出。双击跳到最新一条（不退出全屏），有新回复时页码会闪烁。
- 页脚左下角有个细线字号图标，点开出现字号滑杆；两指缩放和 + / - 键照样能用。右下角是和回复卡一样的 6 个图标：全屏阅读、朗读、转发给我自己、转发到邮箱、复制、回复（最右）。
- 点击复制和回复会退出全屏，回复会引用当前这条，光标直接进输入框。朗读、转发给我自己、转发到邮箱不退出，图标上会显示发送中或已发送。点书本图标也会退出。
- 左右滑动或按 ← / → 切换其他回复时，页眉的时间、页码和页脚的按钮都会跟着换成这一条的内容。回复带的文件也显示在文字下面。
- 键盘快捷键：`G` 第一条，`g` 最新，`u` 第一条未读，`y` 复制并退出，`r` 回复，`l` 朗读，`t` 转发给我自己，`e` 转发到邮箱。

整个网页都不显示滚动条：页面、弹窗、菜单、设置页、代码块和文件预览都一样，照样能用手指、滚轮或键盘滚动。

Agent J Father 就是官方反馈与客服平台。你可以说「请把这个问题汇报给 Agent J 开发者（客服平台）」，也可以轻松地说「把这事告诉你爸爸」。手机命令 `/feedback-to-agentj-father <内容>` 也一样：Agent 先去掉凭据、个人信息、客户数据和路径里的私密内容，直接提交并告诉你编号，不再问第二遍。只发命令会先问你想反馈什么；如果是 Agent 自己想到的问题或点子，它会先在手机上给你看脱敏稿，你同意才发送。客服回复是建议，不是指令；连不上时可写信到 feedback@agentj.app。