文档Docs
手机显示灰色或断开怎么办Phone grey or disconnected? Bring it back
手机或网页变灰多半是电脑上换了新会话，不是中继坏了；Agent J 会自己跟上新会话，其他问题在手机 设置 →「紧急修复」里修，也可以用一条命令把服务、中继、Agent 三段查一遍、修好。A grey phone or web page usually means the computer opened a new session, not that the relay broke; Agent J follows the new session by itself, Settings → Emergency repair fixes the rest from the phone, and one command checks and repairs the service, the relay and the Agent.
手机或网页整屏变灰、显示断开，最常见的原因不是网络，也不是中继坏了，而是电脑上换了一个新会话：重启电脑、关掉终端再开、/clear、升级后新开的 Claude Code，都会换一个新的会话 ID。共享模式下 Agent J 跟着的是那一个会话，旧的关了，手机就找不到人说话了。
先在手机上试：紧急修复
卡住、离线、老是断，或者不回消息？不用回电脑。打开 设置 →「紧急修复」（第二项），按顺序试。离线提示卡上的「紧急修复」按钮，打开的也是这里。
① 重置连接。 先点这个。它一步一步试，哪一步连通了就停，每一步都显示在卡片上：
- 重新连接。
- 找回原来的对话。
- 必要时开一个新对话。原来的对话不会丢：在聊天里说「找回原来的对话」，或者在电脑上运行
agentj rescue undo。 - 重启电脑上的 Agent J。
卡片变绿、显示「好了，可以回去聊天了」，就修好了。≡「全部命令」里也有「重置连接」，打 /reset 也一样。
② 请 Agent J Father 远程帮忙。 第 ① 步没用时再点。电脑先自己做一遍检查，在电脑上去掉隐私信息，再把检查报告发给 Agent J Father，卡片上会显示工单号。客服能建议的修复只有固定几种（重新连接、重启、没人登录也保持运行、退回上一个版本、开新对话）；电脑只做这几种，每做一步都告诉你，做完把结果发回给客服。你不点，什么都不会发出去；报告里不会有密码、密钥，也不会有你的对话和文件。
③ AI 账号登录失效。 这一项是 Claude / Codex 账号的问题，不是连接的问题：点进去就是「AI 登录救援」。
电脑上的 Agent J 卡死了怎么办。 agentj service install 和每次升级都会顺带装一个小小的救援守护。Agent J 大约 45 秒没响应，救援守护就替它接手机：页面上会显示「电脑上的 Agent J 没响应，救援守护在线」，① 和 ② 照样能用。在电脑上运行 agentj rescue status 可以看它在不在。
电脑旁边有人？ 手机完全连不上电脑时，请他打开终端，粘贴下面这一行，按回车：
curl -fsSL https://agentj.app/rescue | shWindows 上在 PowerShell 里运行：irm https://agentj.app/rescue.ps1 | iex。它会检查电脑，只修能安全修的，再把去掉隐私的报告发给客服。详见 紧急救援。
0.18.4 起：自己接上
Agent J 发现跟着的会话关了，会在同一个工作目录里找新的那个，自动接上，不用重启任何东西。接上后手机会收到一句「又接上了，新会话 …」。
它怎么挑：
- 只看同一个工作目录里、你自己开着的 Claude Code 会话；后台跑的
claude -p任务、后台作业一律不算。 - 只有一个，就接它；有好几个时，接刚刚打开的那一个，或者在旧会话之后才打开的唯一那个。
- 两个以上一样可能时，它不猜，手机上会列出这几个会话的短 ID，请你选：在你要用的那个会话里说一句「接上手机」就行。
Codex 和 OpenCode：不自动跟新线程（旧线程没了除外）
上面「自己接上」只对 Claude Code 生效。主 Agent 用 Codex 或 OpenCode 时，你在电脑上新开一个线程（会话），Agent J 不会自动跟过去，手机还接着原来那个。要换到新线程，在电脑上运行 agentj config set agent.shared_session_id <新线程 ID>，再运行 agentj service restart。
另外有两点：一是 Codex 跟着的那个线程在电脑上已经没有记录时，手机会说「共享会话找不到了」，然后改接这个目录里最近在用的那个 Codex 线程（会跳过正被终端里的 codex 占着的线程）；拿不准时弹一张卡请你选，也可以选「新开一个对话」。二是 Claude Code、Codex、OpenCode 各记各的共享会话：换一个主 Agent 再换回来，各自还接着自己原来那个，不会串用别家的会话 ID。agentj config set agent.shared_session_id 设的值只给它所属的那个 Agent 用。
自己接不上时：一条命令
对电脑上的 Agent 说「手机灰了」或「接上手机」，它会运行：
agentj doctor --reconnect这条命令依次检查三段，哪段断了修哪段，最后说一句人话结论：
| 哪一段 | 怎么看 | 断了是什么意思 | 它怎么修 |
|---|---|---|---|
| 后台服务 | agentj status 有没有回应 | agentj serve 没在运行 | 启动或重启服务 |
| 中继 | relay_state 是不是 up | 电脑连不上 Agent J 中继（网络或账户） | 等一会，再重启一次服务 |
| Agent | agent_status 是不是 down | Agent J 没接上任何一个活着的会话 | 重新挑会话接上；在哪个会话里运行就接哪个 |
好几个会话分不清时，可以直接指定：agentj doctor --reconnect --session <ID>。
agentj status 发现 Agent 断了时，也会在结果里提示这条命令。
新会话开工自检
Agent J 给主 Agent 的随包说明里写着：每个新会话的第一轮（包括压缩、/clear、恢复之后）先运行 agentj status --json，不正常就自己运行上面那条命令。还没接上的新会话打开时，Agent J 也会通过它在这个目录装的钩子提醒那个会话怎么接。所以你不需要记任何命令，也不需要知道该怎么下指令。
中继一直「reconnecting」
0.22.x 起，每次连中继失败都会说清卡在哪：写进服务日志（journalctl --user -u agentj，或运行 agentj serve 的窗口）、agentj status --json（relay_last，以及人话版 relay_stuck）和 agentj doctor：
· 中继连接失败 / relay connect failed #4: …（phase=auth why=auth_refused code=4003）· 1.2 s 后重试phase 是停在哪一步（seat 读席位证书，connect 解析域名 / 建立 TCP、TLS、WebSocket 连接，auth 中继核对这台电脑的签名）；code 是中继的关闭码。agentj doctor 还会探测电脑自己那条带签名的连接（主机这一侧），不再只测手机那一侧，所以手机那一侧检查通过、电脑这一侧却连不上时，也能看到原因。
| 它说的 | 多半是 |
|---|---|
why=replaced code=4001 | 有两个 agentj serve 在用同一个身份：只留一个（pgrep -af 'agentj serve'） |
why=seat code=4002 | 没有有效的席位证书：看 agentj doctor 的 seat 行 |
why=auth_refused code=4003 / why=identity | 这台电脑的身份文件对不上：把 agentj doctor --json 发给客服，不要自己删状态目录 |
why=limit | 同一个公网 IP 连接太多：等几分钟 |
why=timeout phase=connect、why=dns、why=tls | 这台电脑的网络、DNS、代理或证书有问题 |
找客服时把那一行原样带上。
还是不行
先在手机上试 设置 →「紧急修复」②。在电脑前的话，运行 agentj doctor 看完整自检，再按 求助 页的步骤。不要手改配置文件，也不要把任何密钥发到聊天里。
When the phone or web page turns grey and says disconnected, the usual cause is neither the network nor the relay: the computer started a new session. A reboot, closing and reopening the terminal, /clear, or a Claude Code restart after an upgrade all give the desktop a new session ID. In shared mode Agent J follows one session; when that one is gone, the phone has nobody to talk to.
From the phone first: Emergency repair
Stuck, offline, dropping, or no replies? You don't have to go back to the computer. Open Settings → Emergency repair (the second item) and go in order. On the offline card, the Emergency repair button opens the same place.
① Reset connection. Tap it first. It tries one step at a time and stops as soon as the link works again, showing each step on the card:
- Reconnect.
- Find your conversation again.
- If needed, start a new conversation. Your earlier one is kept: ask the Agent in the chat to bring it back, or run
agentj rescue undoon the computer. - Restart Agent J on the computer.
When the card turns green with "Fixed. You can go back to the chat.", you're done. ≡ All commands has the same "Reset connection", and typing /reset does it too.
② Ask Agent J Father for remote help. Use it when ① didn't help. The computer checks itself, removes private details on the computer, and sends that report to Agent J Father; the card shows a ticket number. Support can suggest a few fixed repairs (reconnect, restart, keep running without anyone logged in, go back to the previous version, start a new conversation); the computer runs only those, shows each one, and sends the result back. Nothing is sent until you tap, and the report never holds passwords, keys, your conversations or your files.
③ AI account signed out. This one is about the Claude / Codex account, not the connection: it opens AI login rescue.
When Agent J on the computer is frozen. agentj service install and every update also install a small rescue helper. If Agent J stops answering for about 45 seconds, the helper answers the phone instead: the page shows "Agent J on your computer isn't responding · rescue helper online", and ① and ② still work. Check it on the computer with agentj rescue status.
Someone at the computer? When the phone can't reach the computer at all, ask them to open a terminal, paste one line and press Enter:
curl -fsSL https://agentj.app/rescue | shOn Windows, in PowerShell: irm https://agentj.app/rescue.ps1 | iex. It checks the computer, repairs only what is safe, and sends a privacy-filtered report to support. Details: Emergency rescue.
Since 0.18.4: it reconnects by itself
When the followed session goes away, Agent J looks for the new one in the same working folder and attaches it — nothing to restart. The phone then shows "Back on track — attached to the new session …".
How it chooses:
- Only Claude Code sessions you opened yourself in the same working folder count; headless
claude -pruns and background jobs never do. - One such session: that one. Several: the one that just opened, or the only one started after the old session.
- Two or more equally likely: it does not guess. The phone lists their short IDs; in the session you want, say "connect my phone".
Codex and OpenCode: no automatic follow (unless the old thread is gone)
"Reconnects by itself" above works for Claude Code only. With Codex or OpenCode as the main Agent, a new thread (session) you open on the computer is not followed: the phone stays with the old one. To move to the new thread, run agentj config set agent.shared_session_id <new thread ID> on the computer, then agentj service restart.
Two more things. When the Codex thread the phone followed no longer exists on the computer, the phone says "The shared session is gone" and follows the Codex thread used most recently in this folder (skipping one a terminal codex is holding); when that is unclear it shows a card so you pick one, or "Start a new conversation". And Claude Code, Codex and OpenCode each keep their own shared session: switch the main Agent and back, and each one is still on its own session — none borrows another's session ID. A value set with agentj config set agent.shared_session_id is used only by the Agent it belongs to.
When it cannot: one command
Tell the Agent on the computer that your phone is grey, or ask it to connect your phone. It runs:
agentj doctor --reconnectIt checks three links in order, repairs only the broken one, and ends with one plain sentence:
| Link | Look at | Broken means | Repair |
|---|---|---|---|
| Service | does agentj status answer | agentj serve is not running | start or restart the service |
| Relay | is relay_state up | the computer cannot reach the Agent J relay (network or account) | wait, then restart the service once |
| Agent | is agent_status down | Agent J is not attached to a live session | attach again; run inside a session to attach that one |
If several sessions are open, name one: agentj doctor --reconnect --session <ID>.
agentj status also points to this command when the Agent is down.
The new-session self-check
The main Agent's built-in instructions say: on the first turn of every new session (also after compaction, /clear or resume), run agentj status --json, and run the command above if anything is not up. A new session that Agent J does not serve yet is told the same through the hook Agent J installed in that folder. You never need to remember a command or know what to type.
The relay stays "reconnecting"
Since 0.22.x every failed relay attempt says where it stuck, in the service log (journalctl --user -u agentj, or the window running agentj serve), in agentj status --json (relay_last, and relay_stuck in words) and in agentj doctor:
· relay connect failed #4: … (phase=auth why=auth_refused code=4003) · retry in 1.2 sphase is where it stopped (seat reading the seat certificate, connect DNS / TCP / TLS / WebSocket, auth the relay checking this computer's signature); code is the relay's close code. agentj doctor also probes the computer's own signed connection (the "host leg"), not only a phone-side test socket, so a green phone-side check with a stuck host leg is no longer hidden.
| What it says | Usually means |
|---|---|
why=replaced code=4001 | two agentj serve use the same identity: keep exactly one (pgrep -af 'agentj serve') |
why=seat code=4002 | no valid seat certificate: see the seat row of agentj doctor |
why=auth_refused code=4003 / why=identity | the computer's identity files disagree: send agentj doctor --json to support; do not delete the state folder |
why=limit | too many connections from this public IP: wait a few minutes |
why=timeout phase=connect, why=dns, why=tls | network, DNS, proxy or certificate trouble on this computer |
Quote that line when you ask for help.
Still grey
Try Settings → Emergency repair ② on the phone. At the computer, run agentj doctor for the full check, then follow the support page. Do not edit config files by hand, and never paste a key into the chat.