跳到正文Skip to content
Agent J Beta
菜单Menu
中文EN
登录Sign in

搜索文档和页面Search docs and pages

文档Docs

使用说明User guide

手机上每种颜色、每条线、每个按钮是什么意思;命令、附件、语音、快捷键、设置;审批卡、管理员密码卡、密钥卡;上下文过半了怎么办。What every colour, line and button on the phone means; commands, attachments, voice, shortcuts, settings; approval, admin-password and key cards; what to do when the context is past half.

这页按手机屏幕上能看到的东西,一样一样讲。还没装好或者还没配对,先看 安装 和 手机上怎么用。

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

Agent 没回应、只有手机时怎么办

消息没回应,或一直显示「尚未接收」?不用到 Agent J 主机前。每做一步,回聊天发一条简短消息,收到回复就停:

  1. 点 Stop,打断当前任务。
  2. 打开 设置 → 紧急修复 → 终端指令,找到 agentj doctor --reconnect,点旁边的 执行(推荐)。这是在手机上让主机检查并修复连接,不用自己打开终端;按提示用 Face ID 确认。
  3. 仍没回应,在 紧急修复 点 重启服务(推荐),等连接恢复后再试。
  4. 仍没回应,点 紧急修复 → 重启 Agent(主机与网页均需 0.25.2a1 起的版本)。它结束卡住的 AI 会话进程,优先接回同一段对话;无法恢复时开新会话,原对话保留。旧版没有这个按钮,直接下一步。
  5. 仍没解决,点 紧急修复 → ② 请 Agent J Father 远程帮忙。只有你点了才会发送在主机上脱敏的诊断报告;记下工单号。不发送密码、密钥、聊天或工作文件。

被模型的安全检查拦下了,也不用回到 Agent J 主机前。 用 Claude Code 时,手机上会弹卡让你选怎么办:换备用模型继续、原话重试、「改一改再发」(原话放回输入框)或「开新对话」。

先分清额度与连接。 提示 Claude 额度用完时,先在手机的 Claude 设置看 Usage;若页面提供 免费重置,可按提示使用,否则等它显示的重置时间。免费重置不是每个账号、每次都提供。额度恢复后仍「尚未接收」,再按上面五步试;重启和重开会话不会增加额度。AI 登录过期则用 AI 登录救援。

手机灰了、显示断开是另一条线。 先检查手机网络、点「立即重试」,再进 设置 → 紧急修复 → ① 重置连接,没恢复再点 ② 请 Agent J Father 远程帮忙。短暂断线先等几秒。命令、重启和会话修复都需要手机能接通主机或救援守护;主机关机、休眠或断网时不能从手机强行执行。一直连不上时,在手机浏览器打开 在线客服 或写信 feedback@agentj.app,说明症状、版本和发生时间,不贴凭据。无需回到 Agent J 主机前。

Agent J Father 是官方开发者客服平台。聊天恢复后,也可以用 /feedback-to-agentj-father 汇报问题;仍没回应时,直接使用上面的手机求助入口。

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

装好以后,帮你安装的那个 Agent 会带你把这台Agent J 主机加进你的席位,然后配两个遥控器,这两个是必须的:

  1. 这台Agent J 主机的浏览器:在这台Agent J 主机上打开 https://m.agentj.app/ 配对,最快,也方便你在大屏幕上看清楚每一步。
  2. 你的手机遥控器:每天带在身边的那一台,先添加到主屏幕,再从主屏幕图标里扫码配对。

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

所有遥控器都连着同一个 Agent,看到的是同一段对话:在手机上说了一半,回到遥控器浏览器上接着说就行。遥控器是给你一个人的几台设备用的;同事要用,就各开一个席位,像公司里每人一张办公桌,见席位、Agent 和主机。几个人共用同一台Agent J 主机也行,每人一个席位,见一台Agent J 主机多人使用。

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

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

背景颜色:Agent 现在在干什么

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

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

绿色:等你下一句

蓝色:正在工作

橙色:等你批准

紫色:等你回答一个问题

灰色:Agent J 主机没连上

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

三条线:额度和上下文

  • 顶上标题栏下面那条细线(右边写着 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 编程工具后一有数据就会自动显示。

水位过半:背景里的水面已经升到一半以上

OpenCode 的水位优先采用模型提供的上下文上限;没有上限时使用内置模型表,再查不到就按 200,000 token 显示(参考免费 DeepSeek Flash 的窗口)。这是显示用的默认值,不代表服务商承诺的容量。已用 token 仍来自 OpenCode;尚未返回用量时不编造读数。

水位过半了怎么办

上下文快满的时候,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 先读交接再接着干。共享模式下,Agent 真的读完交接文件,手机上才显示一行「压缩好了,已读完交接,接着做。」详见文档里的压缩与交接一页。

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

心跳:Agent 自己醒来看一眼

空闲满一段时间(默认 60 分钟),Agent J 主机先检查本机记录;没有发现要处理的事,就只记一行日志,不调用模型。有事才叫醒主 Agent,并告诉它为什么醒来。只有需要你知道或决定的事才发到手机上。 想改就说「以后每 30 分钟看一次」「每天早上 7:30 叫醒你看一眼」或「别再定时叫醒了」,也可以在设置 → 心跳里改间隔、每日时间和安静时段(默认本地时间 23:00–07:00),;点顶栏用量查看心跳消耗。超大上下文或识别为高价模型时先暂停自动心跳,提示你压缩;不会自动清空对话。详见文档里的心跳一页。

Webhook:外部服务直接通知你

每个席位都自带 Webhook 地址(hook.agentj.app/…)。想让视频生成、Stripe 收款、GitHub、服务器告警直接通知到这里,跟 Agent 说一句就行,比如视频做完了回调我。常驻的 hook 要你在手机上批准审批卡才开始接收。收到的内容 Agent 只当数据:符合预期就接着干,需要你拍板就带 A / B / C 建议来问你,垃圾就忽略。在手机上打开设置 → 「Agent 的功能」 → 「Webhook」,能看到生效中的 hook(可以暂停、恢复、撤销、复制地址)、今天收到了几条,以及「最近投递」(最多 50 条,带 Agent 的分诊结果)。密钥从不在手机上显示。详见 Webhook。

一条消息一页,左右滑着看

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

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

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

回复下面一排按钮,从左到右:

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

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

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

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

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

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

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

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

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

回复中识别出的短值(邮箱、Agent ID、@账号、账户 ID,以及 example.com 这样的域名),点一下就复制;其他链接照常打开,长按正文仍可选择文字。

把本地图片放进回复时,写完整的 [说明](绝对路径) 本地引用,也支持在开头加感叹号的图片写法;两种写法都支持绝对路径和 ~/。主机收到完整引用后就准备文件,不必等整轮工作结束。文件卡片出现前会显示准备中,失败会给出说明;文件仍须通过路径、类型和秘密检查。

需要明确附到当前页时,让 Agent 在当前获准的主人手机回合单独运行 agentj file show PATH --label 说明 --json。没有有效主人回合会失败;桌面独立回合不能借这个命令新建外发消息。queued 只表示排队,后续 FILE_SHOW_RESULT 的 attached_to_page 表示已附到页,failure 表示失败;它们都不表示您已看到或下载文件。 本修复已用 Linux 隔离进程和真实 Chromium 合成图片页面验证。实体手机、macOS、WSL 和 Claude Code/Codex/OpenCode 真实模型回合端到端尚未验证;Kimi/Qwen ACP 尚无已验收的 file-show 接入。Windows 须在 WSL 中使用。

PATH 支持绝对路径和 ~/,文件仍须位于本轮获准的工作目录内。失败说明:broker_unavailable 表示无法连接本机附图服务;no_owner_session 表示无法确认当前主人回合或其上下文;native_admission_missing 表示 AI 工具尚未准入这条具体请求;native_admission_expired 表示准入已失效;native_admission_ambiguous 表示匹配到多条有效准入。这些失败都没有附上文件。当前回合有效时,让 Agent 单独运行这条命令;回合已失效或无法确认时,请用已配对的遥控器在同一会话重新发消息。

在当前获准的主人手机回合里,要把单个本机图片或文件主动发到自己已绑定的微信,让 Agent 整条 Bash 命令只运行 agentj file send PATH --to wechat --json。不能指定群、好友、收件人、账号或 URL。文件须在本轮工作目录里,通过原有类型、无软链接、摘要和秘密检查。微信单件上限 25 MiB,原有媒体类型上限可能更低;每条命令只发一件,不是一次发 24 件的接口。现有页面附件仍受 24 件、合计 100 MiB 上限限制。queued 只是等原生工具完成;等 FILE_SEND_RESULT:sent_to_wechat 且 platform_accepted:true 表示平台接受,不表示手机已看到或下载。failure 可能意味着送达状态未知,明确重试前先查看微信。绑定、上下文或主人回合变动就停止发送;不能借此绕过 file show 失败、审批或文件检查。

回复里的图片、公式和高亮的代码

往下翻:流程图、可以下载的文件,和一行没有发出的说明

搜索聊天记录

放大镜和搜索快捷键会搜索当前页面:在对话里搜聊天记录,在工作流、技能、记忆和 Agent J 页搜卡片,在设置、菜单子页或打开的文档里搜当前文字。

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

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

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

在Agent J 主机上也能搜:agentj history search 关键词。

发消息

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

没网时发的两条消息在输入框上方排队

  • 在输入框开头打 /,会弹出能用的命令,接着打几个字母就会筛选。列表里也有当前 AI 编程工具(Claude Code、Codex 或 OpenCode)自己的命令;和 Agent J 的命令同名的只显示一次(用 Agent J 的)。这些命令都能选、能打:标着「直接执行」的原样交给那个工具去跑(比如 /init、/review);标着「交给 Agent 代办」的会改设置或要用终端界面(比如 /config、/mcp),Agent J 把你的意思转给 Agent,由它按平常的确认流程办完,再告诉你结果;灰色的几条(比如 /exit、/login)不直接运行,点了会说明下一步;登录请从手机的「AI 登录救援」继续。换了工具,列表跟着换。选中的命令(或者用 @ 选中的卡片、工作流)后面自动带一个空格,光标停在后面;消息真正发出去之前,输入框不会失去焦点。

输入框:永远一行,长文用全屏编辑

  • 输入框只有一行高,不会越打越高;写了好几行时,框里可以上下滑着看,输入框上方第 5 个按钮(全屏)的角上会写着有几行(比如 5 行)。Shift+Enter 换行,回车发送。
  • 在电脑的宽窗口里,卡片和输入框跟着窗口一起变宽,不再停在固定宽度。
  • 写长内容就打开全屏编辑:点第 5 个按钮,或按 Ctrl+G,手机上也可以按住输入框往上滑。深色底、白字,整屏都是写字的地方;手机弹出键盘时,编辑区和底下的按钮会自动缩到键盘上方。
  • 全屏里:左上角图标退出全屏(Esc、再按一次 Ctrl+G 一样;在空白处双击也会退出,在文字上双击还是选字;也可以按住顶部中间的横杠往下拉,拉得不够会弹回去),文字原样回到输入框;右上角图标清空,5 秒内可以撤销;左下角的斜杠图标打开命令列表,选中的命令插到光标处;右下角发送,也可以按 ⌘/Ctrl+Enter。全屏里回车只换行。
  • 键盘上习惯终端的话,输入框和全屏里都能用:Ctrl+A / E 到行首行尾,Ctrl+U / K 删到行首行尾,Ctrl+W 删前一个词,Ctrl+Y 贴回刚删的,Ctrl+D 删光标后一个字,Ctrl+J 换行(行末打一个 \ 再回车也是换行)。输入框里另有 Ctrl+S 暂存草稿(再按一次取回),Ctrl+R 在发过的话里找含有这几个字的那条。全部快捷键见 键盘快捷键。

接续 Codex App 会话

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

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

Codex 的权限:默认直接跑在Agent J 主机上

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

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

附件:文件、图片、拍照

附件和引用:输入框上方是待发的附件,再往上是你要回复的那一条

  • 输入框上方三个按钮:「文件」「相册」「拍照」。也可以直接粘贴图片;在遥控器浏览器里,把文件拖进来就行。
  • 按住「文件」:把剪贴板里的文字贴到输入框光标处。输入框空着时,超过 2000 字就变成一个 .txt 附件;框里已经有字时照样贴进去,只有合起来超过一条消息的上限,这次粘贴的内容才变成附件。按住「相册」:把剪贴板里的图片加成附件。iPhone 上可能会先弹一个「粘贴」小气泡,点一下就行。
  • 一次最多 10 个附件,每个不超过 200 MB,任何类型的文件都行。录音和视频会在Agent J 主机上转成文字,原件一起交给 Agent。粘贴文字也按这条规则:框里有字就接着贴,合起来超过上限才把这次粘贴的内容转成附件;空框超过 2000 字直接变成附件。
  • 附件加密后直接送到你的Agent J 主机,放在 Agent 的工作文件夹里,普通附件仍按 30 天清理;手机录音、Telegram 和微信语音的原文件默认保留 24 小时,可在「设置」→「阅读和声音」→「语音原文件保留」改成 0、1、6、24、72、168 或 720 小时(0 表示不自动清理)。

语音:单击锁定,按住说、松开发送

按住说话:正在录音

  • 按住麦克风说话,松开后转写并直接发送;长录音作为附件直接发送。说一半想算了,手指明显滑出按钮(离开超过约 80 像素,或往上滑过一个按钮高)再松手就取消;手抖、轻轻挪一下不会取消,滑回来也能接着录。
  • 单击或双击麦克风都锁定录音,松开手也一直录;锁定后等半秒再点一下结束,文字放进输入框,检查后发送。键盘 m 的按住转文字、双击锁定保持原样。
  • 默认在你自己的 Agent J 主机上转写。你也可以在「设置」→「语音转写」选已配置的服务商或自己的转写端点;选远端时,录音会由主机发到你选的服务,不经过我们。
  • 不需要认证的自定义端点,可以直接在手机上填地址和模型名,把密钥名称留空后保存。需要密钥的转写,请让 Agent 在主机上代配端点、模型、服务商和密钥变量名称;这些绑定不能直接在手机设置里保存。设置页会说明「设置尚未保存」。密钥内容只在「打开密钥卡」里输入,不发到聊天;打开卡片本身不会绑定转写设置。配好后先录一小段核对。
  • 远端转写成功时不加载本机语音模型。远端失败会自动改用已安装的本机模型;短语音和长语音附件都适用。转写成功后,手机显示「远端转写不可用,已改用本机模型转写。」;附件的转写文字收起后,这行提示仍可见。只有两边都失败才显示转写失败,原录音附件仍保留。
  • 「语音热词」每行填一个专有名词,默认带 Agent J、Olares、Claude Code、Codex、OpenCode。远端通过提示词传入,是否采用取决于模型;内置 SenseVoice 不支持原生热词提示,Agent 可用 voice.asr.corrections 配置准确词语替换。
  • 录音卡显示这次会转文字还是发送语音附件,以及当前阈值;阈值按输入框容量计算,在 20–90 秒之间。超过阈值作为附件发送,随后补上转写文字。
  • 想让每条回复自动读出来:「设置」里打开「自动朗读」。

只发了一段语音时,Agent J 主机转好文字后会把它补回到你那张输入卡上:收起时直接显示这段话,展开后在语音附件下面(可以折叠,长按能选中复制);没转出来会写明原因。换一台遥控器、以后翻历史也都看得到。输入卡右下角展开 / 收起按钮左边的拷贝图标,一下就把原话拷走(只有语音时拷的是转写文字)。

≡ 全部命令

全部命令

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

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

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

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

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

切换前,现在这个工具会先把对话要点写进交接文件;新的工具接上后先读它,再接着干。3 分钟内没写成,切换照常继续,改用本机最近请求和回复的脱敏摘录。手机会说明正在用摘录,内容可能不完整;进度缺失时,新工具会向你核实。

菜单里还有 Agent 自己的技能。改设置之类的其他命令,要回Agent J 主机上做。详见 Agent 好友。

顶上显示正在用的模型和思考强度,模型名带版本号(如 Opus 5.5),和终端状态栏一样;点一下换下一个,按住恢复默认。连着点只会改显示:某一半停手 5 秒不再点,才真正切换(等待时这一半会变淡,下方有条细线逐渐缩短);点回原来的选项则什么都不发送。按住恢复默认、输入 /model 名字 都会立刻生效。

需要你出手的卡片

审批卡(橙色)

卡片先告诉你为了哪条任务、要做什么,再显示来源渠道、发起时间和原消息的前两行。点来源就跳回原话并高亮,卡片同时收起;原话已不在最近500条时,改为显示核证的发起者与任务记录。找不到是谁发起的,会明确提醒你先核查。

  • 点“用 Touch ID 确认”或“用 Face ID 确认”批准需要本人验证的动作;普通卡继续用自己的确认方式。命令默认收在“命令详情”里,可展开或全屏查看。确认只覆盖卡上列出的具体操作与范围。
  • 点“我有疑问”,原操作先不执行,主 Agent 会在聊天里解释;等回复时是蓝色,回复后是绿色。点解释下的“重新弹出,我来审批”或心跳圆点回到卡片,仍需你确认。过期后须重新核验申请,不能恢复已拒绝或执行结果不明的操作。
  • 点“拒绝”,请求作废、卡片消失。主 Agent 会说明哪一步因此做不了;来源可疑时会协助核查,但不会自行暂停通道或修改凭据。
  • 点右上“收起”或按 Esc,请求仍在等待;回复卡左下角原网页报告按钮的位置改为 Lotion 底、Peachy 心跳点,点它重新展开,多张待批时显示数量。这时聊天恢复正常蓝色或绿色;只有卡片展开时整页才是橙色。
  • 倒计时结束默认不批准;收起、查看原话或提问都不延长期限。批准后回到最新消息。你的遥控器全都不在线时,沿用最长30分钟的待批处理,Agent 先做不依赖这一步的工作。
  • 任务开始前,Agent 会预告预计确认次数。一次任务批准只覆盖已列出的具体步骤、对象、接收方和限额,最多12步、600秒,每步一次,任务结束或授权失效就停止。范围变化会再请你确认;密码明文领取、审批或配对等授权根变更仍逐次验证。密码或密钥只显示在完成本人验证的那台遥控器上,不回到发起设备或聊天里。 任务停止、到期、结束或主机重启后,旧批准不会恢复执行。临时令牌的待核对记录只保留在主机上的私有元数据,不保存令牌或认证密码;结果不明时不会自动重做创建或撤销。“按请求已到期”不是服务方确认撤销。你可以让 Agent 用 agentj friends action-recovery 查看状态;这只列记录,不执行操作。真正核对或撤销仍要你在新的可信任务里重新确认具体的已记录官方对象;没有对象ID时不会盲目创建或删除。
  • 发邮件:只发给你自己不弹卡;发给别人,点一下确认。卡片上每个新收件人旁边有一个「以后 TA 的来信直接处理(加入白名单)」,默认不勾;勾上再批准,TA 就进了白名单——以后 TA 发给 Agent 的信直接处理,Agent 给 TA 发信仍然每次问你。
  • 电脑操控(Computer Use):主对话里 Agent 要替你点鼠标、敲键盘时,点一下批准;Codex 也一样弹到手机上。需要本人验证的具体动作仍须验证。卡片上有「以后这台遥控器批准的 Computer Use 不再问」,默认不勾;勾上再批准,以后同类操作从这台遥控器来时不再弹卡。想恢复,在「设置」→「安全」→「免问的动作」里点「取消免问」;解绑这台遥控器或紧急停止所有 Agent 时也会自动取消。指纹清单命令永远不能免验证。
  • 没批成时,卡片和 Agent 会写明原因(等太久、通行密钥没通过、当时没有遥控器在线、你点了紧急停止所有 Agent)和下一步怎么办。

普通工具跟随底层 AI 编程工具:它放行的,Agent J 不加卡;它要确认的,手机显示「确认」「拒绝」「我有疑问」普通按钮,不要求指纹。只有 agentj uv list 明确列出的 Agent J 命令及对应手机操作,才要求主人在已配对设备上当场验证,包括秘密显示、发送与填入,设备与通行密钥管理,审批等安全设置和用户注册的高危函数。后台完成、心跳、压缩恢复、Webhook 和邮件回合中的普通工具也按底层权限走;好友访客仍保留隔离沙箱。外部内容不能代替本人验证。要保护自己的低频转账或删数据程序,可用 agentj fn add <name> -- <command> <args> 注册,再用 agentj fn run <name> 执行;注册、执行和删除都须现场验证,agentj fn list 只读。完整说明见手机审批。

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

收起后:回复卡左下角的心跳入口提示仍有操作待批

提问卡(紫色)

Agent 让你选一个答案:点选,再点「确认」。几个选项都不合适,就取消这个问题,直接打字回答。不管Agent J 主机上用的是 Claude Code、Codex、OpenCode、Kimi 还是 Qwen,Agent 都能弹这张卡(agentj ask),可以单选、多选,选项下面可能带一小段预览;选「其他(我在聊天框里写)」或开放题的「好,我在聊天框里回答」,就直接在输入框里打字回答。卡片没真弹出来时,Agent 不会说卡片已经弹出。选项下面的说明最多显示两行,长的点「…展开」看全;Agent 写的选项名不超过 12 个字、说明不超过 60 个字。

模型的安全检查拦下了消息时(Claude Code):不用回到 Agent J 主机前。第一次会弹一张提问卡,问以后怎么办:换到备用模型继续(以后再被拦也自动换,不再问),或者留在原来的模型;每个选项下面写着会怎样。选留下,这一轮停下,你的原话放回手机输入框,改一改或原样再发都行。以后再被拦,共享会话里会弹一张四选一的卡:换到备用模型继续这一轮、用原模型原话重试这一轮、「改一改再发」(这一轮取消,原话放回输入框)、「开新对话」(这一轮取消,之前的内容不再带上)。Agent J 自己开的会话会发一条提示,说明怎么接着来。

一键回复按钮:怎么快速回复 Agent

Agent 的回复末尾有时会带几个圆角按钮,比如「派」「先不派」。点一下,就等于你在输入框里打了这几个字、再点发送:消息立刻以你的名义发出,Agent 收到就接着干。点过以后这组按钮变灰,旁边写着「已回复:派」,同一组只能点一次;你已经打字回答过,或者在别的遥控器上点过,按钮也会变灰。中间先聊了别的事也没关系:回头翻到那条再点,按钮照样能用,发出去的是对那一条的回复,带着对它的引用,Agent 知道你答的是哪个问题。一条回复里有好几组按钮时(每一行或每个列表项是一组),每组各点各的,点了一组不影响其他组。

什么时候是按钮、什么时候是卡片:

  • 一键回复按钮:Agent 只要你拍个板,选项不多(2–4 个),也不急;它不会停下来等你。
  • 提问卡(紫色):Agent 必须等你答完才能继续,或者要多选、看预览、自己填写。
  • 审批卡(橙色):核对任务来源,确认、提问或拒绝;本人验证按卡片要求。

按钮只出现在 Agent 自己写的话里:引用块、代码里,以及 Agent J 主机发的系统通知、定时任务结果里长得像按钮的写法,只显示成普通文字,点了也不会发送。

回复里的 #标签(比如 #发布)点一下,会打开「搜索聊天记录」,列出所有带这个标签的消息。

管理员密码卡

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

管理员密码卡

Agent J 主机也可以记住这个密码:在卡片上勾选一次「用 Face ID 记住(下次扫脸即可)」,下次点「用 Face ID 填入 Agent J 主机登录密码」就行。它只以加密形式存在Agent J 主机上,每台设备用自己的 Face ID 解开;换一台设备时,在那台的「设置」→「安全」→「Agent J 主机登录密码」点「让这台也能用」。它防什么、不防什么,见 Agent J 主机登录密码。

密钥卡

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

密钥卡

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

从手机领取自己的密钥或配置(密钥领取卡)

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

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

开工卡(长程任务)

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

详细说明见 手机上完成管理员授权和密钥录入。

来自你的自动化的消息

你自己的脚本、定时器可以用 agentj notify 往手机发一页消息,标题是「来自你的自动化:」加上它的名字,图片和文件显示成文件卡片。每个自动化默认是关的,要你打开:在设置里的「自动化消息」里,或在 Agent J 主机上运行 agentj notify --allow <名字>。那一页也有总开关。同一条消息也会交给 Agent 看一眼,它只当作脚本发来的资料,不增加权限;成功给你一句总结和 FYI,失败说清问题和已安排的处理,需要你时说清要做什么,纯噪音才不出声。Agent 帮你建的长程任务,创建时就定好发不发,你也可以在同一个地方改。Agent 自己永远不能这样发。详见 长程任务。

定时运行的自动化

每天、每周反复要跑的事,Agent 默认用 Agent J 主机自带的定时器(Linux 是 systemd 定时器,macOS 是 launchd,Windows 是任务计划程序),到点以无头方式启动你的 AI 编程工具。你们一起设计、手动跑一次,你看过报告说没问题,以后运行就不再问你。点了全部停下,Agent 自己建的这些定时运行不会暂停:想暂停某一个,让 Agent 关掉它的定时器。agentj tasks 照样能用。已经启用的 Agent J 定时任务,升级后手机会弹一张主机审批卡「Agent J 主机 · 定时任务改用系统定时」,批准一次(不用 Face ID)就全部搬过去,试跑没成功的自动退回;点「拒绝」就不搬,也不再自动弹卡;运行 agentj tasks migrate 还能再发,拒绝后 24 小时内最多一张。搬过去的任务不再经手机审批,隔离照旧,全部停下能停住它们;改了任务就不再运行,要重新搬。手机「定时任务」页里,搬过的任务下面有「退回」和「重新迁移」。见已有的定时任务改用系统定时。详见 装好之后,Agent J 主机上怎么用。

给别人发邮件的自动化

Webhook 或 Agent J 定时任务要给你以外的人发邮件,需要授权一次。在你自己的对话里说清可以发给谁,Agent 运行 agentj automation grant,你用 Face ID 确认一张卡。之后授权范围内的邮件不再弹卡;发给其他人的不发出,Agent 会告诉你补授权的命令。内置清单上的公共邮箱域名和公共后缀(如 gmail.com、co.uk)只能按完整地址授权;清单并不完整,请核对卡片上的域名。改了 Webhook 的验签方式、来源 IP、投递目标或说明,改了定时任务的定义,用过「全部停下」或换了发信邮箱,授权就作废;只改名字不影响。「设置」→「安全」→「自动化外发授权」列出所有授权,点「撤销」立即生效。详见 Webhook。

全部停下

在「设置 → 安全」点「紧急停止所有 Agent」,确认后:正在做的事马上中断,等你批准的请求全部拒绝,批量授权收回,定时任务暂停。屏幕变成灰色,上方显示「已全部停下」,直到你点「恢复」。

已全部停下

设置

首次准备请打开「设置」→「Agent 的功能」→「首次准备清单」。不必寻找聊天顶部的横幅:清单未启动、主机已收起或这台设备已收起时,顶部没有这个入口。选择和审批能在手机上做的,直接在手机上完成;需要本人在主机操作的项会写明下一步。详见首次准备清单。

设置

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

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

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

紧急修复

「设置」里第二项就是「紧急修复」。消息没回应先按本页 [只有手机时的排障顺序](#phone-only);手机灰了或离线时按下面两步试:

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

Agent J 主机上的 Agent J 不响应时,Agent J 主机上有个小小的救援守护会替它接手机:顶上显示「Agent J 主机上的 Agent J 没响应,救援守护在线」,① 和 ② 照样能用。一直连不上时,在手机浏览器打开 在线客服,不用找 Agent J 主机旁边的人。详见 手机显示灰色或断开怎么办。

「紧急修复」下面的「终端指令」提供固定的终端检查,每条旁边都有「执行」。只读自检 doctor --read-only 只验已配对设备签名,不用 Face ID,大屏也能运行。status、service status、rescue status、update check 和重连修复 doctor --reconnect 仍要用通行密钥验证;大屏没有验证能力时请回手机确认。旧版 Agent J 主机的检查可能仍要求 Face ID。结果先在 Agent J 主机遮住凭据,再以文字显示,并留下操作记录;点 × 可关闭结果。

「接管卡住的会话」(在「紧急修复」里):AI 一直显示正在回答、点停止也没用时用它。它先打断这一轮,10 秒还停不下来就重启 Agent J 用的 AI 后台程序,再接回同一段对话,对话不会丢。

官方远程协助:已经做好,还没开放。 开放前手机上看不到这一项。开放后,在「紧急修复」②下面选 15、30 或 60 分钟,用 Face ID 授权。Agent J 官方客服只能给你的 Agent 发任务文字,你的 Agent 照平时的规则做,权限不会变大;花钱、删除、发送、动密码这类步骤,照样一条条等你批准。点「看实时画面」能看到每条任务和回复,点「收回」马上停下。只有你的 Agent 为这些任务写的回复会发给官方客服,像密码或密钥的内容先被拦下。记录在 Agent J 主机上留 30 天:agentj assist status、agentj assist log、agentj assist revoke。

网页终端

打开 Olares 应用内的终端: 在 Agent J 应用设置页点「打开网页终端」,或在已配对遥控器的「设置」→「安全」点「打开 Olares 网页终端」。新标签页由 Olares 验证登录,终端使用 Agent J 应用内同一个用户、主目录和配置。用 agentj status 查看状态,用 agentj tasks list --json 查看自己的后台任务;不要打印密码、密钥、令牌或完整进程命令行。它不要求开启 Agent J 行模式终端或额外的 Agent J Face ID,也不提供行模式的输出遮挡、操作日志和命令确认。见 Olares 网页终端。

普通 Linux、macOS 和 WSL 的 Agent J 主机支持完整网页终端。手机、平板和电脑浏览器都可以用:从头像菜单打开终端卡,或到「设置」→「安全」→「网页终端」。先配对并设置通行密钥;终端默认关闭,由你本人用通行密钥和 Agent J 主机登录密码开启,也可以在 Agent J 主机终端运行 agentj terminal enable 后核对确认卡。每次打开仍要确认本人,默认最长 15 分钟、最多 60 分钟。完整终端支持 Tab 补全、方向键、Ctrl+C/D/Z、vim、top 和交互程序;手机和平板有常用键行,软键盘和旋转屏幕后会调整大小。它不读你的 shell 启动文件。直接在终端光标处输入,没有独立的聊天式命令框。手机和平板点终端区唤起软键盘;旧主机会提示升级,组件加载失败就关闭,不会改用逐行输入框。

主 Agent 在回复中写明命令要在 Agent J 主机上运行时,紧跟在这行说明下的单行 shell 命令会显示 ▶。点 ▶ 后按手机提示操作,需要批准时会显示确认卡。需在其他设备上运行的命令、没写明目标的命令,以及好友消息、转发和引用中的命令,都只显示复制。

完整终端 5 分钟没有输入或输出、浏览器隐藏超过 60 秒、到期、紧急停止所有 Agent 或设备被收回时会关闭。短断线最多保留 30 秒,只能同一设备重新验证通行密钥后恢复,原到期时间不变。点 ✕ 收起后仍继续运行,点「结束」才关闭。输入焦点在完整终端内时,Esc 交给正在运行的程序。

在原遥控器点「验证并恢复终端」,用通行密钥接回原进程。页面会显示剩余时限。若旧连接留有未提交的输入,终端会安全结束。仍在授权范围内可点「重新验证并开启」。若临时权限已到期,点「填写临时授权申请」,检查主对话里的草稿后发送,由主人确认。

顶上「操作日志记录中」可以打开记录说明:完整终端只记录先遮挡的输出和大小变化,不单独记录按键;兼容行模式还记命令。日志仅存在 Agent J 主机,30 天后清理,不录屏、不开摄像头、不自动上传。输出遮挡不能识别所有格式或编码的秘密,不要打印或转发密码、密钥、令牌。端到端加密不阻止程序把内容显示给自己的设备。

以 ! 开头的消息(如 !df -h)仍是直接运行一行命令,与「执行」只预填不同。它的输出,以及 Agent 读取的终端输出,会先尝试遮挡,再交给你使用的 AI 模型服务商;完整终端的整屏画面不会直接交给 Agent。查看 聊天里的 undefined 命令、Agent J 主机登录密码和网页终端说明。

模型和 API Key

本版手机暂不显示 Agents Relay 密钥区。已保存的密钥不会切换主模型或官方登录,也不代表已测通服务商或已支持后台派单。不要把密钥发进聊天。

「设置」里的「模型和 API Key」最上面是选模型,下面分两块:「基座模型」按服务商一张虚线卡片,列出 Anthropic、OpenAI、火山方舟、阿里云百炼、Kimi、DeepSeek 等的 Key(标着订阅、按量或登录);「第三方 API Key」列出Agent J 主机上的其他 Key(比如 ElevenLabs)。每行只显示名字和「未填」或打码(最多露最后 4 位),Key 本身永远不显示在页面上。右边是图标:拷贝、修改、删除;没填的只有「填写」,底部「添加」可以先起个名字再填。拷贝、填写新值、修改和删除都要先当场验证通行密钥,删除前还会再确认一次;拷贝时值直接进剪贴板。修改和填写打开密钥卡,保存新值或替换时要当场验证,Agent 看不到你填的值。每次拷贝、删除、修改都记进审计日志,只记名字,不记 Key。Agent J 主机上已经有的 Key 也会列出来:systemd 用户环境、~/.config/environment.d/,以及你在 api_keys.extra_env_files 里登记的 .env 文件(默认不登记,跟 Agent 说一声要加哪个文件就行)。这些行标着「Agent J 主机上已有 · 来源 X」,最多只露最后 4 位;点「收进 Agent J」确认一次,Key 就在Agent J 主机上复制进 Agent J 自己的密钥文件,之后以它为准,旧来源默认保留,也可以勾选注释掉。符号链接、别的用户的目录、别人能改的文件一律不读,页面底部会写明查过哪些地方、跳过了哪些。Claude、Codex 的登录行写明正在用的是哪一种:订阅 token(CLAUDE_CODE_OAUTH_TOKEN)优先于 ~/.claude/.credentials.json 的账号登录。装好以后在这里把 Key 填好,就可以离开终端了。

AI 登录救援和到期前续期

救援过程中会留在设置原处,新授权卡出现时会自动定位到卡片。Claude 授权码卡里直接有「打开授权链接」和复制按钮、剩余时间与第几轮;收起后可在救援页点「打开授权码卡」。Codex 的设备码卡同时显示链接和设备码。授权页在新标签打开,完成后回到这里;页面会显示等待授权、已保存并正在实测,以及通过或失败。每次打开救援页都会重新实测当前登录,旁边写明检查时间,也能点「现在检查」;页面打开时会检测其它途径换上的登录并重新检查,检查期间不显示旧结论。

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

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

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

在回复下面「重新登录」:回复说 AI 没登录、登录过期或要确认设备时,下面会出现「重新登录」(回复里的 /login 也会变成这个按钮)。点它,用 Face ID 确认,在授权页面登录并授权:Claude Code 把授权码贴回「粘贴授权码」,Codex 在授权页面输入它给的代码。在你正在用的对话里试发一条消息收到回复,才算登录成功。OpenCode 点「其他登录方式」。

备用 AI 账号

打开 设置 →「Agent 的功能」→「备用 AI 账号」,管理 Claude Code、Codex 额度用完时自动切换的备用账号。页面里的「主账号」与「模型和 API Key」显示同一份配置,只能查看;点链接到「模型和 API Key」修改。这里只添加或管理备用账号,不用再填一次主账号。已保存的账号仍按原数据显示。

  • 点「添加账号」,起个名字(1–24 个字,每个 AI 最多 8 个),用通行密钥确认,再照常在手机上登录:Claude Code 发来授权链接,授权码贴进密钥卡;Codex 给你链接和一次性码。新备用账号单独保存,不会覆盖已有的账号,也不用重新填写主账号。
  • 点「设为当前」就切过去,不用 Face ID:主 Agent 从下一条消息起用新账号,接着原来的对话。正在跑的后台任务用完原来的账号为止,之后新开的任务用新账号。
  • 也可以直接在聊天里说「换 Claude 备用账号」。在 Agent J 主机上:agentj account list 看账号,agentj account use claude 备用 切换;添加账号用 agentj account add claude 备用,要在你自己的终端里运行。
  • 额度按账号分开记:正在用的账号显示实时读数,其他账号显示上次读到的。
  • 正在用的账号不能删除,先切到另一个。删除前会弹确认卡,这个账号存的登录凭据也一起删掉。
  • Agent J 主机的环境里设了 ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN 时,它会盖过这里选的 Claude 账号,暂时不能切换。
  • 不要把 token 发进聊天。

遥控器管理

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

遥控器管理

「设置」→「遥控器管理」是单独的一页:上面是 10 台里已经用了几台;下面列出每一台手机或浏览器(在不在线、什么时候配对、最近什么时候用过、怎么加进来的,你手上这台标着「这台」),每一行都能「改名」「解绑」(解绑别的遥控器要用你手上这部的 Face ID);「添加遥控器」会给出一个 5 分钟内有效、只能用一次的二维码和链接,新设备上会出现 6 位对照码;核对两边数字相同后,在已配对遥控器弹出的确认卡上批准。

所有遥控器一视同仁。手机丢了,就在任意另一台遥控器上解绑它(用你手上这台的 Face ID):等它处理的卡片立即被拒绝,你的同主人 Agent J 主机也不再接受它的签名。配对「同一个主人」时两台Agent J 主机都还没有设了通行密钥的遥控器,就仍用旧的确认方式(只要遥控器签名,不核验 Face ID / Touch ID,不列遥控器名单);在任意一台遥控器上设好通行密钥,再重新配对一次。详见同一个主人。

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

键盘快捷键

键盘快捷键

在遥控器浏览器或者接了键盘的平板上,按 ? 打开快捷键表(「设置」里也有);快捷键多了记不住,点表右上角的放大镜或按 / 搜关键词就行。每个点按、长按、滑动对应哪个键,全表见 键盘快捷键和手势。常用的:

键作用
Alt+Shift+J · j · ←上一条(更早)
k · →下一条(更新)
Alt+Shift+G · g跳到最新一条
G跳到最早一条(更早的会从Agent J 主机上取)
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搜索当前这一页:聊天里搜聊天记录,工作流 / 技能 / 记忆 / Agent J 页筛卡片,设置、菜单页和打开的文档在页内查找(输入框里的 Ctrl+K 仍是删到行尾),再按一次清空并关闭
i · Esc进入输入框;在输入框里按 Esc 离开(输入的字保留)
/命令菜单:在输入框外按 / 直接进输入框,斜杠已经填好,命令菜单随即弹出;弹窗或设置开着时不抢
a选文件发给 Agent
p从相册选图片
c拍照
按住 m按住说话,松开直接发送(滑出取消);键盘 m 松开仍转文字
Esc Esc在输入框外按两下 Esc 清空文字和附件(✕ 只清文字,可以撤销)。Esc 从不打断 Agent;要停下当前任务,点 Stop 按钮或发 /stop
⌘+Enter / Ctrl+Enter批准,等于点一下「批准」(验证本人照常);审批卡开着时优先给它,输入框里的发送让位

配对和 Face ID

任何设备都能先用浏览器打开 https://m.agentj.app/。 新设备的配对页会直接显示二维码,拿另一台已配对且在线的遥控器扫这个码,核对两边的 6 位数相同后确认,新设备就会进入对话;不用回到主机,也不用新设备有摄像头或 Face ID。浏览器不支持生成这个码时,改用下面的扫码或粘贴链接。

第一次配对、手边还没有已配对遥控器:在主机运行 agentj pair,用新设备页面里的扫码按钮扫主机的码,然后在主机提示中输入新设备显示的 6 位码和遥控器配对密码。相机不可用时运行 agentj pair --link,把配对链接复制到新设备的链接框,再开始配对。主机已绑定账号并在线时,也可以从账号页添加遥控器。完整步骤见手机上怎么用。

已经配好的遥控器也能在设置的遥控器管理页生成码或复制链接,让新设备扫码或粘贴;核对两边的对照码,在已配对遥控器的确认卡上批准。

配图待补:原配对截图未展示新设备亮码及双屏核对流程,暂不作为当前界面示例。以本节步骤和实际页面为准。

配对链接和连回

配对链接 5 分钟内有效,只能用一次。它是钥匙,不要发到聊天、群聊、邮件或交给 AI。在 iPhone 上先加到主屏幕,从那个图标里扫码或粘贴;系统相机直接打开链接会配对 Safari 里的另一份页面。

配对后,从同一个浏览器或主屏幕图标打开通常会自动连回;可用的自动登录凭证会轮换。网站数据或凭证被清掉、凭证失效或主机已解绑时,不保证自动恢复;看连不上怎么办和隐私。

配对后可以给这台遥控器设通行密钥,用它自己的解锁方式:iPhone 用 Face ID,Mac 用 Touch ID,安卓用指纹或人脸,Windows 用 Windows Hello。每台遥控器在自己身上设一把:「设置」→「Agent 与遥控器」里写着这台的状态,比如「本机 Face ID:已设好」「本机 Face ID:未设」(安卓、Mac、Windows 写各自的解锁方式,比如「本机 Touch ID:已设好」),没设就点「在本机设置」;Agent J 主机上已经登记过这台的钥匙时(升级以前设过的也算)直接显示「本机 Face ID:已设好」,不用再设;显示「本机 Face ID:未确认」时点「用 Face ID 确认」验一下就好,不用另一台批准;没有别的遥控器能批准时,在 Agent J 主机的终端运行 agentj faceid approve <对照码> 批准;「遥控器管理」里每台也标着。这台用的是别的设备上的通行密钥时,确认前会先提醒你,系统会请你用手机扫码;在本机设好后就能直接确认。验证没完成时,卡片会写明原因,并给出「再试一次」和「在本机设置 Face ID(需另一台批准)」。显示「已设好」时,下面还有「测试一下」(验一次,什么都不改)和「重新设置」(不解除配对,直接换一把新的)。验证时页面被切到后台、连接断开,页面会显示「正在补交…」,连上 Agent J 主机就把结果送过去。

以后配对页提供「用 Face ID 连回Agent J 主机」时,验证后可恢复原设备位置,不用重新扫码或主机批准;同步到另一设备的通行密钥也可能顶替原设备的位置。主机解绑后,通行密钥不能再把它连回来。

没有 Face ID 或通行密钥,也能当遥控器

不支持或尚未设置通行密钥的设备,可以通过扫码、被扫码或粘贴链接配对,正常看对话、发消息和附件、使用语音,并用设备的签名密钥批准普通操作、管理遥控器。这里的降级是少了通行密钥验证,不代表只能看。

它不能用通行密钥连回,也不能完成明确要求通行密钥的操作,例如领取密钥、拷贝或删除 API Key,以及其它会显示真实密钥的操作。请改用已设置通行密钥的遥控器,或在支持的设备上先设置。管理员授权和密钥录入卡仍可按页面要求使用;已有通行密钥的设备在这些卡上必须验证本人,不能通过跳过验证降级。

浏览器连签名功能也不支持时,不能批准操作或执行需要签名的控制;页面会提示换新版浏览器并重新配对。通行密钥和普通签名是两项不同能力。

设置 Face ID:由另一台遥控器批准

每台遥控器各有自己的 Face ID / 指纹钥匙。在「设置」→「Agent 与遥控器」→「设置 Face ID」里设置:这个 Agent 还没有别的遥控器设过 Face ID 时,这台直接设置;已经有了,就由那台批准。这台显示一个 6 位对照码,你其他设过 Face ID 的在线遥控器会弹出确认卡,两边数字一致就点「批准(Face ID)」,再回到这台点「保存」。重装系统、清了浏览器数据后钥匙没了,也这样重新设置,新钥匙会换掉旧的。只有这一台设过、它的钥匙又没了时,先在主机上解除这台遥控器再重新配对。详见手机上怎么用。

转移席位到另一台 Agent J 主机

换 Agent J 主机时,在「设置」→「Agent 与遥控器」里点「转移席位到另一台 Agent J 主机」,看完说明点「继续」,用这台的 Face ID 确认。遥控器会给出新的 Agent J 主机用的整段安装提示词(码默认遮住),点「复制」,粘到新的 Agent J 主机上的 AI 工具里。新的 Agent J 主机用码绑定后,席位转过去,遥控器自动跟到新的 Agent J 主机;没跟过去时点「扫码配对新的 Agent J 主机」。转移码 24 小时内有效、只能用一次,新主机用码之前可以点「撤销」。旧主机要在线;在旧主机的终端里也可以运行 agentj seat transfer。详见从遥控器转移席位。

用一句话就行的事

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

  • 「接着昨天那件事」「上次那个报表做完了吗」:它会翻本机的历史记录,找到那件事接着做。
  • 「重来」「换个说法」:它会换一种做法重做上一条。
  • 「打开那个 xx 项目」:它会在你的工作目录里找到这个项目。
  • 「压缩一下」:先写交接,再压缩。
  • 「切换到 Codex」「切回 Claude Code」:换 AI 编程工具,先检查、能用才切,见 换 AI 编程工具。
  • 「我要反馈一个问题」:先问你想反馈什么;你给出内容后,它脱敏直发并告诉你编号。Agent 自己想反馈时先出稿请示。
  • 「把我的名片发给老王」「老王最近说了什么」:管理 Agent 好友,见 Agent 好友。
  • 做一件很长的事时,它会时不时用一句话告诉你进度。
  • 「做每周竞品简报」这类长期要做的事:它会自查能力,只发一张开工卡让你确认,见 长程任务。
  • 「你会什么」:手机上弹出能力页,看哪些已就绪、哪些要配置。
  • 想每天早上收 Daily AI News 邮件:说一声,它会运行 agentj news on(和「设置」里是同一个开关,见 Daily AI News)。邮件发到你自己的邮箱;还没有邮箱时,它会先问你要一个,再用邮件里的 6 位验证码确认。

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

从其他设备给席位添加遥控器

目标Agent J 主机安装完成、绑定账号且在线后,在账户页找到它的席位卡,点「添加遥控器」,用通行密钥确认后用新遥控器扫码;账号页自动显示等待配对、六位确认码和「批准」,核对两边一致后点「批准」,并再次用通行密钥确认。当前设备没有已有密钥时,可在浏览器弹窗里选「使用手机或平板」,用原手机扫码验证。配对密码若被主机要求,是额外验证,不能代替账号的这次确认。出码后本页会自动轮询,无需点「查看待批准的遥控器」;席位卡「更多」里的「查看Agent J 主机上等你处理的事」只在两种时候用:Agent J 主机被「全部停下」后要恢复,或 Agent 新建的定时任务等你启用;它跟席位和付费无关,欠费也不会停掉Agent J 主机上的任务。

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

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

Codex 报错时,先看手机上的操作提示。账号用不了当前模型时,点顶部模型名换一个;被拒绝的模型会暂时禁用,重新登录后刷新。连不上 ChatGPT 时,检查代理/VPN 后重发;登录失效时,在手机打开「设置」→「紧急修复」→「AI 登录救援」,然后选择 Codex,按设备码卡重新登录。需要运行排障命令时,使用已配对页面的「网页终端(Web Terminal)」,不用回到主机,也不要把登录凭据发进对话。原始报错经脱敏后保留在「详情」里。

Codex 额度升级后仍报用完? 对明确尚未接受的额度拒绝,Agent J 会先刷新当前登录并重新检查,最多重试一次。已经接受、已有输出或工具执行情况不明确的请求不会自动重放。仍未恢复时,在手机发送升级了,或打开「AI 登录救援」,然后选择 Codex,按设备码卡继续;你可以重新验证当前账号,或明确选择另一个账号后发新消息。刷新或登录成功不代表套餐已升级,最终以服务商的实际结果为准。

共享 Codex 的模型与服务商(0.16.4a1)

手机发起回合时,主人配置的 agent.model / agent.effort 或手机最后一次明确选择会传给 Codex。没有手机明确选择时沿用会话自己的模型。Agent J 主机发起回合用Agent J 主机端最后一次明确选择;手机跟随实际模型,不抢改Agent J 主机的选择。顶部显示当前生效的模型;点默认后,下个手机回合使用当前 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 只报告、不改。已开启:手机消息不用在Agent J 主机上逐条确认;想关运行 agentj config claude-inbound off。改设置前就启动的会话需要 /clear 或开新会话。仅影响 Claude Code,Codex/OpenCode 无此机制。消息没被接收时,手机会说明具体原因(组织策略、项目设置、已关闭、需要 /clear、Agent J 主机正忙),重发前先检查Agent J 主机。手机的模型/额度条(agentj config claude-statusline)同时默认开启(主人关掉过就不开),串联在实际生效的状态栏那一层;被别的层遮住时 agentj doctor 会报告。

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

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

共享会话

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

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

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

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

分享截图

安卓系统分享与 iPhone 剪贴板快捷指令。分享内容先进入输入框,补一句话后再发送。

更新手机网页

到 Olares 应用市场「管理 → 更新」升级 Market 安装的 Agent J。手机 /update 和 agentj update apply 会提示去应用市场;不要在应用内重装或安装 systemd。直接装在 Olares 宿主 Ubuntu 上的普通安装仍走普通主机升级流程。

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

升级后页面一直灰? 先看页面提示:若是「Claude 会话没接上」或共享 Claude 会话缺失或匹配不明确的提示,点页面的「一键修复」。旧版没有这个按钮,或修复后仍没接上时,在「设置」→「安全」→「会话模式」点左侧「独立会话」;保存成功后,再到「设置 → 紧急修复」点「重启服务」。若提示 Claude 未登录,先用同页「AI 登录救援 → Claude → 重新登录(推荐)」按画面完成登录,再重试。连回后发一句「你好」,收到新的 AI 回复才算恢复;旧聊天记录保留,新会话不保证接续旧上下文。只需已配对页面,不用到主机前或打开终端。若页面显示主机离线,按下方断线步骤检查;主机在线也不代表 Claude 会话已接上。需要刷新网页时,点右上角齿轮 →「网页版 App」→「更新并刷新」;旧页面可能只有版本号下方的圆箭头。

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

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

网络短暂抖动会被悄悄修好:手机连接断开后一般一秒内就连回来。断开时左上角 logo 旁的状态点马上变灰;超过约 5 秒还没连上,页面才变灰并显示「连接断了,N 秒后重连…」;10 秒还没连上,屏幕中间弹出断开提示框。Agent J 主机忙、回应慢不算断线。Telegram 渠道连续三次(或两分钟)连不上 Telegram 时,对话下方会出现一行提示,恢复后自动消失。Agent J 刚启动的第一分钟里,agentj doctor 显示中继「正在连接」,不算故障。

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

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

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

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

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

新装的Agent J 主机上最常见四种原因,手机都会说明:连不上模型服务(Claude Code 自己重试约 3 分钟,重试约 10 秒仍不行时手机弹卡);缺 bubblewrap(每次启动都会弹「沙箱不可用」卡,要用通行密钥点「本次不隔离运行」;在Agent J 主机上装 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 真停在终端的某个确认上时,手机会收到「在Agent J 主机上处理」卡,原样引用终端里的文字:在手机打开「网页终端(Web Terminal)」运行 agentj agent claude 完成首次设置,再重发;不要把密码或登录凭据发给 Agent。

沙箱失败与管理员命令

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

sudo 卡上的「为了做什么」和「会改动什么」标为「Agent 自述」,「为了做什么」排在最前面;写得太短、只是重复命令,或者想管理 Agent J 自己的后台服务,都不会弹卡。运行 shell 或解释器的命令会标红,必须输入管理员密码,即使已安装免密 helper。少数只读命令的卡片上有一个默认关闭的开关:打开它再用密码同意,10 分钟内同一程序、同样参数、只换文件的命令直接运行,并在聊天里留记录;敏感文件、shell 或解释器命令仍每次要批准,随时可点「收回授权」。密钥卡只支持 URL 校验;--verify-cmd 已禁用,不会在沙箱外运行命令。定时任务和客服 bot 从原生登录存储认证,不继承主机服务的密钥环境。

接入 Telegram

Telegram 用的是你自己的 bot。先用密钥卡保存 bot 密钥,再在Agent J 主机上运行 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。

Telegram 与好友的安全边界

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

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

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

遇到问题怎么求助

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

页面菜单

点左上角 logo,进入聊天、工作流、技能、记忆或 Agent J;长按回聊天。工作流来自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 网站”,并启动登录流程。支持扫码的网站直接弹手机登录卡,二维码只走登录卡;其他网站在Agent J 主机上打开登录页,请你登录一次。检查不确定时会说明不确定,不把它当作已登录。登录不等于授权,发布、付款等操作仍需手机审批。
  3. 本版缺少平台底层能力。 它会说明缺口,提议用 /feedback-to-agentj-father 反馈给 Agent J Father,并说明能力解锁后还需你提供什么。它主动提议的反馈先给你看、获准再发;你明确发送带内容的 /feedback-to-agentj-father 时,脱敏后直接提交,不重复确认。提交成功不代表已经排期,也不承诺上线。两种缺口并存,就把两条路径都说清。

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

工作流页第一次打开、以及Agent J 主机上的 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。

复制系统指令,重新连接 Telegram

主机系统消息会把需要复制的值和命令放进代码块。点复制图标即可,不用手动选中文字。Telegram 配对码和 /start 命令分开放,Telegram 链接会在新标签打开。设置码、恢复命令、终端续聊命令也使用相同的复制操作。续聊命令是可选的;想转到对应终端应用时才需要复制,继续在手机聊天即可。

通过密钥卡把密钥保存到服务环境文件后,Agent J 会自动重读该文件。「重新绑定 Telegram」也会先重读,再检查 token。如果仍需重启,打开「设置」→「紧急修复」→「重启服务」,用 Face ID 或设备通行密钥确认。请求由已配对遥控器签名发送,连接可能短暂断开后恢复。隔离内的 Agent 看不到主机控制 socket 时,只能说明那里无法核实状态,不能据此判断服务已停止。请使用已配对手机的重新加载、Telegram 重新绑定或重启操作。

收进 Agent J 主机上已经发现的密钥

  1. 打开「设置」→「模型和 API Key」。密钥行可以列出 Agent J 主机上已有的来源、遮住后的末尾,以及是否与 Agent J 管理的副本一致,不会完整显示密钥。
  2. 选定要使用的来源,点「收进 Agent J」,再点一下确认。密钥在本机复制,不需要粘贴到聊天。
  3. 默认保留原来源。只有你希望改动时,才勾选注释原来那一行的选项;导入不代表允许删除其他来源。
  4. 查看 Claude 或 Codex 登录行的「正在用」来源。别处列出的密钥未必就是当前 AI 实际使用的登录方式。「重启 Agent J 后生效」表示运行中的 AI 尚未用上这次改动,按该行的重启或登录提示处理后再检查。

刷新、回复选项和大屏遥控器

按住顶部搜索按钮约半秒(550 毫秒)可以强制刷新,文字草稿会保留。正在录音、处理附件或有未提交的卡片时,先完成当前操作再刷新。消息滚到顶部后继续下拉,看到「松开刷新」再松手,也可以刷新。

回复里的选项按钮使用 Noir 深色底、Lotion 浅色字的无边框胶囊,文字与按钮边缘留有间距;按下时底色加深为 Sooty。

大屏上用方向键操作,当前焦点会清楚标出:

  • ↑ / ↓ 在卡片之间上下切换。
  • ← / → 看上一条 / 下一条消息,全屏阅读时也一样。
  • CH± 对应的 PageUp / PageDown 在长消息里每次滚动一屏。
  • 在消息区域连续按两次确认键 Enter,间隔小于 400 毫秒,进入全屏阅读。
  • 按返回键(webOS 的返回键)、Escape 或 Backspace 退出全屏。输入框里仍按原来的方式移动光标、选字和删除。

没有通行密钥的大屏仍按已配对遥控器的原有规则使用。普通审批保留原来的确认方式;明确要求通行密钥的操作会提示「请在手机上确认」,请在手机上完成,电视不会代替验证。

浏览器不能直接录音时,可以用输入框配合系统键盘听写。电视遥控器上的语音键是否支持听写,取决于电视与浏览器;我们没有在 LG 实机验证。横屏 1080p 布局已做 Chromium 仿真检查,不等于电视真机验收。

首次准备语音输入

首次安装语音组件时,页面依次显示下载、解压、安装和自测的当前阶段,不显示估算百分比。组件未就绪时,麦克风显示「准备中」。

完成后会显示醒目的「已就绪」提醒,告诉你可以按住麦克风说话,点「知道了」关闭。失败时显示原因和「重试」按钮,按提示检查网络或磁盘空间后再试。提醒不会自动消失,可按 ESC 关闭,也可能被后来的新提醒替换。

断线重连后会重新检查组件是否就绪;断线期间的安装进度不会逐条重放。

在消息页滚到顶部后继续下拉,看到「松开刷新」再松手,即可更新并刷新;文字草稿会保留,录音、附件或未提交卡片期间不会刷新。左上角机器人随状态变色,自定义 logo 保持原样;顶部状态栏和底部安全区固定为 Sooty #141414。

网页自动更新完成后,会显示约 3 秒的 Noir 通知;同一设备每个版本只提示一次。

快捷键页的搜索也支持同义词,例如截图、截屏和 screenshot。

交互卡每道题都可以选择选项,或在卡内直接填写自己的答案(最多 2000 字);直接填写会替代该题的选项。点「确认」后,答案随卡片签名发回 Agent J 主机,不必再去聊天框补发。旧主机上的卡片仍可选「其他」后在聊天框填写。密码和 API Key 请用专用密钥卡,不填在普通问答卡里。

空录音与恢复

不足半秒或没有有效音频数据的录音会直接丢弃,不保留,也不会弹恢复提示。历史暂存里显示 0:00 的空录音会自动清理。恢复时,左边「丢弃」,右边「放回附件栏」。空音频附件不会发出,会提示「录音太短,没有发出」。iPhone 的 MP4/AAC 录音和其他手机的 WebM 录音都按实际格式处理。

从手机恢复工作

在「设置 → 安全」点「紧急停止所有 Agent」,确认后才会中断主 Agent 当前一轮、停止 Agent J 后台任务、暂停 Agent J 定时任务,并拒绝待批准的请求。Esc 取消。顶部「恢复」入口保留;恢复使用已配对遥控器的签名按钮确认。斜杠菜单不再提供此操作;输入 /stop-all、/stop_all 或 /estop 会提示前往设置。

在「设置 → 紧急修复」的「重置连接」后,点「重启 Agent」并确认一次。主机结束当前 AI 会话进程,再恢复同一段对话;恢复失败时开新会话并接好手机,旧对话保留。Claude Code、Codex 和 OpenCode 都可从手机重连,不需要到 Agent J 主机前。不会改变原来的权限设置;主机无法确认当前进程身份时会拒绝结束它,并提示远程求助。额度恢复后的自动重试另行提供。

确认与执行卡片

审批卡显示任务来源,命令默认折叠;sudo 执行状态保留在当前回复内。长内容可在卡片里滚动,批准仍须签名及相应本人验证。审批收起后,点回复卡左下角的心跳入口重新展开;阅读模式的上下安全区保持 Sooty #141414。

所有拷贝按钮(包括记事本、消息和代码块)成功后都会短暂显示 ✓「已复制」,约 1.5 秒后恢复,并在屏幕中央提示;失败也会提示。语音输入准备成功等纯告知提示会自动消失,不用点「知道了」。阅读模式里拷贝后可以继续阅读。

图标长按与按钮状态

长按图标或工具栏按钮会执行对应动作,不会选中周边图标,也不会弹出系统文字菜单。回复正文、消息和代码仍可长按选择、复制。按钮悬停、按下、键盘聚焦或暂不可用时,文字仍保持清晰;暂不可用的按钮不会执行操作。

屏幕中央的圆形提示只显示一个简短状态词,中文最多四个字,例如「已发送」「已复制」「已保存」;英文只用一个单词。需要说明原因或下一步的长提示会在原位置显示成圆角方形,保留全文和原来的自动消失时间,深浅模式都用 Noir 底、Lotion 字。

排队与静默提示

排队消息下面写着「上一件还在做,已等 N 分钟」和「停止当前任务」:在 0.26.9 的 Agent J 主机上,点了先确认「强制结束这一轮」,再打断前一件,10 秒停不下来就结束这一轮的进程,对话保留。Agent J 主机发来的排队提示,前一件卡住或已等满 2 分钟才有这个按钮。/clear、/new 和「重置连接」不再排在卡住的一轮后面。

排队和前一件没有新输出都满三分钟后,页面提示这段时间没有新输出;这不表示任务一定卡住。前一件出现新输出会重新计时,刷新或重连后也会重新观察。还在干活的任务不会被自动停下。0.26.9 起,确实卡住的一轮(没有卡片在等你、没有工具在跑,却 5 分钟没动静或你的消息排了 10 分钟)会自己恢复:Agent J 主机打断它,必要时重启 Agent J 自己起的 AI 后台程序,接回同一段对话,并说「刚才卡住了,已自动恢复。」。Stop 对未发送消息的处理沿用原有规则。

AI 还在做事时再发一条:用 Codex 且它支持时,新消息直接加进正在做的这一轮(显示「已插入当前这一轮」),否则照常排队,不会丢。前一轮后面的输出接在最下面的新卡片里,原来的卡片显示「继续见下方」。

从失败的一步继续

分步工作流失败后,结果卡和定时任务失败行会提供「从失败处继续」。点一下会请求这一次运行的签名确认;已完成且仍有效的步骤会复用,不从头重跑。任务说明、步骤说明或进度记录已经变化时,原按钮不会放行,刷新记录后重新核对。

可能已发送、付款、发布或删除的非幂等步骤仍会弹出主人确认卡;拒绝就不运行。好友直报、好友转交和「同一个主人」消息都不能代按。旧主机不显示这个按钮,也不能用重复点击绕过一次性签名。也可以让主 Agent 按 agentj-automation 技能核对后续跑。

连续录音与离开页面

页面在前台时,连续录音会复用已授权的麦克风;每次录音结束会禁用采集音轨。锁屏、切到别的应用或离开页面会停止音轨,返回页面不会自动打开麦克风。再次点录音时,浏览器可能重新询问权限;可在 Safari 的网站设置中把麦克风设为允许。系统权限弹窗的实际行为仍需在实体 iPhone 上确认。

邮件与敏感卡片的确认

只发给你自己的邮件不弹卡。发给别人的邮件(包括白名单联系人、会议纪要和邮件回复)点一下确认,不用 Face ID。卡片绑定收件人、内容、附件摘要和邮件服务器;白名单只决定来信是否处理。你在已配对的遥控器上亲手点「转发到邮箱」或转发到 Telegram,或者在客服会话里签名发邮件,这一下就是你的批准,直接发出,不弹卡片,也不要通行密钥。修改邮件设置和测试连接仍需签名确认;输入真实授权码仍走密钥卡。邮箱账号、登录名或 IMAP/SMTP 的服务器、端口、加密方式改变后,旧授权码立即作废。旧版本保存的授权码:邮箱用的是固定服务商(Gmail、QQ、163 等)时,升级后第一次运行会自动迁移,照常收发;自定义服务器的不会直接使用,先核验已登记候选,只有没有可用项时才需要在密钥卡重新输入。

管理员密码卡填写密码后点按钮确认;显示真实密钥仍需要本机遥控器的审批通行密钥,未开通时先到设置里开通。更换已有通行密钥时,先用旧密钥验证本次注册邀请,再创建新密钥;取消或验证失败会保留旧密钥。账号登录的通行密钥与遥控器审批密钥分别设置。

由主机创建新的 Agent J 定时计划

先写本机 JSON 合同,再运行真实主机入口:

agentj tasks create --contract contract.json --json

合同包含 task(现有 task.json v1 格式,enabled:false,两个提示文件名都为 PROMPT.md)和 prompt(任务说明)。只有明确声明为新建大额银行/数字货币转账的任务才加 large_transfer:{"kind":"crypto","limit":"1200.50","currency":"USD"};kind 可为 bank 或 crypto;这个字段即声明“大额”,普通、小额任务和付费 API 不加。主机冻结完整合同,由已配对设备扫一次指纹批准此声明,再原子写入尚未启用的任务。普通任务、付费 API 创建不另弹卡;旧自动化不迁移、不补审。

主人批准的金额写入任务说明,只是说明,不是强制预算。运行期不监控转账、不核实金额、不扣次数、不因超过这个声明拦截;它不代替付款授权,也不提高沙箱权限。首批入口只支持活跃且已核实可写当前工作根目录的 Codex 线程;只读、未知/自定义写根和无法核实的其它工具权限均拒绝,扫指纹也不能绕过。

创建不等于启用:用 agentj tasks show ID 查看,适合时再走现有 agentj tasks enable ID;启用或续跑不补财务审批。首批入口不创建多步骤计划。通道结果未知时先查看任务,不自动重试;已存在 id 不覆盖;即使旧目录已移走,同 id 留有旧启用授权也拒绝创建,不自动清除旧授权。崩溃后未发布的私有暂存不会被发现为有效任务,不自动删除其它暂存数据。若发布冲突要求恢复,保留冲突文件,请主人查看后再决定是否启用或重试。

后台任务信息

后台列表逐项显示程序探测的工具、模型与思考强度、可识别的账号短号或订阅和已运行时长;无法核实就写「未识别」。命令传入的工具和模型另标「自报」,冲突时以探测为准。总数按活跃任务计数,同一进程里的原生子 Agent 各占一行;另列存活进程数。来源退出或原生线程结束就自动收卡。让 Agent 汇报后台时,它应实际运行 agentj busy list --json,引用结果,不凭记忆。账号只显示短号,不显示完整邮箱。

子任务状态无法确认时会标「状态未知」,不计入运行总数;超过最后活动时间的保留期限后自动收卡。宿主程序仍在运行,不代表子任务仍在运行。

0.25.8 本版说明

在办事项显示程序核验的工具、模型、账号短号和运行时长;子任务状态不能确认时仍标为未知。日历新建和修改须逐次长按确认,删除须用 Face ID,批准绑定具体目的端和内容。仅已核验的手机或主人终端输入算主人请求;未知来源、系统提示和外部内容不能借用主人权限。邮箱先核验已保存授权码,无可用项才请主人重新输入。主人要求自行压缩时,先写交接、排入压缩,再结束本轮。

编辑巡检清单

打开设置 → 心跳 → 查看或编辑心跳提示,在全屏编辑器里查看和修改。四角分别是取消、恢复默认、预览和保存;恢复默认先改草稿,保存后生效。取消保留原文,保存失败会保留草稿。设置里的文字字段和通讯录备注也用同一编辑器。

出厂清单会检查本机所有定时任务(Linux systemd timer/cron、macOS launchd/cron、Windows 计划任务)自上次心跳以来的日志和报告、Agent J 好友中异常或卡住的请求,以及邮件/微信/Telegram 主线程的来信、回复和待办,看看有没有漏回、失败或无人认领的事。canonical 清单会从 v1 原地迁移到 v2,保留其它个人正文。主 Agent 需要时补回复或接手,仍遵守原有审批。忙时也按同一份清单顺手巡检,忙时不会触发心跳。

升级只原地迁移带标记的出厂清单并去重,保留清单外的个人正文;完全自定义、没有出厂清单的 heartbeat.md 会保留原样。doctor 和设置提示「出厂清单有更新,可一键合并」时,点合并出厂清单会替换旧清单;原来没有清单时才追加。

主 Agent 可运行 agentj inbox avatar-log --since 2h(也可写日期或时间,加 --json),只读列出本机保留的旧分身往来摘要。这些历史不代表当前通道;当前主人来信仍由主线程直接处理,不会恢复旧分身路由。历史可包含回复、处置结论和送达状态。复核时应覆盖上次心跳以来的时间;旧记录缺少回复或送达证据时显示未知。记录有保留期限和大小上限,截短或通道不可用时会明确提示,不能因为没有记录就判断一切正常。

一次确认一份具体动作清单

需要多次确认的任务,可让 Agent 先列出全部具体动作,合成一张卡给你看。点「批准」;涉及花钱、显示或外发真密钥、不可恢复删除等需要本人验证的动作时,整张清单用一次 Face ID。只批准卡上列出的工具和完整输入;改了命令、换了任务或设备、过期后都要重新确认,不会顺带放行同类动作。

本机任务用 agentj friends approve-actions <动作清单.json>;派给已确认「同一个主人」的设备,用 agentj friends tell <好友> --actions <动作清单.json> <任务文字>,发起方签一次,接收端只执行清单内的具体动作。清单是 1–20 项的 JSON 数组,每项为 {"tool":"Bash","input":{"command":"<完整命令>"}},不写凭据值。申请批准本身不会执行动作。本机授权最多 30 分钟、20 次,任务结束或撤回即失效。

显式同主人清单只认接收方已记录的发起方遥控器签名;其他签名返回 root_reconfirm,先重新做一次同一个主人配对。带清单标记的任务若证明缺失、无效、被改动、超长或过期,接收端直接拒收并返回 task_refused,不降成普通任务、不再弹接收端卡;已排队的清单过期或任务回合变化也拒绝。普通不带清单的转交照旧。

Olares 应用内切换 AI 工具

Olares 应用内的 AI 工具扫描、切换、重启与失败恢复由镜像内只读进程管理器执行;保留已配对手机的签名确认。切换失败时会恢复原配置,并在原 AI 恢复服务后确认回退;未恢复会明确报告。应用内无需安装 systemd。随包 OpenCode 固定为 2.2.5,已有可用的自装工具不会被静默替换。

直接选择原生 Claude Code:先在本应用内安装并由本人登录 Claude Code,再用 agentj agent claude 切换。OpenCode 内的 Claude Agent 是另一入口:需 Claude Code 2.1.248 或以上,由本人运行 claude auth login,再在 OpenCode 的 /connect 选择 Claude Agent。Agent J 不复制 OAuth token;登录完成不等于模型调用已经验证成功。

外部助手:单向 MCP 请求

手机上打开设置 →「Agent 的功能」→「Webhook」→「外部助手 · 单向请求」。填连接名称和允许的网站来源,每行一个完整 HTTPS origin,例如 https://assistant.example,不带路径、参数或末尾斜杠,再点「创建连接」。在手机签名卡上确认后,从领取卡完成 Face ID 验证,一次性领取凭据;连接地址可以从列表复制。

外部助手只能发请求并收到固定回执,不能读取 Agent J 的回复、对话或工作结果,也不能替你审批。入站请求和认证信息会经过云中继内存;回复与工作结果只留在你的主机和手机。列表只显示连接元数据,不显示凭据。丢失凭据就点「轮换凭据」并重新签名领取,旧凭据立即失效;不用时点「撤销连接」并签名确认。

当前支持 MCP 2025-06-18、无状态 JSON 请求,不提供 SSE 或双向结果回传。Muse 的账号连接与平台审核仍待本人授权和实际验证,本页不代表 Muse 已审核或可用。

实时语音通话原型(#441,默认关闭)

这是开发原型,未声明生产可用。主机进程显式设置 AGENTJ_VOICE_STREAM=1 后,复用现有 voice.asr.mode=custom 和 base_url,从同一地址派生 /v1/audio/stream。目前仅支持回环或局域网 IP 字面地址;地址仍经过现有 custom URL 校验,浏览器不能传入地址或密钥。不支持流式接口时显示“流式语音不可用”,不会退回整段录音伪装流式。无需安装新技能。

配对手机出现“开始语音原型”后,点击开始、按住说话、松手提交;“结束通话”随时停止。真实 16kHz 单声道 PCM 每 200ms 经现有端到端加密配对会话发往主机,partial 字幕随到随显示,final 最多提交当前主 Agent 一次。回复按句交给手机浏览器的本地免费语音(没有本地声音则明确不可用)。再次按住会取消旧通话、停止旧朗读;仅当旧任务仍是该设备的同一任务时中断主 Agent,不重发旧任务。简单能量 VAD、30 秒输入、8 包队列和包序号限制用于约束原型;断线、全部停下、席位失效、解绑会清理通话。

音频和字幕仅在手机与主机端解密;云中继仍只转发 端到端加密数据。本机 ASR 凭据留在主机,手机不接收;原有按住录音、转文字、语音附件和审批继续使用。旧主机不显示入口。

验证边界: 合成 ASR/model 的通过不等于真实模型可用。Qwen 服务的 WS 消息格式、真实主 Agent 的逐 token 回复、真机可听见的 TTS 和生产端到端延迟均为 NOT_VERIFIED。现有 Agent 适配器给出完整文本块时,原型只能在块到达后分句,不承诺 token 级延迟。开发测试使用假 ASR/model 和拦截的浏览器 TTS,不能据此声称完成生产实时通话。

托管后台任务

agentj busy run --detach --report REPORT.md -- <命令…> 登记一次性后台任务。busy run 按资源容量等待、降低子进程优先级,并核对明确指定的报告非空且退出码为 0 后才标记交付。管理器返回失败不自动重试;隔离会话拒绝可能逃出沙箱的管理器启动。当前会话 sandbox/approval 策略无法核验时,当前版本拒绝原生 AI 编程工具和 shell 包装的脱离启动;这些任务继续使用会话托管派单。十分钟没有观察到输出或有界工作目录元数据变化时记录 stalled;不会杀任务,也不会据此获得自主唤醒权限。未知结果先核对,不自动重放。

登录救援会填入或替换登录凭据,属于明确指纹清单;每次发起都要当场验证,不复用五分钟内的旧验证。

本机补丁只读检查

agentj local check(可加 --json)只读盘点 ~/.agentj-local/MANIFEST.json。没有清单时不会创建目录;损坏、越界补丁和断链会明确显示。它不会应用补丁、修复链接或联网查工单;pending_review 表示仍待人工核实,present_unverified 只表示链接目标存在,不表示兼容。当前不提供 reapply;relink 只恢复明确登记的主人自定义 Codex 技能入口。升级后的现有 doctor 自检会自动只读盘点;清单问题只报告警告,不阻塞已核实的升级。Father 官方已修证明仍待实现。不要据此声称旧功能已恢复。

卸载广场技能或工作流

请求主机卸载广场包;同名装在多个 AI 编程工具时,必须指定要卸载哪一个。加 --preview 只读预览,不弹卡、不移动。主机核对原安装记录、完整文件与目标后,在已配对手机上显示“卸载广场包”:批准后将目录原子移到本机私有可恢复备份,保留发布方信任与安装历史。拒绝、超时、失效签名、目标变化或断链不会卸载;结果未知时先查看清单,不能盲目重试。

卸载命令

agentj plaza uninstall <包名> --harness <claude_code|codex|opencode>

仅支持文件保持原样的技能/工作流;卡片包、修改过的目录、非本机管理的目标及跨磁盘备份会拒绝。备份引用留在本机卸载历史,重新使用仍走正常广场安装确认,不恢复旧授权。该动作不会终止已经运行的进程,也不会撤销发布方信任。

保存本机补丁或独立功能记录

agentj local record --contract FILE --json 经已配对手机当场核身、明确同意后,仅保存私有记录。首版支持 Linux 上可核实为完整权限的当前 Codex 会话;项目内写入、只读或权限未知时拒绝,手机确认不会提高原生权限。Host 自己确定当前运行包的代码根目录,调用方不能另选安装目录。本命令不应用补丁、不恢复链接、不执行清单命令,也不向客服发送内容。

补丁合同只含 kind: "patch"、files(包内相对路径)、baseline_root(本地文本基线绝对目录)、baseline_sha256(各文件预期 SHA-256)、description、validation、rollback、father_ticket(字母、数字或连字符)。基线明确标为主人提供的本地 SHA-256 证据,不冒充官方发行包或官方已修证明。只收行尾完整的 UTF-8 文本;保护路径、软硬链接、二进制、超限或含秘密输入一律拒绝。私有目录保存统一 diff、基线原字节和说明,清单仍是待人工核对。

独立功能合同只含 kind: "feature"、source(包外代码目录绝对路径)、entry(运行包内相对挂入点)、description、validation、rollback。仅登记当时的源文件摘要和预期符号链接,不创建入口、不把外部代码拷进安装目录;真正恢复前,local check 仍可能报告断链。

记录位于仅主人可访问的 ~/.agentj-local/,使用 pN/fN 编号。清单中的文字既不是可执行命令,也不是官方修复回执。批准后文件发生变化会拒绝;发布结果不确定时保留私有恢复数据并报告 record_recovery_required,应核查后再决定,不能自动重试或删除未知文件。补丁应用和可信 Father 已修版本查询仍未提供;旧版任意安装相对入口也不提供恢复。

恢复主人自定义 Codex 技能入口

新登记记录的字段

新登记时,合同只含 kind: "feature"、entry_kind: "harness_skill"、harness: "codex"、skill_name、source、description、validation、rollback。

技能名必须是非保留包名,与 SKILL.md 的 front matter name 完全一致,不声明别名。Host 只通过现有 Codex 全局技能根派生 ~/.agents/skills/<技能名>;这是主人自定义全局技能,不是内置或官方技能。源代码必须在原版、当前运行包和全局目标树之外。旧版任意安装相对入口保持只读,不猜测迁移。

agentj local relink fN --json 逐项核对登记记录、源文件原字节摘要、inode 代际、主人归属和权限。全局技能父目录须已存在且为安全真实目录。现有广场包、保留的卸载/审核历史、发布方信任和已登记技能名/别名均不能被覆盖或冒充;相关证据损坏或不可核实时拒绝。入口缺失时,须在当前完整权限的 Codex 会话中,经已配对手机重新核身、明确同意。已有正确链接只读返回 already_present、modified:false,不再弹卡;其它占位保留并拒绝,不替换、不删除。

linked 只证明这个精确链接已经创建并核验;functional_verified:false 表示未运行功能代码,也未执行说明中的测试/回退文字。应与主人核实实际行为后,再宣称功能修好。源文件改变,包括原字节相同但 inode 更新,都须重新登记。结果不确定时保留已批准链接、未知对象及私有 prepared journal,并报告需恢复核查;先查清,不自动重试或清理。仍仅支持 Linux/当前完整权限 Codex。reapply 仍不提供:任意登记包内文件可能涉及冻结的信任代码,也没有可信主机功能验收映射;语法编译不能代替修复验证。

花费、学习和朗读设置

在 Agent J 主机运行 agentj usage 查看耗时、用量和花费汇总;读数缺失时不猜,订阅额度不当作美元账单。详见用量和速度。

/learn 技能蒸馏目前尚待主人决定后启用,创建草稿和提交提案会被拒绝。保留的设计要求展示完整提案差异,由已配对主人确认后才写入;发布到广场另行审查。

按住回复上的朗读按钮,可以请 Agent 帮你设置声音。先看 agentj voice status,选择可用引擎,只通过密钥卡填 key,再听一段试听。自动调用模型改写朗读稿目前关闭;云端朗读会先检查包含主人前缀的完整文字,再发给所选服务商。详见选择朗读声音。

A guide to the phone screen. For installation/pairing, start with Install and Using your phone.

Ask Agent J "what does this colour mean?" or "how do I send a file?"; it reads this guide.

Agent not replying and you only have your phone?

No reply / “Not yet received”? Use your phone; after each step send a short test message and stop when answered:

  1. Tap Stop to interrupt the current task.
  2. Open Settings → Emergency repair → Terminal Commands, tap Run beside agentj doctor --reconnect (recommended); confirm with Face ID when asked. The phone requests host repair without opening a terminal.
  3. Still no reply? In Emergency repair, tap Restart service (recommended); wait for reconnection and retry.
  4. Still no reply? Tap Emergency repair → Restart Agent (host and web 0.25.2a1+). It ends the stuck process, tries the same conversation, or keeps it and opens a new one. Skip if an older version lacks the button.
  5. Still stuck? Tap Emergency repair → ② Ask Agent J Father for remote help; keep the ticket number. Only your tap sends host-redacted diagnostics, never passwords, keys, chats or work files.

Stopped by the model's safety check? No computer needed either. With Claude Code the phone shows a card to pick what happens next: continue on the fallback model, retry as is, "Edit and resend" (your words go back in the message box) or "New conversation".

Check quota first. In phone Claude settings, check Usage. Use Free reset only if offered (not every account/limit); otherwise wait until the displayed reset time. After quota recovers, persistent “Not yet received” needs the five steps. Restart/reopen adds no quota. Expired sign-in needs AI login rescue.

Grey/disconnected: wait a few seconds for a brief drop, check phone networking and “Try now”, then Settings → Emergency repair → ① Reset connection, followed by ② Ask Agent J Father for remote help if needed. Commands/restart/session repair need the host or rescue helper online; they cannot force a powered-off, sleeping or offline host. Still unreachable? Use phone support chat or feedback@agentj.app: symptom, versions, time, never credentials. No computer visit needed.

Agent J Father is support from the developers. Once chat works, use /feedback-to-agentj-father; otherwise use the phone controls above.

First use: two remotes and the first message

The installing Agent binds the Agent J host to your seat, then pairs two required remotes:

  1. the Agent J host's browser: open https://m.agentj.app/ on the Agent J host and pair it. It is the quickest, and the big screen makes every step easy to follow.
  2. Your phone remote: the one you carry every day. Add the page to the Home Screen first, then pair from that icon.

Other phones, tablets or computers can wait: when you want one, tell Agent J "pair another one" and it walks you through.

Every remote is connected to the same Agent and shows the same conversation: start on your phone, carry on in the browser on the Agent J host. Remotes are for one person's devices; a colleague who wants in gets a seat of their own, the way everyone in an office gets their own desk. See Seat, Agent and host. Several people can share one computer too, one seat each: see One computer, several people.

On the first remote, the first message comes from Agent J itself: it introduces itself as your chief-of-staff assistant, the single entry point between you and every workflow and agent, and suggests you talk to it in this window from now on. Then it shows you the window in a few small steps — the screen colours, the quota lines and the water level, voice and attachments, the approval card — and finally which remote is still missing. Reply "ok" or "next" for the next step; say "skip" to stop.

The welcome is sent only once. Every remote you pair later just gets one line: "This … is connected too". Until both required remotes are paired, Agent J may mention the missing one in a sentence at the end of a reply; once both are done it stops. On the Agent J host, agentj onboarding shows the same.

Background colour: what the Agent is doing

The colour of the whole screen tells you one thing: the state of the main Agent on the Agent J host. Other agents it runs in the background, and scheduled tasks, never change it.

ColourMeaningWhat you do
GreenWaiting for youSay something whenever you like
Blue, with a light running along the topWorkingWait — or keep sending; messages queue
Orange, edges pulsingAn action needs your approvalRead the card, approve or deny
PurpleA question for youPick an answer, or cancel it and type
GreyNot connected to the Agent J host, state unknown, or everything is stoppedRead the line at the top

Green: waiting for you

Blue: working

Orange: waiting for your approval

Purple: a question for you

Grey: the Agent J host is offline

  • The icon in the top-left corner follows the state too. Tap it to change the text size (medium → large → medium → small); hold it to jump to the first unread reply ("No unread" when there is none). The size is remembered on this phone and survives a reload.
  • With the message box empty, press and hold the grey Send button: a send-sound volume slider grows up out of it. Slide up for louder, down for quieter, and let go to keep it.
  • The small line at the top says the same state in words.
  • The phone gives a short buzz whenever the state changes.

Three lines: quotas and context

  • The thin line under the top bar (marked weekly): how much of your AI plan's weekly quota is used. Longer = more used.
  • The thin line above the message box: the 5-hour quota.
  • The rising water with waves in the background: how much of the context — what the Agent can keep in mind at once — this conversation uses. Higher water = closer to full. After a compaction the water drops to the bottom.

Tap either line (or the number next to it) and the "Usage" box opens in the middle of the screen with the exact numbers, for example week 58 %, 5 hours 34 %, context 64 %, and how long ago they were reported. "Got it", a tap outside or Esc closes it.

The day in brackets after the weekly figure is where you are in the 7-day reset cycle. The Usage box also has a "Reset cycle" bar with how long until the reset and when, and a small line under each quota with how much you will have used by the reset at the current pace. The figures do not glow normally: the weekly one glows faint blue when it is used faster than the even pace (about 14% a day), and its used part turns light blue in the box; anything at 80% or more glows soft orange, at 90% or more orange-red — little is left. Providers that do not report a reset time show no day.

Both quota lines are always there, doubling as the page's top and bottom dividers. A line with no text beside it has no figure right now, usually because ① your plan has no limit for that window (for example ChatGPT Pro at $200: OpenAI reports only the weekly window and a credit balance, no 5-hour window), ② the provider offers no usage query (for example the Volcano Ark and Alibaba Bailian Coding Plans — check their consoles), or ③ the figure is temporarily unavailable. None of these affects normal use; the text appears by itself as soon as a model or AI coding tool reports it.

Water past half: the level in the background is above the middle

The water is past half — what now?

When the context fills up, the Agent starts to forget the earliest details. Once it is past half, Agent J mentions it once at the end of a reply (once per conversation).

  1. When it suits you, say "compact", tap /compact in ≡ (all commands), or send /compact.
  2. You don't need to prepare anything. Before compacting, Agent J has the Agent write a handover file — what it is working on, decisions made, to-dos and the file paths it needs — and only then compacts.
  3. After the compaction it reads the handover first and carries on.

If the handover could not be written (say the Agent was stuck), the compaction still happens and the phone tells you in one line.

The handoff path is fixed and copyable from the phone: ~/.local/state/agentj/handoff/compact.md in shared mode, <work folder>/.agentj/handover/compact.md for Agent J's own main conversation. If you send nothing after a compaction, Agent J itself reminds the Agent to read the handoff and carry on. In shared mode the phone shows one line about it only after the Agent has actually read the handoff file. See the compaction and handoff page.

/clear starts a new conversation. It asks first, and you can undo it until you send your next message; once the new conversation has begun, the button turns into a short "The new conversation has started — too late to undo (the old one is saved on the Agent J host)" line and the old one stays on the Agent J host. To keep your progress, use /compact, not /clear. Status lines such as the new-conversation greeting address you as "Chairman" by default; change it with agentj config set owner.address Alex.

For OpenCode, the water level uses the model’s reported context limit first, then a built-in model table. If neither is available, it uses 200,000 tokens, based on the free DeepSeek Flash window. This display default is not a provider capacity guarantee. Used tokens still come from OpenCode; no reading is invented before usage arrives.

Heartbeat: the Agent checks in by itself

After a quiet spell (default 60 minutes), the Agent J host checks local records first. If it finds nothing to handle, it writes one log entry without calling the model. When something needs attention, it wakes the main Agent with the reasons. Only information or decisions you need reach your phone. Say “check every 30 minutes”, “wake up every morning at 7:30” or “stop waking up on a timer”, or use Settings → Heartbeat to change the interval, daily time and quiet hours (23:00–07:00 local time by default); tap usage in the top bar to see heartbeat consumption. Large context or a recognised expensive model pauses automatic heartbeats and prompts you to compact; it does not clear the conversation. See the Heartbeat page in the docs.

Webhooks: outside services reach you

Every seat comes with webhook addresses (hook.agentj.app/…). To have a video job, Stripe payments, GitHub or server alerts notify you here, tell the Agent in one sentence, for example call me back when the video is done. A resident hook only starts receiving after you approve its card on the phone. The Agent treats what arrives as data only: as expected → it carries on; needs you → it asks with options A / B / C and a recommendation; spam → it ignores it. On the phone, Settings → "Agent tools" → "Webhooks" lists the live hooks (pause, resume, revoke, copy the address), today's count and "Recent deliveries" (up to 50, with the Agent's triage). Secrets are never shown on the phone. See Webhooks.

One message per page — swipe through them

Your words are above the Agent's reply. Swipe right for older pages, left for newer; the corner shows page/total. Flick as your finger lands to turn; hold for a third of a second before dragging to select text. Selection and its handles never turn pages. The name, load line and robots stay pinned while a long reply scrolls.

The header has three equal parts: double-tap the left third for the oldest page, or the right third/page number for the latest. A pulsing badge in the middle counts unread replies: tap it, or press u on a computer, for the first unread; page forward until the badge disappears at the latest. With none unread, the middle does nothing. Reading on any remote clears that reply and earlier unread hints on the others; an offline remote syncs before showing hints again. Existing replies count as read after an upgrade (no initial 99+), and unsynced read acknowledgments retry automatically. Exception: a remote viewing an older page keeps the new reply's pulsing page number and badge count until you reach it there, even if read elsewhere. Silent turns never count.

Reading an older page preserves both page and scroll position when you send or receive a message. A new reply only pulses the top-right page number; page forward when ready. Sending opens a new page only if you were already on the latest.

The buttons under a reply, left to right:

ButtonWhat it does
BookFull-screen reading (or double-tap the reply), with a text-size control
SpeakerRead it aloud with the phone's own voice — the text goes nowhere else
ArrowShare it through the phone's share sheet
Two pagesCopy the whole reply
Curved arrowReply to this one; the quote appears above the message box

Select reply text to quote it. New selections add (not replace) up to five quotes from any reply, including while paging or full-screen reading. Above the composer, tap words for the full quote, its time for the highlighted source, or ✕ to remove it; the final ✕ or Esc clears all. The clipboard holds your latest selection.

A sent message with two or more quotes folds them into one row, as in the composer: count, first quote's start and number remaining. Tap to expand all (each still links to its source), then tap the top row to fold. Single quotes are unchanged.

The white round button at the reply card's bottom left (a broken ring with an outward arrow) shares a web report. Tap to prefill /web-page-report with the cursor after it; nothing sends. Add instructions — "only the pricing part, for people at my company, open for a week" — or send as is. The Agent asks scope (conversation, topics or this reply), access (any link holder, code, company e-mail domain or any e-mail sign-in), expiry, and whether to hide names/numbers; answered choices are not asked again. An older reply is included as a quote. If the skill is missing, the Agent first asks to install it from the plaza.

Hold that button for the Hot key sheet: current binding/action, then a searchable list of every 「/」 menu command and skill, including your commands. Pick one and tap Bind it; the icon stays unchanged. A command such as /status or /compact runs on tap, but destructive /clear still asks — bindings bypass no confirmation. A skill prefills the message box; add words and send to run it on that reply. Back to default restores web-report sharing. Ask the Agent to change it, or run agentj config set ui.card_hot_action status at the Agent J host.

Hold the Agent's name at the reply card's top left to rename it (agentj name at the Agent J host); both screens update. Dancing pixel robots at top right represent background workflow CEOs/helpers: new work adds one; finished work bows and floats away. Phones show six, then +N. Tap for a centred square listing the count, supervisor, robot, name and full task title (ellipsized if long). A row opens that Agent's read-only card: location, elapsed time, latest step and, for background dispatches, report path/first line; Back returns to the list. Claude Code, Codex and OpenCode sub-agents appear even while the main Agent is replying. Missing robots mean unregistered work: ask the Agent to use agentj busy run. "Change the look" at the bottom sends your customization request; the Agent asks how to change robots, colours, logo or Send, then validates the theme before applying. Holding the robots does the same. Esc/outside closes. See Background robots for the gallery and display rules.

The thin grey load line below the name has a pale segment sweeping back and forth, faster when the Agent J host is busier; if it races and your message can wait, pause. Tap for overall load and five rows: CPU, memory, GPU, disk (read/write activity and space left), network (traffic per second). An absent/unreadable graphics card shows "— (not detected)". Measurements run every 2–3 s only while this square is open, stopping on close. Idle/normal/busy sweeps take about 6/3/1 s; disconnected phones show a still line.

Replies are laid out for you:

  • Code: syntax highlighting, sideways scrolling for wide blocks, top-right copy button. Tap shaded inline code to copy ("Copied") for terminal pasting.
  • Maths: LaTeX formulas. Commands ($HOME, $(…)) stay literal; system cards such as goal results show no formulas.
  • Diagrams: mermaid pictures.
  • Images, audio, video, PDFs, web pages and files inside the working folder appear in replies. Enlarge images, play audio/video, preview web pages in a script-free frame. Each file has preview/download/share/email/Telegram icons. Small visible files load automatically; large files need a tap with size shown. Data saver/cellular never auto-loads. Full-screen previews support PDF, docx, xlsx, CSV, Markdown, code and text; unsupported kinds such as PowerPoint offer download. On a computer, Space previews a selected card; Space/Esc closes. Left/right arrows or phone swipes move among files in the same reply, with position/total on the top bar; one finger pans a zoomed image instead. Downloads retain names (Chinese, spaces, emoji), with a browser-download confirmation; the iPhone Home Screen app opens the share sheet — choose Save to Files.
  • Too-large/outside-folder files get a reason instead. Both the configured root (even after cd into a subfolder) and the current folder count. Scripts/source (.sh, .py, .ps1…) are text cards: preview/download, never run. A suspected key's notice gives its line and only its first two characters. Audio/video/images always send regardless of Chinese, underscores or long names. Credential files (.env, .pem, private keys) and text holding real keys use a phone secret-pickup card (Face ID), never ordinary attachment; if unavailable, the notice explains why and how to retrieve it. External image links never open automatically.

Tap a recognized short value in a reply—an email address, Agent ID, @handle, account ID or a domain such as example.com—to copy it; other links open normally, and holding reply text still selects it.

For a local image, write a complete [label](absolute-path) reference, optionally prefixed with !. Both forms accept absolute paths and ~/. Receipt of the complete reference starts preparation while work continues; the slot shows progress/failure until the file card is ready. Path, type and secret checks still apply.

In an admitted live owner phone turn, ask the Agent to run agentj file show PATH --label LABEL --json as a standalone Bash command to attach to that page. No live owner turn, including a standalone desktop turn, means no outgoing message. queued is pending; later FILE_SHOW_RESULT says attached_to_page or failure, neither proves viewing/downloading. Isolated Linux processes/real Chromium passed with a synthetic image; physical phones, macOS, WSL and real Claude Code/Codex/OpenCode model sessions remain untested. No accepted Kimi/Qwen ACP integration; Windows requires WSL.

Absolute or ~/ PATHs must remain in the admitted working root. Failures: broker_unavailable — attachment service unreachable; no_owner_session — owner turn/context unconfirmed; native_admission_missing — no admission for this exact request; native_admission_expired — admission expired; native_admission_ambiguous — multiple valid matches. None attaches a file. If the current turn is still active, have the Agent run the attachment command on its own. If the turn has expired or cannot be verified, send a fresh message in the same session from your paired remote.

To send one local image or file explicitly to your own bound WeChat during the current admitted owner phone turn, run agentj file send PATH --to wechat --json as the whole Bash command. The destination cannot be chosen or changed; no group/friend/account/URL argument is accepted. The file must be inside the admitted work folder and pass existing type, no-symlink, digest and secret checks. The limit is 25 MiB per WeChat file (existing media-type caps may be lower); this is one file per command, not a 24-file batch interface. Existing page attachment limits remain 24 items / 100 MiB. queued only means pending native completion; wait for FILE_SEND_RESULT: sent_to_wechat with platform_accepted:true means the platform accepted it, not that the phone displayed/downloaded it. failure may be an uncertain delivery; check WeChat before explicitly retrying. A changed binding/context/owner execution stops sending; do not use this command to bypass a failed file show, approval or file check.

A picture, a formula and highlighted code in a reply

Further down: a diagram, a file to download and a line about a file that was not sent

Search the chat

The magnifier and search shortcut search the page you are on: chat history in the conversation, cards in Workflows, Skills, Memory and Agent J, or the current text in Settings, a menu page or an open document.

The top-right magnifier beside Settings (⌘K/Ctrl+K on computers) opens a centred dark search card for messages, quotes, attachment names and replies together. Space-separated words must all appear; case, full-/half-width and Traditional/Simplified Chinese are equivalent.

Best-match order favours more hits, your messages, starts/first lines, whole phrases/exact matches, then recency; or choose "Newest". Results show sender, time and highlighted snippets. Phone-cached pages appear immediately; older pages from the Agent J host follow shortly.

Tap a result to close the card, open that page and flash it once. Reopen for the same results/scroll position. Up to 20 searches are kept as pages: swipe sideways or use ←/→/‹/› on a computer; the top says "Search N of M: words". Stored only on this phone and encrypted like drafts, they clear with /clear or unpairing.

On the Agent J host: agentj history search <words>.

Sending messages

  • Type and tap send, or press Enter. Until the Agent has it, you can cancel the send.
  • You can send while the Agent is busy (blue); messages wait their turn.
  • It works offline, too. With no network, send as usual: the message is kept encrypted on this phone and the page says "Will send when you're back online". When the network returns, queued messages go out in order, never twice. Even if the Agent J host restarts, a message is never run twice: one it hadn't finished is marked on the phone with a line saying so — send it again yourself if you still need it.

Two messages sent offline wait above the message box

  • Type / at the start of the box to see the commands you can use; a few more letters filter the list. It also lists the current coding tool's own commands (Claude Code, Codex or OpenCode); a name Agent J also has shows once (Agent J's). All of them can be picked and typed: the ones marked “runs directly” go to that tool as typed (/init, /review); the ones marked “the Agent does it” change a setting or need the terminal screen (/config, /mcp), so Agent J hands your wish to the Agent, which carries it out through the usual confirmations and tells you how it went; the few grey ones (/exit, /login) show guidance instead of running directly; continue sign-in through AI login rescue on your phone. Switch tools and the list follows. A picked command (or a card or workflow picked with @) gets one space after it with the cursor behind it; the box keeps the focus until a message has really been sent.

The message box: always one line, full screen for long text

  • The message box is one line tall and never grows; with several lines you can scroll inside it, and the fifth button above it (full screen) shows how many lines there are (for example 5 lines). Shift+Enter adds a line, Enter sends.
  • In a wide window on a computer, the cards and the message box widen with the window instead of stopping at a fixed width.
  • For long text open the full-screen editor: tap the fifth button, press Ctrl+G, or on a phone swipe up on the message box. Dark background, light text, the whole screen to write in; when the phone's keyboard opens, the text and the buttons below it move up above the keyboard.
  • In full screen: the top-left icon leaves (so do Esc, Ctrl+G again, a double tap on blank space — on words a double tap still selects — and pulling the bar at the top centre down; not far enough and it springs back), and the words go back to the message box as they are; the top-right icon clears everything, with 5 seconds to undo; the slash icon at the bottom left opens the command list and puts the one you pick at the cursor; Send is at the bottom right, or press ⌘/Ctrl+Enter. In full screen Enter only adds a line.
  • Terminal habits work in both the box and full screen: Ctrl+A / E line start and end, Ctrl+U / K delete to the start or end, Ctrl+W delete the previous word, Ctrl+Y paste back what was deleted, Ctrl+D delete the next character, Ctrl+J new line (a \ at the end of the line, then Enter, does the same). In the box, Ctrl+S puts the draft aside (press again to bring it back) and Ctrl+R finds a message you sent that contains these words. All shortcuts: Keyboard shortcuts.

Sharing a Codex App session

While the Codex App holds a session, the phone follows its actual model from local records and shows read-only status. A native active-writer refusal leaves the message undelivered and never automatically starts another thread. Quit the Codex App completely, then resend to try continuing the same thread; switching to New chat or waiting for a reply does not guarantee release. Do not promise concurrent writes from separate clients, delete writer locks, inject the App’s private pipes or change permissions.

When the phone says another program is using the session, it says which one: an Agent J leftover background process is cleaned up automatically and your message goes on; the Codex inside the ChatGPT App, the Codex App or a codex in a terminal must be quit first; if Agent J cannot find out, it tells you so.

Codex permissions: directly on the Agent J host by default

With Codex, as long as you never wrote sandbox_mode at the top of ~/.codex/config.toml, Agent J lets it work like you do in your terminal: network, installs, files in your home folder. Risky actions (spending, deleting, sending, keys …) still wait for your approval on the phone.

  • If you set sandbox_mode yourself (for example workspace-write), it stays yours; anything beyond it is refused, and the notice says how to open it up.
  • sandbox_mode must be at the top of the file (before the first [ ]). Appended at the end it usually lands inside the last [ ] table, where Codex ignores it. /status on the phone or agentj doctor on the Agent J host then says "written but not in effect". Just ask the Agent: it uses agentj codex-sandbox, which writes the right place; after an Agent J restart the same conversation follows the new setting at once.
  • When continuing a Codex App session, that conversation's own permissions in the Codex App apply; if you never chose any there (still the default), the rule above applies. Refused because of permissions? Set this conversation to Full access in the Codex App, then resend from the phone.

Attachments: files, photos, camera

Attachments and a quote above the message box

  • Three buttons above the message box: file, photo library, camera. You can also paste an image, or drag files in on a computer browser.
  • Hold "File" to paste the clipboard's text at the cursor. Into an empty box, text over 2,000 characters becomes a .txt attachment; if the box already has words, it goes in unless together they pass the single-message limit, and then only the pasted part becomes the attachment. Hold "Photos" to add the clipboard's image as an attachment. An iPhone may first show its own small paste bubble — tap it.
  • Up to 10 attachments at a time, 200 MB each, of any file type. Recordings and videos are transcribed on the Agent J host and the Agent gets the original too. Pasted text follows the same rule: words already in the box → it goes in unless the total passes the single-message limit; an empty box → over 2,000 characters becomes an attachment.
  • Attachments travel encrypted straight to the Agent J host, into the Agent's working folder, and other attachments are removed after 30 days. Originals of phone recordings and Telegram and WeChat voice messages are kept for 24 hours by default. Change this in Settings → Reading and voice → Voice original retention (0, 1, 6, 24, 72, 168 or 720 hours; 0 means no automatic cleanup).

Voice: tap to lock, hold to talk and release to send

Hold to talk: recording

  • Hold the microphone and speak; release to transcribe and send automatically. Long recordings send as attachments. To cancel, slide clearly off the button (about 80 px away, or up by more than a button's height) and let go there; a shaky hand or a small move does not cancel, and sliding back keeps recording.
  • Tap or double-tap the microphone to lock recording. Wait half a second, then tap again to finish; review the words in the message box before sending. Keyboard m still releases to text and double-m still locks.
  • Speech is transcribed on your own Agent J host by default. In Settings → Speech-to-text, you can instead choose a configured provider or your own endpoint. The host sends recordings to the service you select; we do not receive them.
  • You can save an unauthenticated custom endpoint directly on your phone: enter its address and model, and leave the key name empty. For transcription that needs a key, ask your Agent to configure the endpoint, model, provider and key variable name on the host. Those bindings cannot be saved directly from phone Settings; the page explains that they are not saved and asks you to have the Agent configure them. Enter the secret value only in Open secret card, never in chat. Opening that card does not bind the transcription settings. Check a short recording after setup.
  • Successful remote transcription does not load the local speech model. If the remote service fails, Agent J automatically tries the installed local model for both short recordings and long voice attachments. A successful recovery shows “Remote transcription is unavailable; the local model transcribed this recording.” The attachment notice stays visible when its transcript is folded. Transcription is marked failed only if both routes fail; the original recording attachment remains available.
  • Enter one speech hotword per line. Defaults include Agent J, Olares, Claude Code, Codex and OpenCode. Remote models receive these as a prompt; support depends on the model. Built-in SenseVoice has no native hotword prompting; your Agent can configure exact word replacements with voice.asr.corrections.
  • The recording card shows whether this take becomes text or a voice attachment, with the current threshold. It follows the message box capacity, between 20 and 90 seconds. Longer recordings send as attachments and receive their transcript afterward.
  • To have every reply read aloud, turn on auto-read in Settings.

When you send only a voice note, the computer's transcript comes back onto your message card once it is ready: folded, the card shows what you said; open, it sits under the voice attachment (it folds away, and a long press selects it). If transcription failed, the card says why. Every remote and your history show it too. The copy icon just left of expand / collapse at the card's bottom right copies the whole message in one tap (for a voice-only message: the transcript).

≡ All commands

All commands

≡ to the left of the message box opens all commands; tap one to run it:

CommandWhat it does
/compactCompact the context (writes the handover first, see above)
/clearClear the conversation (can be undone)
/newSame as /clear (the name Codex uses)
/modelSee which models you can switch to; /model name switches
/contextHow much context is used
/costWhat this conversation cost
/usageHow much of your plan is used
/statusThe current state
/stopInterrupt the current turn
/helpList these commands
/resetReset connection: the same as Settings → Emergency repair → ① (below)

The two commands in the "Friends" group are put into the message box when tapped; finish them and send:

CommandWhat it does
/my-agent-idthe Agent J host answers with your Agent ID (tap the code block to copy it), the share link and an "Open my card" button; never goes to the AI, costs no tokens
/add-friend ID [note]Add a friend: signed by this phone like "Add friend" on the friends page; a mistyped character is caught at once; without an ID it opens "Add friend"

In the "Run now" group, the command to switch the AI coding tool (/switch-harness) goes to your main Agent with one tap; you can also type it in the message box, add "switch to Codex" after it and send it. It does not switch at once; it goes to your main Agent, which says which kind of tool it means, scans which ones the Agent J host has, tries each one's sign-in with a quick headless call and tells you which ones you can switch to. It switches only after you confirm. The remote disconnects for a few seconds and reconnects by itself, then the new tool introduces itself; if it does not come up, Agent J switches back by itself and tells you why. See Switch AI coding tool. Want commands of your own? Tap /customize in the list, or press and hold ≡: it sends the Agent a message from you asking to customize your slash commands; it lists the current ones, asks what to add, remove or change, and only switches the change on after it validates.

Before switching, the tool you use now writes the conversation's key points into a handoff file; the new tool reads it first, then carries on. If no handoff is written within three minutes, the switch continues with a redacted local excerpt of recent requests and replies. The phone says it is using an excerpt, which may be incomplete; the new tool checks any missing progress with you.

The menu also has the Agent's own skills. Other commands, such as changing settings, are for the computer. See Agent friends.

The model and effort at the top, the model always with its version (such as Opus 5.5), as in the terminal's status line: tap to switch to the next one, hold to go back to the default. Taps only change the label: a half is switched once you leave it alone for 5 seconds (meanwhile it fades, with a thin line running out underneath); tapping back to the one in use sends nothing. Holding for the default and typing /model name take effect at once.

Cards that need you

Approval card (orange)

Read which task needs this step and what it will do, followed by the source channel, time and first two lines of the original message. Tap the source to open and highlight that message; the card folds away. Beyond the latest 500 messages, the verified initiator and task record remain. A missing initiator is clearly marked for investigation.

  • Tap Confirm with Touch ID or Confirm with Face ID for an action requiring owner verification; ordinary cards keep their own confirmation method. Commands are folded under Command details, which can expand or open full screen. Approval covers only the exact operation and limits shown.
  • Tap I have a question to leave the operation unexecuted and ask the main Agent for an explanation in chat. The background is blue while awaiting the reply, green afterwards. Reopen for my approval under the explanation or the heartbeat dot returns to the card; you still need to approve. Expired requests need revalidation and a new application, never revival of a denied or unknown-result operation.
  • Tap Deny to invalidate the request and dismiss the card. The main Agent explains which step cannot proceed; for a suspicious source it helps investigate without automatically pausing a channel or changing credentials.
  • Tap Collapse at the top right or press Esc to keep the request pending. A Lotion circle with a Peachy heartbeat dot replaces the web-report button at the lower left of the reply card; tap to reopen. Multiple requests show a count. Chat returns to its usual blue or green; orange appears only while the approval card is open.
  • Expiry means no approval. Collapsing, reading the original or asking a question never extends the deadline. Approval returns you to the latest message. With no remote online, the existing pending period of up to 30 minutes applies while the Agent continues independent work.
  • Before a task starts, the Agent estimates how many confirmations it needs. One task approval covers only listed exact steps, objects, recipients and limits: at most 12 steps for 600 seconds, each once, ending with the task or authorization. Scope changes ask again. Secret pickup and approval or pairing trust-root changes still verify each time. A password or key appears only on the remote that completed owner verification, never on the initiating remote or in chat.

Stopping, expiry, task completion or a host restart never restores execution under an old approval. Temporary-token reconciliation keeps only private metadata on the host, never token or authentication secrets; unknown creation or revocation results are not automatically retried. “Expired as requested” is not provider confirmation of revocation. Ask the Agent to check status with agentj friends action-recovery; it only lists records. Actual verification or revocation needs your fresh confirmation in a new trusted task for the recorded official object; no object ID means no blind creation or deletion.

E-mail: mail only to yourself goes without a card. Mail to anyone else has a one-tap confirmation card. Each new recipient on the card has an unticked "Handle mail from them directly from now on (add to the allowlist)"; tick it and approve, and they join the allowlist — their mail to the Agent is handled directly; mail to them still asks you.

Computer Use: when the Agent wants to click and type for you in your main conversation, tap once to approve; Codex sends these to the phone too. Actions requiring owner verification still ask for it. The card has "Don't ask again for Computer Use approved from this remote", unticked by default; tick it and approve, and the same kind of action from this remote goes ahead without a card. To undo it, tap "Ask again" under Settings → Safety → "Actions that skip approval"; unpairing that remote or the emergency stop also undoes it. Red-line actions can never skip approval.

When a request is not approved, the card and the Agent say why (waited too long, the passkey check failed, no remote was online, emergency stop) and what to do next.

Ordinary tools follow the AI coding tool: Agent J adds no card to allowed actions, and native permission prompts use ordinary Confirm, Deny and I have a question buttons without fingerprint verification. Only commands and matching phone operations on agentj uv list require the owner to verify in person on a paired device. This covers secrets, device and passkey trust, approval and security settings, and registered high-risk functions. Background, heartbeat, recovery, webhook and mail turns follow the same native tool permissions; friend and visitor sandboxes remain. External content cannot approve a listed command. Register a fixed occasional transfer or deletion program with agentj fn add <name> -- <command> <args>; fn run <name> takes no extra arguments. Adding, running and removing each require verification; fn list is read-only. See Phone approvals.

No remote online: the card stays on the phone and the lock-screen alert goes out as usual. With Telegram or the e-mail channel set up, one content-free line also reaches your private Telegram chat and your own inbox (at most once every 15 minutes). After 20 seconds the Agent knows you're away and does other work; the card stays for 30 minutes, and once you approve, the same requester's next try of that step runs; "Stop everything" cancels an approval not yet used. More in When no remote is online.

Collapsed: the heartbeat entry stays at the lower left of the reply

Question card (purple)

The Agent wants you to choose: tap an answer and confirm. If none fits, cancel the question and type your answer. The card works whichever Agent runs on the Agent J host — Claude Code, Codex, OpenCode, Kimi or Qwen (agentj ask): single or multiple choice, sometimes with a short preview under an option. Pick "Other (I'll type it in the chat)", or "OK, I'll answer in the chat" on an open question, then type your answer in the message box. If the card did not really appear, the Agent never says it did. The words under an option show two lines; tap "… More" to read the rest. The Agent keeps option names to about 24 letters (12 Chinese characters) and the words under them to 120 (60).

When the model's safety check stops a message (Claude Code): no need to go to the computer. The first time, a question card asks what should happen from now on: switch to the fallback model and continue (and switch automatically next time), or stay on the current model; each choice says what it does. If you stay, the turn stops and your words go back into the phone's message box to edit or resend. After that, in a shared session a card offers four choices: continue this turn on the fallback model, retry this turn on the current model as is, "Edit and resend" (cancels the turn and puts your words back in the message box) or "New conversation" (cancels the turn; earlier context is dropped). In Agent J's own session you get a note saying how to go on.

One-tap answers: the quickest way to reply

A reply sometimes ends with a few rounded buttons, such as "Dispatch" and "Not yet". One tap is the same as typing those words and tapping Send: the message goes out at once as yours, and the Agent carries on. The group then greys out and says "Replied: Dispatch"; each group can be tapped only once. It also greys out when you have already typed an answer, or tapped on another remote. Talking about something else in between does not close it: page back and tap, and it goes as a reply that quotes that message, so the Agent knows which question you answered. When one reply has several groups of buttons (each line or list item is a group), you answer each group on its own; tapping one does not affect the others.

Buttons or a card:

  • One-tap buttons: the Agent only needs a quick decision, with a few options (2–4), and it is not urgent; the Agent does not stop to wait.
  • Question card (purple): the Agent must have your answer before it can go on, or it needs several choices, previews or your own words.
  • Approval card (orange): check its task source, then confirm, question or deny; complete owner verification when required.

Buttons appear only in the Agent's own words: anything that looks like one inside a quote block, in code, or in a system notice or scheduled-task result from the computer stays plain text and sends nothing.

A #tag in a reply (such as #release) opens Search chat history with every message that carries that tag.

Admin-password card

When the Agent needs to run one command as administrator (installing a system package, say), this card shows first what it's for, then the command and its effect. Type the Agent J host's admin password on the card. It travels encrypted and is used for that one command; the Agent never sees your password.

Admin-password card

The Agent J host can also remember it: tick Remember it with Face ID (next time, just scan your face) on the card once, and next time tap Fill in the password with Face ID. It is stored only in encrypted form on the Agent J host, and each device unlocks it with its own Face ID; on another device, tap Use it on this device too under Settings → Safety → Agent J host login password. What this protects against, and what it does not: Agent J host login password.

Key card

When the Agent needs an API key, this card says which key, what for, and where it will be stored. Paste the key; it is written straight there — not into the chat, and the Agent never sees it.

Key card

Tapping save (or Enter) with nothing pasted just asks you to paste the key first — it never counts as a no. "Don't provide" sits on its own line below and needs a second tap. The card stays valid for 10 minutes, even if the Agent's command is interrupted meanwhile: submit as usual and it is saved.

Getting your own keys or configs on the phone (pickup card)

To use something set up on the Agent J host on your phone — a proxy ss:// link, a config file with a password — just ask the Agent ("send me the SS link"). Ordinary replies hide passwords, so the Agent sends a secret pickup card instead:

  • The card stays hidden and shows only the name, purpose and size. Tap "View with Face ID"; only after that does the computer send the contents.
  • Copy text with "Copy", save a file with "Download file". Tap "Done" when finished and it is cleared from the page (automatically after 2 minutes too); the chat keeps a single "picked up" line.
  • It can be picked up once within 10 minutes; tap "Not needed" if you don't want it.
  • If this phone hasn't set up Face ID yet, tap "Set up Face ID" on the card first.
  • The card goes only to your own paired phones. Telegram, groups and friends still can't get these secrets.

Start card (long tasks)

When you ask for something that keeps running — "set up a weekly competitor brief" — your Agent checks what it can do and puts everything that is yours to decide on one start card: what it will do, where it delivers, how often it runs and at most five choices. Confirm and start confirms the brief and, when needed, turns the schedule on; Change something starts nothing. No keys go on this card, and confirming never approves paying, deleting or sending outside — those still ask you one by one. See Long tasks.

More in Admin rights and keys from your phone.

Messages from your automations

Your own scripts and timers can post a page to the phone with agentj notify. The page is titled "From your automation:" plus the automation's name; its images and files open as file cards. Each automation is off until you turn it on — in Settings under Automation messages, or agentj notify --allow <name> on the computer. A long task your Agent makes decides this when it is created; you can switch it in the same place; that page also has a master switch. Your Agent also gets a copy of each message and treats it as information from a script, not as your instruction. It summarizes success as FYI, explains failures and the repair arranged within existing permissions, and tells you clearly if it needs you. Only noise may stay silent. Your Agent itself can never post this way. See Long tasks.

Automations on a schedule

For work that repeats every day or week, your Agent uses the Agent J host's own scheduler by default (a systemd timer on Linux, launchd on macOS, Task Scheduler on Windows); at the set time it starts your AI coding tool headless. You design it together and run it once by hand; once you say the report is right, later runs don't ask again. Stop everything doesn't pause the timers your Agent made: to pause one, ask your Agent to switch its timer off. agentj tasks keeps working. For Agent J scheduled tasks you already enabled, your phone shows one host approval card, "Agent J host · Move to the system scheduler", after an update: approve it once (no Face ID needed) and they all move, and any whose test run fails goes back as it was; tap "Deny" and nothing moves and the card stops coming by itself; agentj tasks migrate can still send one, at most one per 24 hours after a Deny. A moved task no longer asks for approvals on the phone; isolation stays, and Stop everything stops it. Once you edit the task it no longer runs until you move it again. On the phone's "Scheduled tasks" page a moved task has "Move back" and "Move again". See Move existing scheduled tasks to the system scheduler. See Using it on the Agent J host.

Automations that email other people

A webhook or an Agent J scheduled task that must email someone other than you needs one grant. Say who it may email in your own chat; the Agent runs agentj automation grant and you confirm one card with Face ID. Mail inside the grant then goes out with no card. Mail to anyone else is not sent, and the Agent tells you the command that extends the grant. Public mailbox domains and public suffixes on the built-in list (such as gmail.com and co.uk) only work as exact addresses; the list is not complete, so check the domain on the card. Changing the webhook's auth method, source IPs, delivery target or note, or the task definition, Stop everything or a new sending mailbox voids the grant; renaming alone does not. Settings → Safety → "Automation send grants" lists them; "Revoke" works at once. See Webhooks.

Stop everything

In Settings → Safety, tap "Emergency stop all Agents" and confirm: the current work stops at once, every pending approval is denied, batch approvals are withdrawn and scheduled tasks pause. The screen turns grey with a banner on top until you resume.

Everything stopped

Settings

For first-run setup, open Settings → Agent tools → First-run checklist. Do not depend on a banner above the chat: it is absent before setup starts or after the host or this device closes it. Complete supported choices and approvals on the phone; an item needing your presence at the host names its next step. See First-run checklist.

Settings

The gear in the top-right corner opens Settings, full screen (on a computer browser: s, or ⌘, / Ctrl+,; Esc closes it). It is the only menu: Agent & remotes (the Agent's name, Remotes, Face ID, unpairing); Emergency repair (below); Agent tools (Models & API keys, Memory — rules the Agent keeps, you can delete them —, Activity — what it did recently and who approved what —, Schedules, Friends, Bots, the first-run checklist); language and appearance; reply text size, send sound volume, auto-read, wake word; lock-screen alerts; Channels (re-pair Telegram, Email, Contacts — your friends' e-mails and phones, one tap onto the e-mail allowlist — and My contact details); safety options (high-risk warnings, session mode, isolation, Docker, automation send grants); the web app (how updates happen, upgrade Agent J on the Agent J host, versions, update and reload, Add to Home Screen, keyboard shortcuts); account (with the Daily AI News email switch), help, and the security, privacy and terms pages. The phone must be connected to the Agent J host to change settings.

Message box buttons (under language and appearance): the five buttons above the message box (File, Photos, Camera, the mic and Expand full screen) can go in any order — put the mic on the far left, say, to talk with the phone in your left hand. On a phone, hold a button for a moment, then drag it; or tap one, then tap where it should go. On a computer, drag it with the mouse, or focus it and press ← →. The new order shows at once and follows you to every remote; when the Agent J on the Agent J host is too old for that, it is saved on this device only. Restore default puts back the usual order. The Agent can change it for you too: agentj config set ui.composer_buttons '["mic","file","image","camera","full"]'.

Every menu — Settings and the pages it opens, ≡ All commands, keyboard shortcuts, silent history, "How safe is this web app?" — is a full-screen dark page with the same header, icons and buttons. The back arrow at the top left does what Esc does: one level up, so a page opened from Settings returns to Settings. Confirmations and risky actions still ask in a centred card.

Emergency repair

Settings → Emergency repair is the second item. For no replies, follow the five-step phone-only section above. For a grey or offline phone, use the steps below:

  • ① Reset connection: tap this first. It reconnects, finds your conversation again, starts a new conversation if it has to, and as a last step restarts Agent J on the Agent J host; it stops at the first step that works and shows each one. A green card saying "Fixed. You can go back to the chat." means done. If it started a new conversation, the earlier one is kept: ask the Agent in the chat to bring it back. /reset in ≡ does the same.
  • ② Ask Agent J Father for remote help: when ① didn't help. the Agent J host checks itself, removes private details on the Agent J host and sends the report to Agent J Father; you get a ticket number. Support can only suggest a few fixed repairs, and the card shows each one the Agent J host runs. Nothing goes out until you tap.
  • ③ AI account signed out: for a Claude / Codex login that expired; it opens AI login rescue (next section).

When Agent J on the Agent J host stops answering, a small rescue helper there answers instead: a banner says "Agent J on the Agent J host isn't responding · rescue helper online", and ① and ② still work. If the host stays unreachable, open the support chat on your phone. See Phone grey or disconnected?.

Under Emergency repair, Terminal Commands offers fixed terminal checks with Run. The read-only health check (doctor --read-only) uses the paired device signature and needs no Face ID, including on a large screen. Status, service status, rescue status, update check and reconnect still require passkey verification; a large screen without it asks you to confirm on your phone. Older Agent J hosts may still require Face ID for checks. Output is masked on the Agent J host, shown below as text and recorded in the operation log. Tap × to close the result.

Take over the stuck session (in Emergency repair): for an AI that keeps answering and ignores Stop. It interrupts the turn, restarts the AI background program Agent J uses if it is still busy after 10 seconds, and reconnects the same conversation; nothing is lost.

Official remote assist: built, not open yet. It does not show on the phone until it opens. Then, under ② in Emergency repair, you allow 15, 30 or 60 minutes with Face ID. Agent J support can only send task text to your Agent, which follows its usual rules with no extra permissions; spending, deleting, sending or password steps still ask you one by one. Watch live shows every task and reply; Take back stops it at once. Only your Agent's replies to those tasks go to support, with password- or key-like text held back. Logged on the Agent J host for 30 days: agentj assist status, agentj assist log, agentj assist revoke.

Web terminal

Olares app: Open web terminal on setup, or Open Olares web terminal in Settings → Safety, opens a new tab authenticated by Olares. It uses the Agent J app’s user, home and configuration. Check with agentj status or agentj tasks list --json. Olares supplies its own terminal, without Agent J’s masking, operation log or command confirmation; no extra Agent J Face ID or terminal enable step. Do not print credentials or full process command lines. Olares details.

Ordinary Linux, macOS and WSL hosts: open the avatar-menu terminal card or Settings → Safety → Web terminal. Pair and set up a passkey first. Access is off until you enable it with a passkey and Agent J host login password, or agentj terminal enable and its confirmation card at the host. Every open verifies you; default 15 minutes, maximum 60. Type at the terminal cursor, without a separate command box. Tap the terminal on phones/tablets to open the keyboard; the common-key row supplements Tab, arrows and Ctrl+C/D/Z. vim, top and interactive programs work. Keyboard and rotation resize the terminal; shell startup files are not read. Older hosts ask for an upgrade; component failure closes, without line-mode fallback.

In the main Agent’s reply, a single-line shell command shows ▶ when the line immediately above it says to run it on the Agent J host. Tap ▶ and follow the prompt. Commands that need approval show a confirmation card. Commands for another computer, commands with no stated destination, and commands in friend messages, forwards or quotations offer Copy only. undefined chat commands instead run one line; their output, and output the Agent reads, is masked where possible and sent to your AI model provider. Full-screen displays are not handed directly to the Agent.

Five minutes without input/output, 60 seconds hidden, expiry, Stop everything or revoked access closes the terminal. A disconnection allows 30 seconds for the same device’s fresh passkey check; process and original expiry stay unchanged. ✕ collapses; End closes; Esc at the terminal goes to the program.

On the original remote, choose Verify and resume terminal and use your passkey to return to the same process. The page shows the remaining time. Unsubmitted input on the old connection can require a new terminal. Choose Verify and open again while you still have access. If temporary access expired, choose Prepare an access request, review the draft in chat and send it for the owner to approve.

Operation log recording links to what is recorded: masked output and resize, no separate keystrokes; legacy line mode also logs commands. Logs stay on the host for 30 days; no camera, recording or automatic upload. Masking misses unusual secret formats/encodings, and end-to-end encryption cannot stop programs displaying secrets to your own device. Do not print or forward credentials. Password storage · authorization and limits.

Models & API keys

The phone does not show an Agents Relay key section in this version. Saved keys do not switch the primary model or official login, prove provider connectivity, or establish that background dispatch is available. Never paste keys into chat.

"Models & API keys" in Settings keeps the model picker at the top and two sections below it. "Base models" shows one dashed card per provider (Anthropic, OpenAI, Volcano Ark, Alibaba Bailian, Kimi, DeepSeek and more), each key tagged Subscription, Pay-as-you-go or Sign-in; "Third-party API keys" lists the other keys on the Agent J host (ElevenLabs, for example). A row shows only the name and "Not set" or a mask (at most the last 4 characters) — the key itself is never shown on the page. The icons on the right are Copy, Edit and Delete; an empty row only has Add, and "Add" at the bottom lets you name a new key first. Copy, entering a new value, Edit and Delete require in-person passkey verification first, and Delete asks once more; Copy puts the value straight on the clipboard. Edit and Add open the key card; storing a new value or replacement requires in-person verification, and the Agent never sees what you type. Every copy, delete and edit is written to the audit log — the name, never the key. Keys already on the Agent J host are listed too: the systemd user environment, ~/.config/environment.d/, and any .env file you list in api_keys.extra_env_files (none by default; just tell the Agent which file to add). Those rows say "Already on this computer · from X" with at most the last 4 characters; Tapping "Move into Agent J" copies the key into Agent J's own key file on the Agent J host, and from then on that copy counts — the old source stays unless you tick the box to comment its line out. Symlinks, other users' folders and files others can change are never read; the bottom of the page lists the places checked and any skipped. The Claude and Codex sign-in rows say which login is really in use: a subscription token (CLAUDE_CODE_OAUTH_TOKEN) wins over the account sign-in in ~/.claude/.credentials.json. After installing, fill your keys in here and you can leave the terminal.

AI login rescue and renewing before expiry

Rescue stays in Settings and brings a new authorization card into view. The Claude code card includes Open the authorize link, Copy, time left and the round number; after folding it, use Open the code card on the rescue page. The Codex device card shows both its link and code. Authorization opens in a new tab; return here afterward to follow waiting, saved and testing, then passed or failed. Opening the page tests the current login again and shows the check time, with Check now available. While open, the page detects credentials replaced elsewhere and checks again; old conclusions are hidden during checking.

When the Agent J host's Claude Code / Codex login expires, the Agent cannot reply. Open Settings → Emergency repair → ③ AI account signed out → AI login rescue and sign in again from the phone, without going back to the Agent J host: Codex shows a link and a device code; Claude Code shows an authorize link, and its code goes only into the secret card.

With a long-lived Claude token, Agent J writes down the day it stored the token and counts one year from it. The section shows how many days the Claude login has left. On day 7, 3 and 1 before the expiry you get one reminder each: a note in the chat, a push, and a red banner at the top of the chat. Tap the banner (or Renew now in the section) → passkey → open the authorize link in the phone's browser and approve → paste the code into the secret card. The new token replaces the old one as soon as a few-second live check passes, and a new one-year countdown starts; if the check fails, the old one stays and you approve again. The authorize link lasts 10 minutes (the page counts down); when it expires or the code does not work, the Agent J host opens a new link by itself (up to 3 rounds). The link goes only to paired phones, never to Telegram.

Subscription /login and Codex's ChatGPT sign-in renew themselves, and provider keys usually do not expire, so they have no fixed date. Once a day the Agent J host sends each signed-in AI one very short, tool-free test message. If the login no longer works (for example you signed out of all devices on the web), you are told at once to rescue it; running out of balance or hitting a rate limit never asks you to sign in again.

Sign in again under the reply: when a reply says the AI is signed out, expired or needs device confirmation, Sign in again appears under it (so does a /login in the reply). Tap it, confirm with Face ID and approve on the authorization page: for Claude Code paste the code into Paste the authorisation code, for Codex enter its code on that page. It counts as signed in only once a test message in your current conversation gets a reply. OpenCode: Other ways to sign in.

Backup AI accounts

Open Settings → "Agent tools" → "Backup AI accounts" to manage the backup accounts Claude Code and Codex switch to automatically when quota runs out. The primary account is read-only and shows the same configuration as Models & API keys; follow its link there to change it. Add or manage only backup accounts here, without entering the primary account again. Previously saved accounts remain visible with their existing data.

  • Tap "Add backup account", give it a name (1–24 characters, up to 8 per tool), confirm with your passkey, then sign in on the phone as usual: Claude Code sends an authorize link and its code goes into the key card; Codex shows a link and a one-time code. The new backup account is saved separately and never replaces an existing one. You do not need to enter the primary account again.
  • Tap "Make current" to switch, no Face ID needed: the main Agent uses the new account from its next message and continues the same conversation. Background tasks already running finish on the old account; tasks started after that use the new one.
  • Or just say “switch to my Claude backup account” in the chat. At the Agent J host, agentj account list shows the accounts and agentj account use claude Backup switches; to add one, run agentj account add claude Backup in your own terminal.
  • Quota is kept per account: the account in use shows its live reading, the others the last one read.
  • The account in use can't be deleted; switch to another first. Deleting asks on a confirmation card and also removes that account's saved login.
  • If the Agent J host's environment sets ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN, it overrides the Claude account chosen here and switching stays off until it is removed.
  • Never paste a token into the chat.

Remotes

At the bottom of Settings, "Download Agent J Brand Kit" opens the official Brand Kit on the website in a new tab: the main logo and the 16 robots as transparent PNGs (256, 512 or 1024 pixels; 512 is recommended), ready to use as the avatar of your Telegram bot, your email or any other bot.

Remotes

Settings → Remotes is its own page: how many of the 10 remotes are in use, every paired phone or browser (online or not, when paired and last used, how it was added; this one marked "This one"), Rename and Unbind on each row (unbinding another remote takes Face ID on the remote in your hand), and "Add a remote": a one-time QR / link for 5 minutes. Compare the six digits shown on the new device and the paired remote’s confirmation card, then approve on a paired remote.

All remotes are equal. If a phone is lost, unbind it from any other remote (Face ID on the remote in your hand): cards waiting for it are refused at once, and your Same owner hosts stop accepting its signatures. If neither Agent J host had a remote with a passkey when you paired Same owner, the older confirmation still applies (remote signature only, no Face ID / Touch ID, no list of remotes); set a passkey on any remote and pair again. See Same owner.

The scan icon at the top right (or holding the camera button) reads QR codes: a new device's pairing code adds it as a remote (both screens show the same 6 digits; tap "They match — add it" only if they do); any other code goes into the message field as text, never opened or sent by itself. A new device needs no computer: open https://m.agentj.app/ and the code at the top is for a paired phone to scan. The "Web app" tag now lives in Settings → "How safe is this web app?".

Keyboard shortcuts

Keyboard shortcuts

On a computer browser or a tablet with a keyboard, press ? for the full list (it is in Settings too); to find one, tap the magnifier at its top right or press / and type a word. Every tap, hold and swipe with its key: Keyboard shortcuts and gestures. The ones you will use most:

KeyWhat it does
Alt+Shift+J · j · ←Previous page (older)
k · →Next page (newer)
Alt+Shift+G · gJump to the newest page
GJump to the earliest page (older ones are fetched from the computer)
uJump to the first unread reply (read status syncs across your remotes), then page forward
o · ↑ · ↓Expand / fold the message (↑ expands, ↓ folds; with nothing to toggle ↑ ↓ scroll the page)
fRead this reply full screen
Alt+Shift+Y · yCopy the whole reply
Alt+Shift+A · rReply to this one (the quote shows above the message box, focus stays in it; Esc cancels); Alt+Shift+A also works while typing
Alt+Shift+O · s · ⌘+, / Ctrl+,Open Settings
Alt+Shift+K · ⌘+K / Ctrl+KSearch the page you are on: the chat history in the chat, the cards on Workflows / Skills / Memory / Agent J, the text of Settings, a menu page or an open document (inside the message box Ctrl+K still deletes to the end); press again to clear and close
i · EscInto the message box; Esc in it leaves (the draft stays)
/Commands: / outside the message box jumps in with / typed and the command menu open; not while a dialog or Settings is open
aPick a file for the Agent
pPick pictures from the photo library
cTake a photo
hold mHold to talk, release to send (slide out to cancel); keyboard m still releases to text
Esc EscEsc twice outside the message box clears text and attachments (✕ clears the text only, with undo). Esc never interrupts the Agent; to stop the current task, use the Stop button or send /stop
⌘+Enter / Ctrl+EnterApprove, the same as tapping Approve (identity checks as usual); the card wins over the message box

Pairing and Face ID

Start on any device by opening https://m.agentj.app/ in its browser. The unpaired page displays a QR code. Scan it with another paired, connected remote, compare the six digits on both screens and confirm. The new device joins the conversation without visiting the host, and does not need a camera or Face ID. If its browser cannot generate this code, use scanning or a pasted link below.

For your first remote, run agentj pair on the host. Scan the host's code using the scanner inside the new device's page, then enter the six digits and remote pairing password at the host's prompt. Without a camera, run agentj pair --link, copy its pairing link into the new device's link box and start pairing. An online host linked to your account can also add a remote from the account page. See Using your phone for the full steps.

An existing remote can also generate a code or copy a link from Remotes in Settings. Have the new device scan or paste it, compare the match codes and approve on a paired remote's confirmation card.

Screenshots pending: the previous pairing images omit the new-device QR code and comparison on both screens. They are not shown as examples of the current interface; follow these steps and the live page.

A pairing link is a key: it works once and expires after five minutes. Never send it through chat, a group or email, or give it to an AI. On iPhone, add the page to your Home Screen first, then scan or paste inside that icon. Opening the link with the system camera pairs a separate Safari page.

Opening the same browser or Home Screen icon normally reconnects automatically, with rotating renewal credentials where available. Recovery is not guaranteed after clearing website data or credentials, expiry, or unpairing on the host. See Reconnecting and Privacy.

After pairing, you can give this remote a passkey that uses its own unlock: Face ID on iPhone, Touch ID on a Mac, fingerprint or face unlock on Android, Windows Hello on Windows. Each remote sets up its own: "Settings" → "Agent & remotes" shows this one's state, such as "This device's Face ID: set up" or "This device's Face ID: not set" (Android, Mac and Windows name their own unlock, such as "This device's Touch ID: set up"); tap "Set up here" if it is not set. If your Agent J host already has this remote's key on record (one set up before an upgrade counts too), it simply says "This device's Face ID: set up"; if it says "This device's Face ID: not confirmed", tap "Confirm with Face ID" once — no other remote needed; when no other remote can approve, approve in a terminal on the Agent J host with agentj faceid approve <code>. "Remotes" shows the state of every remote too. If this remote uses a passkey from another device, you are told before you confirm that the system will ask you to scan with your phone; once it has its own, it confirms directly. When a check does not finish, the card says why and offers "Try again" and "Set up here (approve elsewhere)". When it says "set up", it also offers "Test it" (one check, nothing changes) and "Set up again" (a new key without unpairing). If the page goes to the background and the connection drops while you verify, it shows "Handing it in…" and sends the result once the Agent J host is connected again.

When the pairing page offers Face ID reconnect, verifying restores the existing device slot without a new scan or host approval. A passkey synced to another device can replace the original device's slot. Unpairing on the host invalidates this route.

Remotes without Face ID or passkeys

A device without passkey support, or without a saved passkey, can pair by scanning, displaying its code or pasting a link. It can read conversations, send messages and attachments, use voice, approve ordinary operations with its signing key and manage remotes. This reduced capability does not make it read-only.

It cannot reconnect using a passkey or complete operations that explicitly require one: picking up a secret, copying or deleting API keys, or other operations that reveal a real secret. Use a remote with a saved passkey, or set one up on a supported device. Administrator authorization and secret-entry cards still work as their prompts allow; a device that already has a passkey must verify its user for those cards and cannot skip verification to fall back.

A browser that also lacks signing support cannot approve operations or send controls that require signatures. The page asks you to update your browser and pair again. Ordinary signatures and passkeys are separate capabilities.

Set up Face ID: approved by another remote

Each remote has its own Face ID or fingerprint key. Set it up under "Settings" → "Agent & remotes" → "Set up Face ID": if no other remote of this Agent has Face ID yet, this one sets it up directly; otherwise another one approves. This remote shows a six-digit matching code, your other online remotes with Face ID get a confirmation card, and if the numbers match you tap "Approve (Face ID)" there, then "Save" back here. After reinstalling the system or clearing the browser's data, set it up the same way; the new key replaces the old one. If this was the only remote with Face ID and its key is gone, unpair it on the host and pair it again first. Details: Using your phone.

Move this seat to another Agent J host

When you change computers, tap "Move this seat to another Agent J host" in "Settings" → "Agent & remotes", read what happens, tap "Continue" and confirm with this remote's Face ID. The remote shows the whole installation prompt for the new host (the code hidden); tap "Copy" and paste it into an AI tool on the new computer. Once the new host binds with the code, the seat moves and your remotes follow on their own; if one doesn't, tap "Scan to pair the new host". The transfer code is valid for 24 hours and works once; until the new host uses it you can tap "Revoke". The old host must be online; on the old host you can also run agentj seat transfer in the terminal. Details: Move a seat from a remote.

Things one sentence does

Agent J is the only Agent you deal with, so most things are a sentence, not a button:

  • "Pick up where we left off yesterday", "Did that report get finished?": it searches the Agent J host's history and continues.
  • "Redo that", "Say it differently": it redoes the last answer another way.
  • "Open the xx project": it finds that project in your work folder.
  • "Compact": handover first, then compaction.
  • "Switch to Codex", "back to Claude Code": switches the AI coding tool — checked first, switched only if it works. See Switch AI coding tool.
  • "I want to report a problem": it asks what you want to report; once you provide the content, it redacts, sends and gives you the ticket ID. Agent-initiated reports need your agreement on the draft first.
  • "Send my card to Kai", "What did Kai say lately?": it manages your Agent friends, see Agent friends.
  • On long jobs it sends you a one-line progress note now and then.
  • "Set up a weekly competitor brief" and other recurring work: it checks its capabilities and sends one start card for you to confirm, see Long tasks.
  • "What can you do": a capability page opens on your phone — what is ready and what needs setup.
  • Want the Daily AI News email every morning: say so and it runs agentj news on (the same switch as in Settings, see Daily AI News). The email goes to your own address; with no email yet, it asks you for one first and confirms it with the 6-digit code from the email.

Silent turns do not take up chat pages. Open ≡ → View silent history to read them. Esc or the backdrop closes the read-only panel; /clear clears it too.

Add a remote for another computer

Once the target Agent J host is installed, account-bound and online, find its seat card on your account page and choose Add a remote. Confirm it's you, then scan with the phone. The account page automatically shows the waiting remote, six-digit code and Approve; compare and approve. When also required by the host, the pairing password is a fresh sealed proof for that exact device and handshake; the target Agent J host's terminal isn't needed. Each start and approval requires its own passkey confirmation (choose Use a phone or tablet if needed). A pairing password is an additional host check and cannot replace account passkey confirmation; the QR expires after five minutes and adds one device. Pending devices can also be reviewed and approved on the seat card. Under More on the seat card, See what the Agent J host is waiting on you for is only for two cases: resuming after Stop everything, or enabling a scheduled task the Agent created. It has nothing to do with seats or billing; an unpaid bill never stops the tasks on the Agent J host.

Account-page pairing is on by default. The target Agent J host’s owner can disable it with agentj remote-pair off. Offline hosts are never queued; turn them on and try again. Older hosts must run agentj update apply or update from a paired phone. Devices record “Added from account page” and other remotes receive a notice.

This route trusts the signing control plane. Pairing material is encrypted to an ephemeral browser key and its plaintext is never stored by the backend; compromise of the signing service could still add a device. The remote pairing password is stored only on that computer, as a hash. When you type it on the account page, the browser first encrypts it to a one-time public key that computer just handed out; only that computer can open and check it. Our servers pass on ciphertext they can't read and keep nothing. Five wrong tries in a row lock it on that computer for a while.

For Codex failures, follow the phone guidance: tap the top model name to replace an account-unsupported model (temporarily disabled until an account refresh); check your proxy/VPN for ChatGPT connection failures; open Settings → Emergency repair → AI login rescue → Codex on your phone when login expires, then follow the device-code card. Use Web Terminal on the paired page for diagnostic commands; you do not need to return to the host or put credentials in chat. Redacted native errors remain under Details.

Still limited after a Codex plan upgrade? For an explicit quota refusal before a request was accepted, Agent J refreshes the current login, checks again and retries at most once. Accepted requests, existing output and uncertain tool execution are never replayed automatically. If the limit remains, send “I upgraded” from your phone or open AI login rescue → Codex and follow the device-code card. Revalidate the current account, or explicitly choose another account and send a new message. A successful refresh or login does not prove a plan upgrade; the provider’s actual result decides.

Shared Codex model and provider (0.16.4a1)

For a phone turn, an explicit agent.model / agent.effort or the latest phone selection is sent as turn/start.model / effort. Without an explicit phone choice, Codex keeps the thread choice. A desktop turn uses the desktop actor’s own last explicit selection; Agent J only observes it. The top bar shows the active actor’s model, not a promise that a queued phone choice is already running. Selecting Default sends the current native defaults once.

Agent J reads effective native model_provider from Codex config/read and names it as thread/resume.modelProvider when the phone resumes an existing thread. It never copies provider keys or rewrites your Codex configuration. If a different program holds the writer, the phone stays read-only and identifies the program/PID when known. Quit that program before retrying.

For older Agent J versions that keep an old model/provider, start a new Codex conversation in the same folder using your current native defaults, then let Agent J follow the new conversation (clear any explicitly selected old shared thread). Or switch Agent J to an independent session. A new conversation has separate history. Do not ask the owner to paste keys into chat.

Shared Claude makes the phone-message setting Claude Code really uses in the work folder accept (organization policy > the folder's private .claude/settings.local.json > its .claude/settings.json > ~/.claude/settings.json), at selection, startup and upgrade, backing up the file first; the phone is told once. A hold in user or private local settings is changed where it is; a hold in the shared project file is overridden from the private local layer. Organization policy, refuse and an explicit agentj config claude-inbound off are only reported. Enabled: phone messages no longer need individual confirmation on the Agent J host; to disable, run agentj config claude-inbound off. A session started before the change needs /clear or a new session. Only Claude Code is affected; Codex/OpenCode have no equivalent mechanism. When a message is not acknowledged, the phone names the reason (organization policy, project settings, turned off, needs /clear, computer busy); check the Agent J host before resending. The phone's model/quota bars (agentj config claude-statusline) are turned on at the same moment unless the owner turned them off, chained at the status-line layer in effect; agentj doctor reports a layer that hides them.

Shared mode: Claude /clear and /compact wait for the current desktop turn and confirm native hook receipts. A successful clear archives phone pages and starts at zero, including clears typed on the desktop. Context uses only new-session/post-compaction measurements; pending readings show “—”, never the previous value. A timeout reports an unconfirmed change; check the desktop before retrying. Shared Claude has no native undo-clear button: history remains archived locally; use desktop /resume to restore a conversation. Independent mode retains undo. Attached Codex clears from the phone with /clear: the next phone message opens a new Codex conversation, the phone archives its earlier pages as usual, and Undo clear works until that message is sent. Once the new conversation is open, keep chatting on your phone; no extra action is needed. An optional continuation section at the bottom of the clear-success card stays collapsed by default; no second message is sent. Expand it to copy a command only if you want to continue the same conversation in a terminal or the matching app on the Agent J host. The command follows your current AI tool, Claude Code, Codex or OpenCode; it is hidden when no resume command is available. While the desktop Codex is mid-answer nothing is cleared; clear again when it finishes. Attached OpenCode supports /compact; use desktop /new and select the new session to clear. Agent J's own Claude PTY accepts controls directly; an existing terminal requires an exact-session Herdr input route, otherwise the phone explains the reason and native command. Shared /context, /usage, /status and /model without an argument read measured data; unavailable values show “—”.

The 5h line remains visible at 1%; 0% has a start marker. No text beside it means no reported measurement. Expanding the input card reduces the reply reading area while keeping the action row and composer fixed; long inputs and replies scroll within their cards.

Shared sessions

New installs use an independent session: Agent J starts its own and leaves your terminal tools alone. Sharing the session you already have open on the Agent J host is optional — Settings → Session mode, or agentj config set agent.session_mode shared (back: … independent).

When you enter or switch to a shared Claude Code, Codex or OpenCode session, the phone shows a one-time notice that fades after 3.5 seconds. Refreshing or reconnecting to the same session does not repeat it. Read-only conflicts, failed sends and requests that need your action remain visible.

Which session the phone talks to: by default the Claude Code session open in your work folder. If several are open there, run agentj agent claude on the Agent J host: it lists them with their names and first messages and lets you pick one. Nothing changes on the phone.

The pairing page offers browser and storage guidance. Use a regular Safari / Chrome window, add to Home Screen and pair from that same icon. The menu retains Set up Face ID after Later; Copy page link excludes the one-use pairing secret.

Sharing screenshots

See Android sharing and the iPhone clipboard Shortcut. Shared content enters the composer; add a note before sending.

Updating the phone page

Upgrade Agent J installed from Olares Market in Market → Manage → Updates. The phone’s /update and agentj update apply direct you to Market; do not reinstall Agent J or install systemd inside the app. A separate installation directly on the Olares host’s Ubuntu keeps the ordinary host upgrade flow.

Host and page updates are checked separately. In other cases, when a newer web version is detected, a square opens in the middle of the screen: Server upgraded. Tap Refresh to use the new version; Later, ESC or a tap outside closes it, and you can still tap the top-right gear (Settings) → Web app → Update and reload later. When the host and page server both have the same newer version, the page reloads after ten seconds without input, preserving the draft; recording and unsubmitted card actions block it. Otherwise only offer a refresh. Keyboard: Alt+Shift+U upgrades the host (phone confirmation unchanged); Alt+Shift+R updates and reloads the page.

Still grey after an upgrade? Read the message first. If it says “Claude session is disconnected” or that the shared Claude session is missing or matches multiple sessions, tap Repair on the page. If an older page has no Repair button, or repair still fails, open Settings → Safety → Session mode, choose Independent session on the left, and wait for the setting to save. Then open Settings → Emergency repair → Restart service. If Claude sign-in is missing, first use AI login rescue → Claude → Sign in again (recommended) on the same page, follow the sign-in prompts, and retry. Once connected, send “Hello” and check for a new AI reply. Old chats remain, but a new session may not carry their context. Use your paired page; you do not need access to the host or a terminal. If the page says the host is offline, follow the disconnection steps below. An online host does not prove Claude is attached. To refresh the web app, open the top-right gear → Web app → Update and reload; older pages may show only a circular-arrow icon below the version.

When a daily, weekly or monthly model allowance runs out, the phone tells you to wait for its reset or upgrade your plan with the model provider. A temporary rate limit still asks you to retry later. Provider error details are never displayed.

If shared Claude completes a reply while your phone is disconnected, reconnecting updates its existing input page. Reloading first fetches the current computer history before claiming that a message is still waiting. /update receipts use the current language setting, including changes made while Agent J is running. agentj doctor includes the websockets version for troubleshooting.

Short network blips are repaired quietly: when the phone's connection drops it is usually back within a second. The status dot next to the logo turns grey at once; the page only turns grey with "Connection lost. Retrying in N s…" after about 5 seconds, and a dialog opens in the middle of the screen after 10 seconds. A busy computer that answers late is not treated as a disconnect. If your Telegram channel can't reach Telegram three times in a row (or for two minutes), one line under the chat says so and disappears by itself once Telegram works again. For the first minute after Agent J starts, agentj doctor shows the relay as "connecting" rather than a problem.

Local read-aloud uses only voices on this phone. Host/cloud voices stay in voice.tts.voice; choose a phone voice separately with voice.tts.phone_voice (empty selects the local default for the reply language). Switching modes keeps both choices. An unavailable phone voice falls back with one notice. On first opening, iPhone waits for local voices to load before reporting that no voice is available.

Shared Claude ingress: startup and doctor repair the effective writable layer to accept; managed policies are read-only. Sessions started before the change need a new session or /clear on the Agent J host. Shared startup re-enables ingress; check the desktop before resending unacknowledged messages.

0.18.1: Valid older Telegram enrollment continues with its local bot environment name. Huawei HarmonyOS devices have accurate names; account owners can rename a remote with a passkey while its host is online.

Renaming a remote: press and hold the source at the top left of the input card (half a second) to rename the remote in your hand; other remotes and the account page show the new name right away. Only the owner can rename other remotes, on the account page. A remote the owner renamed shows that name and its device type as the message source (for example "Alex (boss) · iOS Safari"), marked "(name set by the owner)"; a tap shows the name the device gave itself. Remotes nobody renamed are marked "(name set by the device)". The Agent uses the owner's name to tell who is speaking, but the name is only a label, not proof of identity. A double tap at the top left still goes to the first message.

The first message is slow and the phone shows nothing

On a new computer it is usually one of four, and the phone says which: the model service cannot be reached (Claude Code retries for about three minutes; the phone shows a card when it is still failing after about 10 seconds); bubblewrap is missing (every start shows a "Sandbox unavailable" card, whose "Run this launch without isolation" button needs the owner's passkey; install sudo apt-get install -y bubblewrap socat on the Agent J host); running as root with bypassPermissions (Claude Code refuses to start; Agent J starts it in the default permission mode and says so); a model the provider does not serve (400; sent again once on the default Opus 5.5 · medium).

agentj agent claude (or codex) answers the tool's one-time setup ahead (onboarding, theme, folder trust, bypass confirmation) — only what is missing, no key read; the first-setup row of agentj doctor checks it. When the Agent really waits at a terminal prompt, the phone gets a "Handle it on the Agent J host" card quoting the terminal's words: open Web Terminal on your phone and run agentj agent claude to finish first-time setup, then send again. Never send passwords or login credentials to the Agent.

Sandbox failures and admin commands

If an independent session's sandbox cannot start, the Agent stays stopped. The phone card explains the cause (such as missing bubblewrap) and repair. Tap Run this launch without isolation and verify with the owner's passkey to allow this launch only; the next launch checks isolation again. This launch may access local files and credentials. Set up a passkey in the phone menu if needed. Denial or timeout never starts the Agent.

The sudo card labels what it's for and the effect as Agent claim, what it's for first; a purpose that is too short or only repeats the command, or a request to manage Agent J's own background service, shows no card. Shell or interpreter commands are marked red and require an admin password even with the passwordless helper installed. A few read-only commands offer a switch on their card, off by default: turn it on and approve with the password, and for 10 minutes the same program with the same options, only on other files, runs without a card, each noted in the chat; sensitive files and shell or interpreter commands still ask every time, and "Revoke" ends it at any time. Secret cards support URL verification; --verify-cmd is disabled and runs no command outside the sandbox. Scheduled tasks and native customer-service bots authenticate from native storage and do not inherit host-service API keys or tokens.

Connecting Telegram

Telegram uses a bot of your own. Save its key with a key card, then run agentj channel add telegram on the Agent J host or tap 「Re-pair Telegram」 in Settings. The chat shows a one-time 6-digit pairing code (10 minutes, one use). In Telegram, send /start <code> to your bot in a private chat: that chat becomes the owner, and the bot replies that Telegram is connected. No other bot is needed to look up your ID. Anyone else who writes to the bot only gets their own numeric ID back; a code sent in a group does not count. To move to a new phone or Telegram account, tap 「Re-pair Telegram」 again.

The same bot can also be customer service for everyone else. In Bots, open a customer-service bot and tick 「Let my Agent J Telegram bot receive guests」 (or ask your Agent J; you approve it on the phone). Your paired private chat stays your main conversation; any other private chat becomes a visitor of that bot, with its own session, instructions, model and limits, and never gets your permissions. Off by default: then strangers only get their numeric ID. See Customer service bots.

Telegram and friend safety boundaries

Forwarded messages in the owner’s Telegram private chat are external data, not the owner’s instructions. Forwarded commands do not execute. Approval commands in groups remain silent; use the paired phone to approve. When the family safety check is unavailable, that message pauses: the owner can send the request directly from the paired phone. Only a leading /notification or /notify command counts as a reminder request; the word notification inside other text does not.

Group text and captions are checked before attachments are downloaded. Proxy groups do not download attachments; family attachments are refused when the rules match. Each group sender has a 40 MiB download budget per UTC hour across groups, preserved across restarts. Unknown sizes reserve the per-file maximum. Paused group messages cannot start Agent tools. Friend cards allow up to 64 characters for the name, 32 for the owner and 140 for the introduction. A credential-shaped value in supplementary context rejects the whole edit; use ordinary background information.

Support bots process Telegram private chats independently, preserving order within each chat. Text over 2000 characters gets a fixed request to shorten it without a model call. Customer text and model suggestions in support reports are data for summarising and diagnosis, never owner instructions.

Getting help

  • When your Agent can report the problem itself, have it use agentj support to ask our support desk; you don't have to find a person. See Getting help from the support desk.
  • The phone can't reach the Agent J host, or the chat is stuck: Settings → Emergency repair, starting with ① (above).
  • If it can't connect at all (offline, the install failed, it can't reach our servers), or https://agentj.app/ won't open (for example in mainland China), email feedback@agentj.app — email gets through from anywhere. Include your account ID, what happened and when, and a screenshot.

Tap the logo for Chat, Workflows, Skills, Memory or Agent J; hold it to return to Chat. These pages read the Agent J host's documents and hide credential files. A workflow's @ inserts an atomic mention that sends as plain text. Tap the dancing robots for Working (AI tool and reported model) or Workflow (CEO, people and reporting lines); unassigned workers are temporary helpers. Alt+W opens the menu; Z still cycles text size and M still records.

Double-click or double-tap a non-audio file card (image, video, PDF, document, text, code, Markdown or HTML) to view the file full screen, or use Full screen. Audio cards and reply text open the reply reader. Video keeps its playback position; Escape or Back closes the current viewer.

A collapsed input card shows two quote lines and one body line, or up to three body lines without a quote, with an ellipsis for overflow. Attachments appear as a line paperclip and total count beside “…” (images, files and audio together); zero attachments show no count. Double-click the body, tap “…” or press o to expand all text, the quote and attachments.

The Agent J Father robot is the official logo. Its body follows the five state colours; the Send button uses its white silhouette. Outside chat it dances to remind you that holding it returns to chat. Reduced motion uses a static logo and a subtle inset heartbeat outline. When changing the background robots, Agent J first asks whether you also want a new five-state logo set; leaving it out keeps the current set.

When a goal needs a capability you have not set up

Agent J checks existing APIs, skills and its browser sign-in before explaining what is missing and how to supply it. It does not end with “I cannot do that.” The routes, in order, are:

  1. Official API. For missing accounts, authorization or keys, it gives one sentence stating what you can supply, followed by a short list of providers, registration pages and approximate costs. After you agree it guides setup step by step. Keys go only in the phone secret card, never chat or the opening card. Service charges need separate approval.
  2. A website with no API. Agent J can operate it with its own browser. It first checks browser setup and the site's sign-in. When needed it says “This site has no official API; I can operate it through my browser. Please sign in to X there once” and starts the login flow. QR sites open a phone login card; QR codes only appear there. Other sites open a sign-in page on the Agent J host. An uncertain check is reported as uncertain, never as signed in. Sign-in is not authorization: publishing, payment and other sensitive actions still require phone approval.
  3. A missing platform primitive in this version. It explains the gap, offers /feedback-to-agentj-father to send feedback to Agent J Father, and states what you must still supply once the capability is unlocked. For feedback it proposes itself, you review and approve the draft first. Your explicit /feedback-to-agentj-father command with content is redacted and submitted directly, without a second confirmation. Submission does not mean it is scheduled and never promises a release. Combined gaps get both paths.

For goals needing a workflow, genuinely missing choices, authorization and setup go on one opening card (at most five required items), followed by a secret or login card as needed. Already authorized, equipped work continues; only dependent work waits. Truly illegal or dangerous requests are still refused.

The first time you open Workflows, and each time Agent J starts on the Agent J host, it scans the folders one level under the working root: folders organized with the workflow design method (an entry file and the documentation/ boot documents) show as cards; one missing from the CEO roster (documentation/ROLES.md) gets a row appended at its end — append-only, nothing else changes, and a row you delete is not added back. When no workflow is found, the three that come with Agent J (Knowledge base, Scripts and articles, E-book) are shown; Install it makes Agent J show you the preview first. Set up organization sends Agent J one standard instruction: organize the projects you use with the workflow design method, register their CEOs and check, listing any unorganized project for you first; nothing is deleted or moved. After one use it reads Review organization, which fills gaps.

Open a workflow card and its staff are listed under the CEO: only employee files with a name in .claude/agents/ (on the Codex side, the .toml files in .codex/agents/) count — a README or another note there does not; an employee file with a title (for example title: Copywriter) shows that name. When a CEO has no staff yet, the card carries a small line "Only a CEO, no staff yet", and the Review organization button adds the count, for example "Review organization (2 with only a CEO)". Tap it and Agent J reads that company's latest reports, task.json and RUN.md, lists 3–7 proposed staff roles for you first, and writes them only after you agree (the Codex copy is made with them), never over an employee file you changed. When work is sent to a company that has only a CEO, Agent J also mentions it once in its reply — once per company.

Full-screen history and file forwarding

In the reader, swipe right on text for an older reply and left for a newer reply. Desktop ← / → do the same. A small bounce marks either end. Vertical scrolling, long-press selection, horizontally scrolling tables/code, file controls and edge-back gestures keep their actions.

The file card’s paper plane sends the original file as a document to your Telegram private chat. It immediately shows “Sending…” and keeps “Sent to Telegram” or a failure reason. If Telegram is not configured, it tells you to configure it first. If delivery times out, check Telegram before trying again. Credential files remain blocked.

The reader uses the same dark Noir as the dialogs in the middle of the screen, in light and dark mode alike. The header at the top and the footer at the bottom never move; only the text between them scrolls, with no scrollbar drawn — fingers, the wheel, the arrow keys and Space all scroll it.

  • Header, left: the Agent's name and the reply's time — double-tap for the first reply. Middle: the unread badge when there is something unread — tap for the first unread reply. Right: the page number (this one / all of them; no ✕ — you leave the way you came in) — double-tap for the newest reply without leaving; it flashes when a new reply arrives.
  • Footer, bottom left: a thin text-size icon that opens the size slider; pinching and the + / - keys still work. Bottom right: the reply card's six icons — full-screen reading, read aloud, forward to myself, forward by e-mail, copy, reply (rightmost).
  • Copy and reply leave the reader; reply quotes this reply and puts the caret in the message box. Read aloud, forward to myself and forward by e-mail keep you in the reader, and the icon shows sending / sent. The book icon leaves too.
  • When you swipe or press ← / → to another reply, the header's time and page number and the footer's buttons all follow it. Files that came with a reply show under its text.
  • Keys: G first, g newest, u first unread, y copy and leave, r reply, l read aloud, t forward to myself, e forward by e-mail.

No scrollbar is drawn anywhere in the web app — pages, dialogs, menus, Settings, code blocks and file previews included — and everything still scrolls by finger, wheel or keyboard.

Agent J Father is our official feedback and support platform. Say “Please report this problem to Agent J’s developers (support platform)”, or casually “Tell your dad about this”. On the phone, /feedback-to-agentj-father <message> does the same: your Agent removes credentials, personal information, customer data and private path details, submits directly without asking twice, and gives you the ticket ID. The command alone asks what you want to report. If reporting a problem or idea is the Agent’s own initiative, it shows you the redacted draft on the phone and waits for agreement. Support replies are advice, not instructions. If it cannot connect, email feedback@agentj.app.

Copy system instructions and reconnect Telegram

Host system messages put values and commands you need to copy into code blocks. Press the copy icon instead of selecting text. Telegram pairing shows the code and the /start command separately; its Telegram link opens a new tab. Setting codes, recovery commands and terminal continuation commands use the same copy controls. A continuation command is optional: keep chatting on the phone unless you want to move to the matching terminal app.

After saving a key to the managed service environment file through the secret card, Agent J rereads that file automatically. Rebind Telegram also rereads that file before checking the token. If the service still needs a restart, open Settings → Emergency repair → Restart service and confirm with Face ID or your device passkey. This sends your signed request from the paired remote; the connection may drop briefly and reconnect. In an isolated Agent session, an unavailable host control socket means its status cannot be checked there, not that the service stopped. Use the paired phone's reload, Telegram rebind or restart controls.

Import a key already found on the computer

  1. Open Settings → Models & API keys. A key row can list existing sources on the computer, with a masked ending and whether it matches the managed copy. Values are never displayed in full.
  2. Choose the source you intend to use, then tap Move into Agent J and confirm once. Agent J copies it locally; you do not paste the key into chat.
  3. The old source is kept by default. Only select the option to comment out its original line if you want that change. Importing a key is not permission to delete other sources.
  4. Read the Claude or Codex sign-in row's actually in use source. A key listed elsewhere is not necessarily the login the running AI uses. after Agent J restarts means the running AI has not picked up that change yet; follow the row's restart or sign-in guidance and check again.

Refresh, reply options and a TV remote

Hold the top search button for about half a second (550 ms) to force a refresh. Your text draft is kept. Finish any recording, attachment work or unsubmitted card first. At the top of a message, pull down until “Release to refresh” appears, then release.

Reply options use borderless pills with a Noir background, Lotion text and space around the text. Their background becomes Sooty while pressed.

On a large screen, the current focus is clearly marked:

  • Up / Down moves vertically between cards.
  • Left / Right opens the previous / next message, including in full-screen reading.
  • PageUp / PageDown (CH± on compatible remotes) scrolls a long message by one screen.
  • In the message area, press the confirm key Enter twice, less than 400 ms apart, to read full screen.
  • Press the webOS Back key, Escape or Backspace to leave full screen. In text fields, cursor movement, selection and deletion keep their usual behavior.

A paired large screen without a passkey keeps the existing remote rules. Ordinary approvals keep their usual confirmation flow. Actions that explicitly require a passkey show "Please confirm on your phone"; complete those on your phone. The TV does not replace verification.

If the browser cannot record audio, use the text field with your system keyboard's dictation. Whether the remote's voice key supports dictation depends on the TV and browser; we have not tested it on an LG TV. Landscape 1080p has been checked in Chromium emulation, which is not physical TV acceptance.

Preparing voice input for the first time

While voice components are installed for the first time, the page shows the current download, unpacking, installation and self-test stages, without an estimated percentage. The microphone shows "Preparing" until it is ready.

A prominent "Ready" notice tells you to press and hold the microphone to speak; dismiss it with "Got it". If setup fails, the notice shows the reason and a "Try again" button. Check the network or disk space as advised, then retry. Notices do not expire automatically. You can dismiss them with ESC; a later notice can also replace them.

After reconnecting, readiness is checked again. Installation progress from the disconnected period is not replayed step by step.

At the top of a message, pull down until “Release to refresh” appears, then release to update and refresh. Text drafts are kept; recording, attachments and unfinished cards block refresh. The header robot follows the state colour unless you use a custom logo; the status bar and bottom safe area stay Sooty #141414.

After an automatic web update, a Noir notification appears for about 3 seconds, once per version on each device.

Shortcut search also matches synonyms, including screenshot, snapshot, 截图 and 截屏.

For each question, choose an option or write your own answer in the card (up to 2,000 characters). Writing replaces that question’s selected options. Confirm sends the signed answers to the computer; no extra chat message is needed. On older hosts, choose Other and answer in chat. Use the dedicated secret card for passwords and API keys, not ordinary question cards.

Empty recordings and recovery

Recordings shorter than half a second or with too little audio data are discarded without a recovery prompt. Empty saved recordings showing 0:00 are cleaned up automatically. In the recovery dialog, Discard is on the left and Put them back is on the right. Empty audio attachments are blocked with “Recording too short. Not sent.” iPhone MP4/AAC recordings and WebM recordings keep their actual format.

Continue from your phone

In Settings → Safety, tap Emergency stop all Agents and confirm to interrupt the main Agent’s current turn, stop Agent J background tasks, pause Agent J scheduled tasks and reject pending approvals. Esc cancels. Resume remains at the top; resuming uses a signed confirmation button on a paired remote. Emergency stop is no longer in the slash menu; /stop-all, /stop_all and /estop direct you to Settings.

After Reset connection in Settings → Emergency repair, tap Restart Agent and confirm once. The host ends the current AI session process and resumes the same conversation; if that fails, a new session is connected to your phone and the old conversation is kept. Claude Code, Codex and OpenCode reconnect from your phone: no need to go to the computer. Native permissions stay in place. If the host cannot verify the selected process identity, it refuses to end it and offers remote help. Automatic retry after quota recovery is separate.

Approval and execution cards

Approval cards show the task source with commands folded away; sudo execution status stays in the current reply. Scroll within a long card. Approval still requires a signature and its applicable owner verification. Reopen a collapsed approval with the heartbeat entry at the lower left of the reply; reading mode keeps both safe areas Sooty #141414.

Copy controls in Notebook, messages and code blocks briefly show ✓ “Copied” for about 1.5 seconds, with a centred notice; failures also show a notice. Informational notices such as voice input becoming ready disappear automatically, with no OK button. Copying in reading mode keeps the reader open.

Icon holds and button states

Holding an icon or toolbar button runs its shortcut without selecting nearby controls or opening the system text menu. Reply text, messages and code remain selectable and copyable. Button labels stay readable on hover, while pressed, with keyboard focus and when unavailable. Unavailable buttons do not run actions.

Centred circular notices show one short status word: Sent, Copied or Saved (up to four Chinese characters). Longer explanations use a rounded rectangle in the same centre position, keeping the full text and the original automatic dismissal time. Both shapes use Noir with Lotion text in light and dark mode.

Queued messages and quiet periods

A queued message shows Previous task still running · waiting N min and Stop current task: on a 0.26.9 Agent J host it first asks you to confirm Force-end this turn, interrupts the earlier task and after 10 seconds ends that turn's processes; the conversation is kept. On a queued notice from the Agent J host the button appears once the task is stuck or has waited 2 minutes. /clear, /new and Reset connection no longer wait behind a stuck turn.

After three minutes both queued and without new earlier-task output, the page reports that quiet period; this does not prove the task is stuck. New output resets the timer, and a reload or reconnection starts a new observation. A working task is never stopped automatically. From 0.26.9 a turn that is really stuck (no card waiting, no tool running, yet nothing for 5 minutes or your message waiting 10) recovers by itself: the Agent J host interrupts it, restarts the AI program Agent J started if needed, continues the same conversation and says: It got stuck just now — recovered automatically. Stop retains its existing handling of unsent messages.

Sending while the AI works: with Codex, when supported, your message joins the running turn (Added to the current turn); otherwise it queues and is never dropped. The rest of the earlier turn's output continues in a new card at the bottom; the old card says Continued below.

Continue from the failed step

A failed multi-step workflow offers Continue from the failed step on its result card and failed scheduled-task row. The tap signs that exact run and checkpoint. Completed steps with valid outputs are reused. A changed task, step description or checkpoint invalidates the old action; refresh and review the current record.

A non-idempotent step that may already have sent, paid, published or deleted still needs the owner's confirmation card. Declining runs nothing. Friend reports, delegated friend tasks and Same owner messages cannot authorize this action. Older hosts do not show it, and repeated taps cannot replay a consumed signature. You can also ask the main Agent to inspect and resume using agentj-automation.

Consecutive recordings and leaving the page

Foreground takes reuse an authorized microphone and disable its capture track between takes. Locking the screen, switching apps or leaving the page stops the track. Returning does not open the microphone automatically. Tapping Record again may prompt for permission; Safari website settings can set Microphone to Allow. Actual system permission dialogs still require a physical iPhone check.

Confirming email and sensitive cards

Mail only to yourself goes without a card. Mail to anyone else, including allowlisted contacts, meeting notes and email replies, has a one-tap confirmation card; no Face ID. The card binds recipients, content, attachment hashes and mail servers. The allowlist only controls incoming mail. When you yourself tap Forward by e-mail or forward to Telegram on a paired remote, or sign a customer-service email, that tap is your approval: it goes out at once, with no card and no passkey. Mail settings changes and connection tests use their signed confirmation; entering a real app password still uses the secret card. Changing the account address, login name, IMAP/SMTP server, port or encryption invalidates the old app password. An app password saved by an older version moves over by itself on the first run after the upgrade when the mailbox uses a fixed provider (Gmail, QQ, 163 …). With a custom server it is not used directly: saved candidates are verified first, and you enter it again in the secret card only when none works.

Administrator password cards use password entry and a confirmation button; revealing a real secret still requires this remote's approval passkey. Enable it in Settings first. Replacing an existing passkey asks the old key to verify this one-use registration offer, then creates the new key. Cancellation or verification failure keeps the old key. Account sign-in and remote approval passkeys are set up separately.

Create a new Agent J plan through the Host

For the new Host transaction, write a local JSON contract and run:

agentj tasks create --contract contract.json --json

The contract has task (the existing task.json v1 schema, enabled:false, both prompt file names PROMPT.md) and prompt (the task instructions). Only an explicitly declared new large bank/cryptocurrency transfer adds large_transfer:{"kind":"crypto","limit":"1200.50","currency":"USD"}. The kind is bank or crypto. Its presence declares the task large; do not add it to ordinary tasks or paid API work. The Host freezes the exact contract, asks one paired-device fingerprint approval for this declaration and atomically publishes the disabled task. A small/new ordinary task or a paid API task has no additional creation card. Existing automations are not migrated or reapproved.

The owner-approved amount is written in the task instructions and is informational, not enforced. Agent J does not monitor transfers, verify runtime amounts, debit a quota or stop a run over this declaration. This is not a payment authorization or extra sandbox permission. Creation initially supports a live verified Codex thread whose current sandbox can write the configured working root; read-only, unknown/custom roots and other unverifiable AI coding tool policies refuse, even with fingerprint approval. Do not bypass that refusal.

Creation does not enable the task. Inspect with agentj tasks show ID, then use the existing agentj tasks enable ID when appropriate; enabling/resuming adds no financial reapproval. Multi-step creation is not supported by this initial endpoint. On an uncertain connection result inspect the task before retrying; a task id is never overwritten. If that id retains an old enable authorization, creation refuses even when the old directory has moved; it does not clear the old authorization automatically. A crashed uncommitted stage is retained privately and is never discovered as an active task; do not delete unrelated private staging data automatically. If publication reports a conflict requiring recovery, keep the conflicting files and ask the owner to inspect them before enabling or retrying.

Background task information

Each background row shows the detected tool, model and reasoning effort, a recognizable short account ID or plan, and elapsed time. Unverifiable fields say “Unknown”. CLI-supplied tool/model labels are separately marked “Self-reported”; detection wins a conflict. The total counts active tasks, including separate native children sharing a process; live processes have a separate count. A lost process source or ended native thread removes its row automatically. The Agent must actually run agentj busy list --json to report background work, rather than rely on memory. Accounts use short IDs, never full email addresses.

Children whose state cannot be confirmed are marked “Status unknown” and excluded from the running total; their rows expire after the last-activity retention period. A live host process does not prove that its child task is still running.

Version 0.25.8

Background work shows program-verified tool, model, short account ID and elapsed time; unverified child status remains unknown. Calendar creates and changes need a long-press confirmation each time and deletions need Face ID, each bound to the exact destination and content. Only verified phone or owner-terminal input is an owner request; missing sources and external/system content cannot borrow it. Saved mail passwords are verified before asking again. For a requested self-compaction, write the handoff, queue compaction and end the turn.

Edit the watchlist

Open Settings → Heartbeat → View or edit heartbeat prompt. The shared full-screen editor offers Cancel, Restore defaults, Preview and Save. Restore changes the draft first; Save applies it. Cancel preserves the original, and a failed save keeps your draft. Settings text fields and contact notes use the same editor.

The factory watchlist checks all local scheduled-job logs and reports since the last heartbeat (Linux systemd timers/cron, macOS launchd/cron, Windows Task Scheduler), unusual or stuck Agent J friend requests, and mail/WeChat/Telegram main-thread messages, replies and to-dos with missed replies, failures or unclaimed work (canonical watchlist v2 replaces v1 in place, preserving other personal text). The main Agent follows up or takes over under existing approvals. It follows this same file while working too; heartbeats do not fire while busy.

Upgrades replace and deduplicate marked factory blocks in place, preserving personal text outside them. A wholly custom heartbeat.md without a factory block stays unchanged. When doctor or Settings reports an update, Merge factory checklist replaces an old checklist or appends one if absent.

The main Agent can run agentj inbox avatar-log --since 2h (or an ISO date/time; add --json) for read-only legacy avatar exchanges, replies, handling outcomes and delivery status. This history does not cover current channels: owner messages are handled in the main thread, and legacy avatar routes must not be restored. Cover the period since the last heartbeat. Missing historical replies or delivery evidence are unknown. Retention and size limits apply; truncation and unavailable channels are explicit. Absence of a record never proves everything was handled.

Confirm one exact action list

For a task needing several confirmations, ask the Agent to list every exact action on one card first. Tap Approve; if any action requires owner verification, such as spending, revealing or sending a real key, or unrecoverable deletion, confirm the whole list once with Face ID. Approval covers only the listed tools and complete inputs. Changed commands, another task or device, and expired plans need confirmation again; other actions of the same kind are not included.

For a local task use agentj friends approve-actions <actions.json>; for a verified Same owner device use agentj friends tell <friend> --actions <actions.json> <task text>. Sign once on any confirmed remote of the initiating host; the receiver accepts only the listed exact actions. The JSON array has 1–20 items, each {"tool":"Bash","input":{"command":"<exact command>"}}; never include credential values. Requesting approval does not execute the actions. Local approval lasts at most 30 minutes / 20 uses and ends with the task or revocation.

An explicit Same owner plan must be signed by a confirmed remote of the sending host that the receiver already knows. Any other signer returns root_reconfirm: repeat Same owner pairing first. Missing, invalid, changed, oversized or expired plan proof is refused with task_refused, without delivery, execution, a fallback ordinary task or another receiver card. Queued plans also refuse on expiry or turn drift. Ordinary handovers without a plan are unchanged.

Switch AI tools in the Olares app

AI tool scanning, switching, restart and failure recovery in the Olares app use the image-owned read-only process manager, retaining paired-phone signed confirmation. A failed switch restores the original configuration; rollback is confirmed only after the original AI returns to service, and failed recovery is reported. Do not install systemd inside the app. Bundled OpenCode is pinned to 2.2.5; existing working owner-installed tools are not silently replaced.

For native Claude Code, install and personally sign in to Claude Code inside this app, then switch with agentj agent claude. Claude Agent inside OpenCode is a separate route: install Claude Code 2.1.248 or newer, personally run claude auth login, then choose Claude Agent in OpenCode /connect. Agent J does not copy OAuth tokens; completing login does not establish a verified model reply.

External assistants: one-way MCP requests

On your phone, open Settings → Agent tools → Webhooks → External assistant · One-way requests. Enter a connection name and allowed website origins, one exact HTTPS origin per line, such as https://assistant.example, without a path, query or trailing slash. Tap Create connection, confirm the signed card on your phone, then verify with Face ID on the pickup card to collect the credential once. Copy the connection URL from the list.

An external assistant can send requests and receive fixed receipts. It cannot read Agent J replies, conversations or work results, or approve actions for you. Incoming requests and authentication pass through hosted relay memory; replies and work results stay on your host and phone. The list shows metadata only. If you lose a credential, choose Rotate credential, confirm the signed card and collect its replacement; the old credential stops working immediately. Choose Revoke connection and confirm its signed card when you no longer need the connection.

This version supports MCP 2025-06-18 with stateless JSON requests, without SSE or two-way result delivery. Connecting a Muse account and completing platform review still require the owner's authorization and live verification. This page does not claim Muse approval or compatibility.

Live voice call prototype (#441, off by default)

This is a development prototype, not a production availability claim. Explicitly set AGENTJ_VOICE_STREAM=1 on the host process to reuse the existing voice.asr.mode=custom and base_url, deriving /v1/audio/stream on the same destination. This prototype currently supports loopback or LAN IP literals only. The existing custom URL validator still applies; browsers cannot supply endpoints or keys. An unavailable streaming interface reports streaming unavailable, without falling back to whole-recording transcription. No new skill is needed.

On a paired phone, choose Start voice prototype, hold to talk, and release to submit. End call stops at any time. Real mono 16kHz PCM chunks travel every 200ms over the existing paired encrypted session to the host. Partial captions appear as received; a final transcript enters the current main Agent at most once. Reply sentences go to free local browser speech synthesis; no local voice means unavailable. Holding again cancels the old call and speech. The host interrupts the old Agent task only while its device and task identity still match, without resubmitting it. Simple energy VAD, a 30-second input limit, an eight-packet queue and sequence checks bound the prototype. Disconnect, emergency stop, invalid seat or unpairing clean up the call.

Audio and captions decrypt only on the phone and host; the relay continues to carry encrypted data. ASR credentials remain on the host. Existing PTT, transcription, voice attachments and approvals remain available. Older hosts show no call entry.

Verification boundary: Passing synthetic ASR/model tests does not establish real model availability. The Qwen service WS dialect, real main-Agent token streaming, audible physical-phone TTS and production end-to-end latency are NOT_VERIFIED. When an existing Agent adapter supplies complete text blocks, sentence delivery starts only after each block arrives; token-level latency is not promised. Development tests use fake ASR/model and intercepted browser TTS and cannot establish a production live-call result.

Managed background work

agentj busy run --detach --report REPORT.md -- <command…> registers a one-shot background job. Busy run waits for resource capacity, lowers child priority and checks that an explicit report is nonempty with exit status 0 before marking delivery. A failed manager response is never automatically retried. A fenced session refuses a manager launch that would escape its sandbox. Detached native AI coding tools and shell wrappers are refused while the current session sandbox/approval policy cannot be verified; use session-managed dispatch for those jobs. After ten minutes without observed output or bounded work-directory metadata changes, the job records stalled; this never kills the task or grants automatic wakeup authority. Check the job before replaying an unknown outcome.

AI login rescue inserts or replaces login credentials and is on the explicit verification list. Every request requires fresh in-person verification; a check from the last five minutes is not reused.

Inspect local patches

agentj local check (optionally --json) inspects ~/.agentj-local/MANIFEST.json without changing files. A missing inventory does not create a directory. Corrupt records, unsafe patch paths and broken links are reported. It does not apply patches, repair links or contact support. pending_review needs human verification; present_unverified means only that a link points to an existing source, not that it works with this release. The existing post-upgrade doctor automatically inspects this inventory read-only; findings are warnings and never block an otherwise verified upgrade. reapply and trusted official fixed-version checks remain unimplemented; relink is limited to explicitly registered owner-custom Codex skill slots. Do not claim that inspection restored a feature.

Uninstall a plaza skill or workflow

Request a plaza package uninstall. Choose the AI coding tool when the same name has several installs. --preview inspects without a card or move. The host checks the original record, complete installed files and target, then shows Uninstall plaza package on a paired remote. Approval moves that directory atomically to a private recoverable backup, keeping publisher trust and installation history. Denial, expiry, invalid signatures and changed targets leave it installed. Inspect the installed list before retrying an unknown outcome.

Uninstall command

agentj plaza uninstall <package> --harness <claude_code|codex|opencode>

Only unchanged skill/workflow directories are supported. Card packages, modified or unmanaged targets and cross-filesystem backup moves are refused. The local uninstall history retains the backup reference; reinstalling uses the normal signed install and does not revive old approvals. This action does not terminate running processes or revoke publisher trust.

Save local patch or feature records

agentj local record --contract FILE --json saves a private record only after a fresh paired-phone identity check and explicit approval. This initial entry supports Linux and a verifiable active Codex session with full access; it refuses workspace-only/read-only/unknown authority. It cannot increase native permissions. The running Host derives its own package code root; the caller cannot select an installation directory. Nothing is applied, linked, executed or sent to support.

A patch contract has exactly kind: "patch", files (relative package paths), baseline_root (an absolute local text baseline directory), baseline_sha256 (each file's expected SHA-256), description, validation, rollback, and father_ticket (letters, digits or hyphens). The baseline is explicitly owner-local SHA-256 evidence, not an official release or an official fix. Newline-terminated UTF-8 files only; protected paths, links, binaries, oversized or secret-bearing input refuse. The private record contains the unified diff, baseline bytes and README; the manifest remains pending review.

A feature contract has exactly kind: "feature", source (an absolute external code directory), entry (a relative path inside the Host package root), description, validation and rollback. It records the exact source inventory and proposed symlink entry without creating the link or copying the external code into the installation. local check may therefore report broken_link until a separately approved restoration exists.

Records stay in owner-only ~/.agentj-local/, with numeric pN/fN IDs. No manifest text is a command or an official repair receipt. A concurrent file change refuses instead of broadening approval; uncertain publication retains private recovery data and reports record_recovery_required. Keep it for review rather than automatically retrying or deleting unknown files. Patch application and authenticated Father fixed-version evidence remain unavailable. Legacy arbitrary installation entries cannot be relinked.

Fields for a new feature record

Use a new feature record with exactly kind: "feature", entry_kind: "harness_skill", harness: "codex", skill_name, source, description, validation and rollback.

skill_name must match SKILL.md's canonical front-matter name, use a nonreserved package slug and declare no aliases. Host derives the only destination from the existing Codex global skill root, ~/.agents/skills/<skill_name>. This is an owner-custom global skill, never bundled/official. Original and current installation roots and the global destination tree cannot hold the external source. Existing arbitrary installation-relative feature records stay read-only; there is no guessed migration.

agentj local relink fN --json verifies that record and the exact source files, inode generations, owner and permissions. The global skill parent must already exist and be a safe real directory. Existing Plaza packages, retained uninstall/history/certification records, publisher trust, registered names or aliases cannot be displaced or impersonated. Corrupt or unavailable conflict evidence refuses. A missing target needs a fresh paired-phone identity check and approval in the active full-access Codex session. An existing correct link returns already_present, modified:false, without another card; other occupants are preserved and refused. No file or link is replaced or deleted.

linked proves the exact link was created and validated; functional_verified:false means no feature code or validation/rollback text was executed. Check behavior with the owner before calling the feature repaired. Source edits, including same-byte new inodes, need a new record. An uncertain result preserves the approved link or unknown object plus private prepared journal and reports recovery-required. Inspect first; do not automatically retry or erase recovery files. Linux/Codex/full-access restrictions still apply. reapply remains unsupported because arbitrary recorded package files may include frozen trust code and no trusted Host-owned functional verification mapping exists; a compile check would not prove a repair.

Spend, learning and read-aloud settings

Run agentj usage on the Agent J host for time, usage and spend summaries. Missing readings stay unknown; subscription quota is not a dollar bill. See Spend and speed.

/learn skill distillation is currently awaiting an owner decision; draft and proposal requests are refused. Its retained design requires the complete proposed diff and paired-owner confirmation before writing, with a separate review for plaza publishing.

Hold a reply's Read aloud button to ask for voice setup. Inspect agentj voice status, choose an available engine, enter keys only through a secret card and listen to a test. Automatic model rewriting for speech is disabled; cloud speech checks the full text, including an owner prefix, before sending it to the chosen provider. See Choose a reading voice.

这一页的 Markdown 原文This page as Markdown: zh.md · en.md