文档Docs

装好之后，电脑上怎么用Using it on your computer

让它一直运行、打开本机的 Agent 管理页、换 AI 编程工具、改名、全部停下、看记忆和记录，常用命令都在这里。Keep it running, open the local Agent settings page, switch AI coding tools, rename, stop everything, check memory and activity — the commands you will actually use.

装好以后，平时你基本只用手机。电脑上要做的事很少：让它一直开着，偶尔改个设置。这一页列出会用到的命令。

所有命令都在终端里运行。这些事你都可以直接让电脑上的 AI 替你做；只有配对手机要你自己来，而且在账户页或已配对的手机上点就行，不用终端。遥控器配对密码是可选的，见下文。

Agent 需要管理员密码或者某个 API key 时，会在你手机上弹一张卡片，不用回到电脑前，见手机上完成管理员授权和密钥录入。Agent J 自己出了问题，Agent 会先去问我们的客服，见遇到问题找客服。

先看一眼状态

agentj

agentj

agentj doctor

agentj doctor

agentj status

agentj status

agentj（不带参数）：列出安装步骤的完成情况，并提示下一步该做什么。
agentj doctor：逐项自检，每项一行。✓ 表示正常，! 表示提醒，✗ 表示需要修复，后面会说明怎么修。
agentj status：查看后台程序是否在运行、是否已连接。

想看全部命令：agentj --help。

让它一直运行

安装时 AI 已经帮你装成了系统服务。电脑开机、你登录之后，它会自己启动。

agentj service status

agentj service status

agentj service install

agentj service install

agentj service uninstall

agentj service uninstall

status：看服务在不在运行。
install：安装并启动服务（Linux 上是 systemd 用户服务，Mac 上是登录项 LaunchAgent）。
uninstall：停掉并删除服务。

install（以及每次升级）还会顺带装一个小小的救援守护。电脑上的 Agent J 不响应时，靠它手机上的设置 →「紧急修复」照样能用；uninstall 也会一起删掉它。运行 agentj rescue status 可以看它在不在，详见手机显示灰色或断开怎么办。

Mac 上，系统设置 → 通用 → 登录项与扩展的「App 后台活动」里，Agent J 的条目是：这个服务一条，它的救援守护一条；装了 Agent J 浏览器会再多一条。服务那一条显示为「Agent J」和机器人图标，下面是签名开发者的名字：服务由一个经过 Apple 公证的小程序 Agent J.app 启动，它装在你个人的「应用程序」文件夹（~/Applications）里，请不要删。万一下载不到签名版，会退回原来的方式，那一条就显示成 agentj、写着「来自身份不明的开发者」，不影响使用；救援守护那一条目前也是这样显示。升级、切换 Agent 时用到的一次性任务不再登记到那里，用完就删；旧版本留下的那些，升级后会自动清掉。不要关掉这些开关，否则电脑重启后服务不会自己起来。

云服务器上，没人登录也得让它跑着。先执行 loginctl enable-linger $USER，再跑 agentj service install。

不想装成服务，也可以在一个终端窗口里运行 agentj serve，窗口关了它就停了。

注意：电脑关机、睡眠或断网时，手机连不上它。电脑恢复后，它会自己重新连上。

本机的 Agent 管理页

agentj admin

运行后，终端会打印一个链接。用这台电脑的浏览器打开它，就能进入这台电脑自己的 Agent 管理页。在这里可以：

配对新手机（点「添加手机遥控器」）；
在「手机遥控器」里看已配对的手机（满 10 台显示「已满」），解绑某一台；
在「Agent 的名字」里改名；
开关「从账号后台解绑」（勾选「允许在账号后台解绑这台电脑的手机遥控器」）；
在「连接状态」里看「电脑端程序」是否在运行、「转发服务器」是否连上、是否加入 Agent J 账号。

页面上的「使用建议」写着：一个人用一个 Agent。10 台手机遥控器，给同一个人的手机、平板和电脑用。

这个页面只能在这台电脑上打开，别的电脑和手机打不开。链接 10 分钟内有效，只能用一次。在终端里按回车会换一个新链接，旧的立刻作废；按 Ctrl-C 关掉管理页。

不想复制链接，就运行 agentj admin --open：它直接用这台电脑的默认浏览器打开管理页，命令马上结束，链接不会打印出来。页面 30 分钟不用会自动关闭，要再开就再运行一次。跟 Agent 说「打开 Agent 管理页」，它运行的就是这条命令。

如果你是用 SSH 登录的云服务器，agentj admin 会同时打印一行 ssh -N -L … 命令。在你自己的电脑上运行这行命令，再在自己电脑的浏览器里打开那个链接。

手机和设备

agentj pair

agentj pair

agentj devices

agentj devices

agentj revoke <设备号>

agentj revoke <设备号>

agentj pair：配对一部新手机。后台程序得在运行，没运行的话它会提示你先跑 agentj service install。具体步骤看手机上怎么用。
agentj devices：列出已经配对的手机和浏览器。
agentj revoke <设备号>：马上断开并移除一台设备（设备号在 agentj devices 里查）。

一个 Agent 最多配 10 台手机。满了再配，agentj pair 会列出这 10 台，让你先解绑一台。

换 AI 编程工具或工作文件夹

agentj agent

agentj agent

agentj agent detect

agentj agent detect

agentj agent codex --dir ~/agentj-work

agentj agent codex --dir ~/agentj-work

agentj agent：看现在接的是哪个 AI 编程工具、在哪个文件夹干活。
agentj agent detect：看这台电脑上哪些 AI 编程工具能用。
agentj agent claude --dir <文件夹>、agentj agent codex --dir <文件夹>、agentj agent opencode --dir <文件夹>：换成 Claude Code、Codex 或 OpenCode，并指定文件夹。OpenCode 还要加 --model，写成「服务商/模型」，比如 --model zhipuai/glm-5.3。
agentj agent reset：忘掉之前的对话，下一条手机消息开始一段新对话。

用火山方舟、Kimi、阿里百炼或 DeepSeek 的模型：见按你用的模型选。

会话模式：新安装默认用独立会话——Agent J 自己开一个、在隔离里运行，不改你终端里的工具。想让手机接上你电脑上已经开着的那个会话（高级），在这几条命令后面加 --shared；加 --independent 就改回来。每次切换都会说明这意味着什么，并给出改回去的那一行（agentj config set agent.session_mode independent|shared）；手机「设置」→「会话模式」也一样。从默认共享的旧版本升级上来的安装保持共享（写进设置文件，不会被悄悄切走）。共享模式下，文件夹里同时开着好几个 Claude Code 会话时，它会列出来（名字、最近活跃时间、第一条消息）让你选一个；以后想换：agentj config set agent.shared_session_id <会话 ID>。

换完要重启后台程序才生效

agentj service uninstall
agentj service install

用 Codex 共享模式（手机和电脑同一个会话）时，手机发的第一条消息不会被拒。没指定会话，就接上这个文件夹里最近的 Codex 会话；一个都没有，就新开一个，并在手机上告诉你。电脑上用 codex resume <id> 也能接着聊。电脑上那一轮还没答完，手机的消息会排队，等它答完再发，最多等 30 分钟，/stop 可以取消。接不上原来的会话、或者读不到原来的权限设置，按你自己的 Codex 默认设置来，手机上提示一次。原因都记在 agentj activity 里；agentj doctor 也会多一行，写明会接上哪个会话。

改 Agent 的名字

agentj name

agentj name

agentj name 小助手

agentj name 小助手

不带名字是查看，带名字是修改。名字要短：中文最多 8 个字，英文、数字、横杠和空格最多 13 个；混着写时中文每个算 1.6、其他算 1，合计不超过 13（比如「市场部 Agent」算 10.8）。同一个账号里不能重名。以前起的长名字升级后照常用，下次改名时才按这个规矩。这台电脑加入了 Agent J 账号时，会先在账号后台改，成功了才改本机。也可以在账号后台或本机 Agent 管理页里改。

全部停下

agentj stop

agentj stop

agentj resume

agentj resume

agentj resume：恢复。设了遥控器配对密码就要输它（没设的话要你自己在键盘上确认），所以 Agent 自己解除不了「全部停下」；在已配对的手机上点「恢复」也行。

手机上 ≡ 菜单里的「全部停下」和这里是同一个开关，在手机上点「恢复」也行。

看它记住了什么

Agent 每次开工都会读一些记忆文件，比如 Claude Code 的 CLAUDE.md。你可以一条一条地看、一条一条地删：

agentj memory list

agentj memory list

agentj memory show 1

agentj memory show 1

agentj memory rm 1 3

agentj memory rm 1 3

agentj memory restore

agentj memory restore

list：列出记忆放在哪几处，每处有几条。
show <编号>：看某一处的每一条。
rm <编号> <条目号>：删掉一条。删掉的原文先进回收站，7 天内可以恢复。
restore：看回收站；agentj memory restore <编号> 恢复一条。

手机上的「记忆」页也能做同样的事。

看它做过什么

agentj activity --since 2h

agentj activity --since 2h

agentj approvals --verify

agentj approvals --verify

agentj activity：看操作记录：每轮对话的开始和结束、每次请求批准、谁批准或拒绝了、全部停下和恢复。--since 可以写 2h、3d 或日期。记录只存在这台电脑上，保留 30 天。
agentj approvals --verify：看每一次批准和拒绝，并核对它确实来自你配对过的手机。

不想记录：agentj config activity off。马上删掉所有记录：agentj activity --clear。

手机上的「记录」页读的就是这份记录。

定时任务

如果你用「工作流设计向导」搭了按时运行的工作流，可以在这里管：

agentj tasks list

agentj tasks list

agentj tasks show <任务名>

agentj tasks show <任务名>

agentj tasks enable <任务名>

agentj tasks enable <任务名>

agentj tasks disable <任务名>

agentj tasks disable <任务名>

agentj tasks run <任务名> --dry-run

agentj tasks run <任务名> --dry-run

任务装好时都是关着的。用 enable 打开（你让 Agent 开，它也能直接开），手机上的「定时任务」页也能开关。run --dry-run 只显示会怎么跑，不真的运行。

想搭工作流，在手机上对 Agent 说「帮我设计工作流」，它会一个问题一个问题地问你。

遥控器配对密码

可选，推荐设。它只存在这台电脑上（至少 8 个字符），有两个用处：在这台电脑的终端里配对（agentj pair 必须有它，没设会先请你设）；在别的电脑的浏览器上用邮箱验证码登录账户页、添加遥控器时，可以用它代替通行密钥。不设也能用账户页的通行密钥或已配对的手机添加遥控器；但将来所有遥控器都失效、手边又没有通行密钥时，就得回到这台电脑的终端来设它。安装结束时会问你一句要不要现在设，直接回车就跳过。

agentj passphrase status

agentj passphrase status

agentj passphrase change

agentj passphrase change

agentj passphrase reset

agentj passphrase reset

status：看有没有设置、是不是因为输错太多被锁了。
change：改密码。
reset：忘了遥控器配对密码时用。要输入 RESET 确认。它会删掉旧密码，同时解绑所有手机，之后用 agentj passphrase set 设新密码，再重新配对。

密码至少 8 个字符，别的没有要求。

升级

agentj update check

agentj update check

agentj update apply

agentj update apply

agentj update check 看有没有新版本。谁都可以运行，AI 也可以替你查。第一行开头的词说明情况：newer 是有新版本；current 是已经最新；ahead 是你这台电脑上的比公开发布的还新，不用管；unknown 是这次没查到，多半是没联网，过会儿再查就行。

升级用 agentj update apply：你让 Agent 升级，它会自己运行这条命令，装好、重启、自检，再把结果告诉你。

后台程序每天查一次新版本，有新版就在手机上提醒你一句。这个每天的检查本身不会安装任何东西。不想让它每天查：agentj update auto off。

这台电脑加入了 Agent J 账号的话，新版本发布时还会收到我们签名的官方通知。Agent 按你选的升级方式处理：默认自动升级，再告诉你改了什么；也可以改成先问你。紧急安全修复总是马上升级。在手机「设置」的「升级方式」里改，或者在电脑上运行 agentj config set updates.mode ask（改回来用 auto）。

我们每天早上 9 点（日本时间）还可能发一封升级邮件，里面有升级授权码。把邮件转给 Agent J，它会自己升级（agentj update apply --from-email -），中间不用你再确认。详见官方通知。

其他开关

agentj report-hostname off：不再把这台电脑的名字报给账号后台。
agentj remote-unbind off：不让账号后台解绑这台电脑的手机，解绑只能在这台电脑上做。
agentj unlink：把这台电脑从 Agent J 账号里移出来。用设置码加入的，账号后台那边也会一起移掉；用 agentj login 加入的，只删本机的记录，账号后台那边还要在 Agent 卡片上点「移除这个 Agent（释放席位）」。

想彻底卸载，见安装最后一节。卸载不会停止扣费，订阅要在账号后台的「管理账单」里取消。

个性化设置

agentj config path 显示唯一的用户 JSON5 文件（~/.config/agentj/config.json5）。可以写注释和尾逗号，只写自己改过的项。升级保留你的改动，未修改项使用新默认值。agentj config keys 列出当前配置项、默认值、别名和安全等级。

用 agentj config get、agentj config set、agentj config unset、agentj config validate、agentj config diff、agentj config history、agentj config rollback、agentj config apply 管理配置。主机把校验、保存和生效放在一个事务里；生效失败保留上一份可用配置，并明确报错。返回 applied:false 表示还要启动或重启主机，不能宣称手机已改变。声音调整后仍需听真实样本。

重新加载，不用重启（agentj reload）：设置分三层。大多数设置保存就生效；隔离、Docker、高危提醒、审批强度、你的追加指令和 Telegram 通道要「重新加载」：在手机 ≡ 全部命令里点「重新加载配置」、发 /reload、按 Alt+Shift+L，或在电脑上运行 agentj reload。后台服务不重启，主 Agent 在下一条消息前重启，对话接着原来的；服务密钥文件里新存的 key（比如 Telegram 机器人的）也一起读进来。Agent 用 agentj config set 改了这类设置会自己重新加载；你在手机设置页改了，会弹一张卡片，点「重新加载」就行。只有工作根目录和会话模式（独立 / 共享）还要 agentj service restart。

agentj skill install 把随包附带的 agentj-config 技能安装给 Claude Code、Codex 和 OpenCode，你让 AI 装它就会装。agentj skill uninstall 只移除自己的链接，不覆盖已有同名技能。你本机的 AI 可结合技能和 agentj doctor --offline --json 完成个性化与诊断；独立会话里的 Agent 看不到 Agent J 的设置文件，改设置时用共享会话或手机「设置」。

唤醒词留空时跟随嘿加上你给 Agent 起的名字，连接后会同步改名。安卓后台监听默认关闭，陌生名字可能需要指定发音。安卓 APK 目前供审阅测试，任意名字识别率和耗电尚未完成验收。iOS 网页版 App 不能后台唤醒。

ASR 默认在你的主机识别。云 ASR 用你自己的 OpenRouter key，音频直接发给该服务商。TTS 默认用手机已安装的本地声音，也可选主机或自有 key 的 OpenAI / ElevenLabs 服务。云 TTS 将回复文字直接发给所选服务商，返回音频经过我们的中继时是密文。安卓本地通知播报只说通用提醒，不在锁屏读对话。后台播放仍受系统和浏览器策略限制。

云端朗读用 OpenAI 时，默认模型是 gpt-realtime-2.1-mini。OpenAI 会在 2027-01-06 停用旧的 gpt-4o-mini-tts：你的设置里如果还是这个旧默认值，Agent J 启动时会自动换成新模型；你自己指定过的其他模型原样保留，agentj doctor 会提醒你检查一下。用 ElevenLabs 时，没指定模型就用 eleven_v4。

也可以用你自己的本地发声程序：把 voice.tts.mode 设成 host、voice.tts.provider 设成 command，在 voice.tts.command 里按参数数组写好命令，用 {output} 标出要写的文件。程序从标准输入读回复的文字，写出一个 WAV 文件；超过 voice.tts.command_timeout（默认 60 秒）会被停掉。命令里不要写密钥。

Telegram 可选、默认不启用，用的是你自己的 bot。接入时先保存 bot 密钥，再运行 agentj channel add telegram（或在手机「设置」里点「重新绑定 Telegram」）：手机上会出现一个一次性的 6 位配对码，在 Telegram 私聊里给你的 bot 发 /start 配对码，这个私聊就成了主人。不需要找别的 bot 查 ID；别人给这个 bot 发消息只会收到他自己的数字 ID，在群里发配对码不算数。文字、图片、语音、视频和文件都能发，单个最大 20 MB；语音和视频里的话在你的电脑上转成文字，手机上选了云端识别也一样。在 Telegram 里长按一条消息点「回复」再说话，被回复的那条也会一起转给 Agent，标成「回复 Telegram 消息」的引用（谁说的、几点；最多 300 字，先选中一段再回复就只引用那一段；图片、语音只写成「[图片]」「[语音]」，不会重新下载）。引用里的命令不会执行，只有你自己打的字才算命令。

想让这个机器人也接待客人：在客服 bot 里打开「让我的 Agent J Telegram 机器人也接待客人」。你的私聊照旧是主对话，其他人由那个客服 bot 单独接待，见客服 bot。

macOS 后台服务的 Telegram 和服务商密钥写在 ~/Library/LaunchAgents/net.agentj.host.env，使用配置里 key_env 指定的变量名；文件必须由你本人拥有、权限为 0600，不能是软链。保存后运行 agentj service restart。不要把密钥写进 plist、聊天或命令参数。

群聊要在 telegram.groups 里写明群的编号，以及允许发言的成员的数字 ID，两样都对上才处理。代理群（默认）里要 @ 机器人或者回复它，它才接话；家庭群里，名单上成员的普通消息也会处理。发回群里的内容会先去掉网址、路径和地址这类信息。

telegram: {
  groups: [
    { id: "-1001234567890", members: [123456789], profile: "family", label: "家里" }
  ]
}

群里的人可以在 names 里配上称呼（只认名单里的数字 ID），Agent 就知道是谁在说话。telegram.private_domains 写上你自己的域名，发往任何群的回复都会隐去这些域名和它们的子域名；邮箱地址一律隐去。家庭群里被拦下的消息，机器人会在群里礼貌拒绝，你的手机上只多一行提示，不带原话。同一批消息按你的私聊、家庭群、代理群的顺序处理；一组相册算一轮；群升级成超级群后编号会自动跟上；你私聊里的命令菜单和家庭群的 /notification 会自动同步到 Telegram。

私聊和群聊回复时，常用 Markdown 会自动转成 Telegram 格式。要是 Telegram 不认某个格式片段，就会用纯文本重发同样的内容。

telegram.owner_commands 可以让你私聊里的某个命令直接由你电脑上的程序回答，不经过 Agent：程序的输出只发回你的私聊，不进对话、历史和日志，每小时有次数上限，程序必须是你自己的、别人改不了的可执行文件。手机上每条回复下面的分享按钮，配好 Telegram 后一点就发到你自己的私聊（telegram.forward，默认开）；没配时用手机自己的分享。

Telegram 不能批准任何操作。端到端加密、已配对设备签名审批，都不能用配置关闭。

预装准备可先放入 JSON5、校验，再运行 agentj init 和首次向导。镜像不能复制身份密钥、设备审批状态或云 key。遥控器配对密码和设备配对仍需本人操作；本轮不提供镜像。

受限地区：代理怎么配

优先用 Claude Code。所在地区（比如香港）连不上模型服务时，最简单的办法是对电脑上的 Agent 说：「帮我把代理设成 http://127.0.0.1:7890」（换成你本机代理软件的端口）。它会运行 agentj config set proxy.https http://127.0.0.1:7890。不要把代理密码、订阅链接或模型 key 发到手机对话里。

这个设置只给 Agent J 替你启动的 Claude Code、Codex 或 OpenCode 进程用，作为 HTTPS_PROXY、HTTP_PROXY 和 NO_PROXY；本机地址不走代理。语音、更新和手机连接都不受影响。设好后，Agent 的进程会在你下一条消息前重启，对话接着聊。共享会话用的是你电脑上原来的进程：代理要在它启动前配好，改了以后请自己重启它。

需要用户名和密码的代理不写进设置。让 Agent 把它存进环境变量，设置里只填变量名，例如 proxy.https_env: "AJ_HTTPS_PROXY"（另有 proxy.http_env 和 proxy.no_proxy_env）。两样都填时，以直接填的地址为准。

OpenCode 的认证分两件事：连接模型服务商，再选择匹配的 provider/model。v1 的 auth.json 或 v2 的 opencode.db 存在，都不能证明 key 有效。v1 的运行时诊断读取 GET /provider 的 connected，这里只表示连接已配置，余额、权限和网络仍须验证。用 opencode auth login 换 key 后，Agent J 会在你下一条消息前重启它启动的 OpenCode，对话不断；也可以让 Agent 运行 agentj agent restart。如果连的是你电脑上自己开的 OpenCode 服务，请自己重启它。出错时，手机上的提示和 agentj doctor 会说明是哪一类：登录或 key（401）、地区（403/451）、权限（403）、余额或额度、限流、模型名称、网络。

OpenCode v1 和 v2 都能用：官方安装脚本现在装的是 v2（2.0.x），Agent J 启动 OpenCode 时会自己认出版本，独立会话（默认）和共享会话都一样。v2 允许同一个服务商存好几把 key（比如「DeepSeek 2」），但只有选中的那一把生效；换了新 key，运行 opencode auth switch <服务商> 选中它。如果 OpenCode 里根本没有所选服务商的 key（比如 key 只在终端里 export，后台服务看不到），手机上会直接说明是哪个服务商缺 key，存好之后再发一条消息就行。你在电脑上自己开着的 OpenCode 服务（设置了 agent.shared_opencode_port 和 agent.shared_session_id）v1、v2 都能接：手机上能发文字、批准请求，你在电脑上打的字和回复也会同步到手机；换模型、斜杠命令仍在电脑上操作。接 v2 服务时「高危操作提醒」用不了，要用它就去掉端口设置，让 Agent J 自己启动 OpenCode。你的 server 设了密码的话，Agent J 不会去读别的程序的环境变量：手机上会提示一条 agentj secret request --name OPENCODE_SERVER_PASSWORD --purpose "Your OpenCode server password" --dest "env:<Agent J service env file>#OPENCODE_SERVER_PASSWORD" 命令，在电脑上运行它、在手机的密钥卡片里贴上密码，再 agentj service restart 就能接上。403 也可能是地区或权限限制，不一定是 key 错了。

如果你从第三方服务商拿到的是一个 base_url 加一把 key（OpenAI 兼容或 Anthropic 兼容），让 Agent 运行 agentj provider add <名字> --base-url <地址> --model <模型>。它把这个服务商写进 OpenCode 的配置，配置里只记 key 的变量名；key 本身由你在手机的密钥卡上粘贴，Agent 看不到。之后把模型换成 <名字>/<模型>，重启一次服务即可。

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

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

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

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

Claude 手机消息与服务登录

共享 Claude 接收手机消息，不用在电脑上逐条确认。选择共享模式、Agent J 启动和 agentj doctor 时，都会检查 Claude Code 在工作目录里实际生效的值（组织策略 > 该目录私有的 .claude/settings.local.json > 该目录的 .claude/settings.json > 你的 ~/.claude/settings.json）。用户设置或私有本地设置里的拦截会就地改成放行；共享项目文件里的拦截从你私有的本地层覆盖，不改团队文件。组织策略、refuse 和你自己运行的 agentj config claude-inbound off 只报告、不改。改之前先备份。改设置之前就启动的 Claude Code 会话仍用旧设置，在它里面执行 /clear 或开新会话后生效。手机提示尚未接收时会说明具体原因：组织策略、项目设置、你关掉了、需要 /clear，或电脑正忙。先看电脑再决定是否重发，原消息仍可能送达。agentj config claude-inbound on|off|status 修改或查看实际生效的设置。macOS/Linux 的 Claude socket 以同一操作系统用户为边界，认证帧并非强制要求；Agent J 始终发送本机 peer token 认证帧。该用户下其他进程的消息也会被接受。

共享模式沿用电脑上活会话的登录。切换到独立模式前，Agent J 会检查服务是否有登录；没有就保留共享模式。在电脑终端运行 claude 并 /login 一次（Mac 存进钥匙串），或运行 claude setup-token 后自己把 token 写入服务专用 env 文件，权限设为600：Linux 用 ~/.config/systemd/user/agentj.env，Mac 用 ~/Library/LaunchAgents/net.agentj.host.env。不要把 token 发到聊天里。旧版 Mac 服务先运行一次 agentj service install 加上 env 文件路径，改完 env 后运行 agentj service restart。LaunchAgent plist 只存路径，不存 token。

登录过期时不用回电脑：手机设置 →「紧急修复」→ ③「AI 账号登录失效」→「AI 登录救援」重新登录（Codex 设备码；Claude 授权链接，授权码只贴进密钥卡）。用手机换上的 Claude 长期 token 会记下日期、按一年推算到期日，到期前第 7、3、1 天各提醒一次，点「现在续期」在手机上授权一次就换上新的；新 token 实测通过才替换，没通过保留原来的。没有固定到期日的登录（订阅 /login、Codex 的 ChatGPT 登录、服务商密钥），电脑每天发一条不带工具的极短测试消息，失效立刻提醒。

共享 Claude 的模型和额度条

选择共享 Claude 时额度条也默认开启：手机显示同一会话的模型、思考深度、周额度、5 小时额度和上下文水位，并提示一次。运行 agentj config claude-statusline off 后会记住你的选择，不再自动开启。原状态栏命令收到的输入和输出都保留。设置先备份、再原子写入；off 精确恢复原值（只为 tap 新建的私有本地文件会删掉），主人之后的编辑不会被覆盖。手机只使用同一会话的测量值，并显示数据年龄，重新连接也不会让旧数据变新。组织策略设定的状态栏不改，agentj doctor 会报告。

状态栏 tap 装在 Claude Code 对工作目录实际生效的那一层；本地或项目里原有的状态栏会从你私有的本地层串联起来，照常运行。更高一层把它遮住时，status 显示 shadowed，agentj doctor 指出是哪一层，手机显示「—」；运行 agentj config claude-statusline on（下次启动也会，除非你关掉了）会在实际生效的那一层重新串联。模型/思考强度标签和 /model <名字> [强度] 在电脑空闲时，通过 Claude Code 自己的 /model 选择器切换共享会话，只对本会话生效；要等本会话的状态栏显示新模型才算成功。/cost 显示 Claude Code 自己报告的本会话花费。想给主 Agent 加上你自己的长期规则，就把 agent.private_instructions_file 指向一份本机文本文件：它作为文字追加在核心身份之后，不授予任何权限；用 agentj config private-instructions status 检查。

升级后的重装与启动由独立的服务任务执行，当前会话退出也会继续。Linux 使用单独的 systemd 用户任务，macOS 使用一次性 launchd 任务。若启动失败，下次启动会提示，agentj doctor 会报错；在电脑运行 agentj service start 后再运行 agentj doctor。agentj service stop 停止后台服务并保留安装；start 在未安装时自动安装。

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

装好 AI 命令行工具 · agentj 命令参考

让电脑保持唤醒：命令、系统设置和可发给 Agent 的请求。

Agent J 专用浏览器与登录保活：管登录、每天体检、手机扫码卡，还有「早上好」。

接 Kimi Code

agentj agent kimi --dir <目录>：接上 Kimi Code CLI（kimi 2.2.0 以上）。Kimi 会员在海外站 kimi.ai 的加 --region global；默认是国内站 kimi.com（--region mainland-cn）。只支持独立会话。
agentj agent switch kimi：从别的工具安全切过来（先检查，不通自动切回），见换 AI 编程工具。
agentj agent detect 会列出 Kimi Code 的版本和有没有登录；agentj doctor 还会说出 ~/.kimi-code/config.toml 里有几条不经手机卡片就放行的规则。
登录：在你自己的终端运行 kimi login --region mainland-cn（或 global），或者用手机上的 AI 登录救援（设备码）。

接 Qwen Code

agentj agent qwen --dir <目录>：接上 Qwen Code（qwen 0.25 以上），想省额度再加 --model qwen3.8-flash。只支持独立会话。
agentj agent switch qwen：从别的工具安全切过来，见换 AI 编程工具。
agentj agent detect 会列出 Qwen Code 的版本、有没有 key 或你自己的设置；agentj doctor 还会数出 ~/.qwen/settings.json 里有几条不经手机卡片就放行的 permissions.allow 规则。
key：agentj provider bailian 会打印手机密钥卡命令（BAILIAN_TOKEN_PLAN_API_KEY），见阿里百炼 Token Plan。

接 DeepSeek dsh

agentj agent dsh --dir <目录> --base-url https://<服务>/v1 --model <模型 id>：接上 DeepSeek 的编程工具 dsh（DeepSeek Harness 0.2.0-rc.2 以上，还是预览版），模型用 Olares Router 或任何 OpenAI 兼容服务。不加 --base-url，就用你自己配好的 dsh，或者 DeepSeek 官方 API 的 key。只支持独立会话。
agentj agent switch dsh：从别的工具安全切过来，见换 AI 编程工具。
agentj agent detect 会列出 dsh 的版本、有没有模型路线或登录；如果 ~/.dsh 里的设置会改动 dsh 的审批或插件，Agent J 不会启动它，agentj doctor 会指出是哪个文件，挪走就好。
key：服务要 key 时，Agent 会发手机密钥卡（DSH_ROUTER_API_KEY；DeepSeek 官方 API 用 DEEPSEEK_API_KEY），见DeepSeek dsh。

Once it is set up you mostly use your phone. The computer only needs to stay on, and now and then you change a setting. This page lists the commands for that.

Everything below runs in a terminal, and you can ask the AI on your computer to do any of it for you — only pairing a phone is yours, and that happens on the account page or a paired phone, not in a terminal. The remote pairing password is optional; see below.

When the Agent needs an admin password or an API key, a card pops up on your phone, so you don't have to walk back to the computer: see Admin rights and API keys, from your phone. When Agent J itself has a problem, the Agent asks our support desk first: see Getting help from the support desk.

Check how things are

agentj

agentj

agentj doctor

agentj doctor

agentj status

agentj status

agentj on its own: which setup steps are done and what comes next.
agentj doctor: a health check, one line per item — ✓ fine, ! worth a look, ✗ needs fixing, each with how to fix it.
agentj status: whether the background program is running and connected.

Every command: agentj --help.

Keep it running

During setup the AI installed it as a service, so it starts by itself when the computer starts and you log in.

agentj service status

agentj service status

agentj service install

agentj service install

agentj service uninstall

agentj service uninstall

status: is the service running?
install: install and start the service (a systemd user service on Linux, a LaunchAgent on a Mac).
uninstall: stop and remove it.

install (and every update) also sets up a small rescue helper. When Agent J stops answering, it keeps the phone's Settings → Emergency repair working; uninstall removes it too. Check it with agentj rescue status; see Phone grey or disconnected?.

On a Mac, System Settings → General → Login Items & Extensions → "App Background Activity" shows Agent J's rows: this service, one for its rescue helper, and one more if you set up the Agent J browser. The service row reads "Agent J" with the robot icon and the signing developer's name: the service is started by a small Apple-notarized program, Agent J.app, kept in your personal Applications folder (~/Applications) — please leave it there. If the signed copy cannot be downloaded, Agent J falls back to the old way and the row reads agentj with "Item from unidentified developer"; everything still works. The rescue helper's row still reads that way for now. The one-shot jobs used for upgrades and Agent switches are no longer registered there and are deleted when they finish; the ones older versions left behind are cleaned up after you upgrade. Leave these switches on, or the service will not start by itself after a restart.

On a cloud server, where nobody stays logged in, run loginctl enable-linger $USER once before agentj service install.

If you'd rather not use a service, run agentj serve in a terminal window instead; it stops when the window closes.

Note: while the computer is off, asleep or offline, your phone cannot reach it. When the computer is back, it reconnects by itself.

The local Agent settings page

agentj admin

This prints a link in the terminal. Open it in a browser on the same computer and you get this computer's own Agent settings page, where you can:

pair a new phone (tap "Add a phone remote");
see the paired phones under "Phone remotes" ("Full" at 10) and unlink one;
rename the Agent under "The Agent's name";
switch "Unlinking from the account dashboard" on or off (the box "Allow unlinking this computer's phone remotes from the account dashboard");
check under "Connection" whether "The agentj program" is running, the "Relay server" is connected and the computer is in an Agent J account.

The page's "Good to know" box says it plainly: one person per Agent works best, and the 10 phone remotes are meant for the same person's phone, tablet and computer.

The page only opens on this computer — not on another computer or a phone. The link works once, for 10 minutes. Press Enter in the terminal for a fresh link (the old one stops working at once); press Ctrl-C to close the page.

Rather not copy a link? Run agentj admin --open: it opens the page in this computer's default browser and returns at once, without printing the link. The page closes by itself after 30 minutes unused; run it again to reopen. Asking your Agent to "open the admin page" runs exactly this.

On a cloud server over SSH, agentj admin also prints an ssh -N -L … line. Run that line on your own computer, then open the link in your own computer's browser.

Phones and other devices

agentj pair

agentj pair

agentj devices

agentj devices

agentj revoke <device-id>

agentj revoke <device-id>

agentj pair: pair a new phone. The background program has to be running; if it isn't, agentj pair tells you to run agentj service install first. The taps are in On your phone.
agentj devices: list the paired phones and browsers.
agentj revoke <device-id>: cut a device off and remove it straight away (the id is in agentj devices).

Each Agent takes up to 10 phones. When all 10 are used, agentj pair lists them and asks you to unlink one first.

Switch the AI coding tool or the work folder

agentj agent

agentj agent

agentj agent detect

agentj agent detect

agentj agent codex --dir ~/agentj-work

agentj agent codex --dir ~/agentj-work

agentj agent: which AI coding tool is connected and which folder it works in.
agentj agent detect: which AI coding tools on this computer are usable.
agentj agent claude --dir <folder>, agentj agent codex --dir <folder>, agentj agent opencode --dir <folder>: switch to Claude Code, Codex or OpenCode and set the folder. OpenCode also needs --model as provider/model, for example --model zhipuai/glm-5.3.
agentj agent reset: forget the conversation so far; the next message from the phone starts a new one.

Using a model from Volcano Ark, Kimi, Alibaba Bailian or DeepSeek: see Choose by your model.

Session mode: new installs use an independent session — Agent J starts its own, fenced, and changes nothing in your terminal tools. To attach the phone to the session you already have open on this computer instead (advanced), add --shared to any of these; --independent goes back. Each switch says what it means and prints the line that undoes it (agentj config set agent.session_mode independent|shared); the phone's Settings → Session mode does the same. An install upgraded from a version where shared was the default keeps shared (written into your settings file, never switched silently). In shared mode, with several Claude Code sessions open in the folder, it lists them (name, last activity, first message) and you pick one; to change it later: agentj config set agent.shared_session_id <session ID>.

The change takes effect after a restart of the background program:

agentj service uninstall
agentj service install

With Codex in shared mode (the phone and the computer use the same session), the first message from the phone is no longer refused. If no session was picked, it continues the most recent Codex session in that folder; if there is none, it starts a new one and tells you on the phone — codex resume <id> on the computer continues the same one. While the computer is still in the middle of a turn, phone messages wait in line and go out when it finishes (for up to 30 minutes; /stop cancels). If the original session can't be continued, or its permission settings can't be read, your own Codex defaults apply and the phone tells you once. The reasons are recorded in agentj activity, and agentj doctor gets an extra line saying which session will be continued.

Rename the Agent

agentj name

agentj name

agentj name Wren

agentj name Wren

Without a name it shows the current one; with a name it changes it. Keep it short: up to 8 Chinese/Japanese/Korean characters, or 13 letters, digits, hyphens and spaces; mixed, each CJK character counts 1.6 and anything else 1, 13 in all. A longer name given before this rule keeps working until the next rename. No two Agents in one account may share a name. When the computer is in an Agent J account, the name is changed in the account dashboard first, and only then on this computer. You can also rename it in the account dashboard or on the local Agent settings page.

Stop everything

agentj stop

agentj stop

agentj resume

agentj resume

agentj stop: stop everything now. The current work is interrupted, every request waiting for your approval is denied, batch approvals are withdrawn and scheduled tasks are paused. It stays stopped across a restart.
agentj resume: start again. Asks for your remote pairing password if one is set (otherwise you confirm at the keyboard yourself), so the Agent can't lift "Stop everything" itself; tapping "Resume" on a paired phone is enough too.

"Stop everything" in the phone's ≡ menu is the same switch, and tapping "Resume" on the phone works too.

What it remembers

Every time it starts work, the Agent reads a few memory files — Claude Code's CLAUDE.md, for example. You can look at them entry by entry and delete entries:

agentj memory list

agentj memory list

agentj memory show 1

agentj memory show 1

agentj memory rm 1 3

agentj memory rm 1 3

agentj memory restore

agentj memory restore

list: where its memory lives and how many entries each place has.
show <number>: every entry in one place.
rm <number> <entry>: delete one entry. The original goes to a trash folder on this computer for 7 days.
restore: show the trash; agentj memory restore <id> brings one entry back.

The phone's "Memory" page does the same.

What it has done

agentj activity --since 2h

agentj activity --since 2h

agentj approvals --verify

agentj approvals --verify

agentj activity: the activity record — when each conversation turn started and ended, every permission request, who approved or denied it, stops and resumes. --since takes 2h, 3d or a date. The record stays on this computer for 30 days.
agentj approvals --verify: every approval and denial, each checked to really come from one of your paired phones.

Turn the record off with agentj config activity off; delete it all now with agentj activity --clear.

The phone's "Activity" page shows this same record.

Scheduled tasks

If you built workflows that run on a schedule with the workflow design wizard, manage them here:

agentj tasks list

agentj tasks list

agentj tasks show <task>

agentj tasks show <task>

agentj tasks enable <task>

agentj tasks enable <task>

agentj tasks disable <task>

agentj tasks disable <task>

agentj tasks run <task> --dry-run

agentj tasks run <task> --dry-run

New tasks are always installed switched off. Switch one on with enable (your Agent can do it when you ask), or on the phone's "Schedules" page. run --dry-run shows how a task would run without running it.

To build a workflow, say "帮我设计工作流" (help me design my workflows) to the Agent on your phone. It asks you one question at a time.

The remote pairing password

Optional, recommended. It lives only on this computer (at least 8 characters) and has two uses: pairing at this computer's terminal (agentj pair requires it and asks you to set one first), and adding a remote from a browser on another computer signed in to the account page with an email code, where it can stand in for a passkey. Without it you can still add remotes with a passkey on the account page or from a paired phone; but if every remote is ever lost and no passkey is at hand, you'll have to come back to this computer's terminal to set it. The installation asks once whether to set it now; press Enter to skip.

agentj passphrase status

agentj passphrase status

agentj passphrase change

agentj passphrase change

agentj passphrase reset

agentj passphrase reset

status: whether one is set, and whether it is locked after too many wrong tries.
change: change it.
reset: for when you forgot it. Type RESET to confirm. It deletes the old one and unlinks every phone; then set a new one with agentj passphrase set and pair again.

The password needs at least 8 characters; there is no other rule.

Updates

agentj update check

agentj update check

agentj update apply

agentj update apply

agentj update check tells you whether there is a newer version; anyone can run it, the AI included. The first word says how things stand: newer — there is a new version; current — you're up to date; ahead — this computer runs something newer than the public release, nothing to do; unknown — it couldn't check this time (usually no network), try again later.

To upgrade, ask your Agent: it runs agentj update apply itself, installs, restarts, self-checks and tells you the result.

The background program checks once a day and tells your phone when a newer version exists; that daily check never installs anything by itself. To stop it: agentj update auto off.

If this computer has joined an Agent J account, a new release also arrives as an official notice signed by us. The Agent follows your upgrade setting: by default it upgrades and then tells you what changed, or it can ask you first. Urgent security fixes always upgrade right away. Change it under "Upgrade method" in the phone's "Settings", or run agentj config set updates.mode ask on the computer (auto switches back).

We may also send an upgrade email at 9:00 in the morning Japan time, with an upgrade authorization code. Forward it to Agent J and it upgrades itself (agentj update apply --from-email -) without asking you to confirm again. Details: Official notices.

Other switches

agentj report-hostname off: stop sending this computer's name to the account dashboard.
agentj remote-unbind off: don't let the account dashboard unlink this computer's phones; unlinking then happens only on this computer.
agentj unlink: take this computer out of the Agent J account. If it joined with a setup code, the account dashboard drops it too. If it joined with agentj login, only the record on this computer is removed, and you still tap "Remove this Agent (frees a seat)" on its card in the account dashboard.

To uninstall completely, see the last section of Installing. Uninstalling doesn't stop the billing; cancel the subscription under "Manage billing" in the account dashboard.

Personalize your Agent

agentj config path prints the single JSON5 user file (~/.config/agentj/config.json5). It supports comments and trailing commas. Put only overrides there; upgrades preserve your choices while new defaults apply to untouched keys. agentj config keys is the current option list, with defaults, aliases and safety tiers.

Use agentj config get, set, unset, validate, diff, history, rollback and apply. A change validates, persists and activates as one host transaction; failed activation keeps the previous working configuration and reports an error. applied:false means restart/start the host before claiming the phone changed. Listen to a real audio sample after voice changes.

Reload instead of restarting (agentj reload): settings come in three tiers. Most take effect when saved; isolation, Docker, high-risk warnings, approval strength, your added instructions and the Telegram channel take effect on a reload: tap Reload configuration in the phone's ≡ All commands, send /reload, press Alt+Shift+L, or run agentj reload on the computer. The background service keeps running; the main Agent restarts before its next message, same conversation, and a key newly saved in the service key file (a Telegram bot key, say) is read in too. When the Agent changes such a setting with agentj config set it reloads by itself; when you change one on the phone's Settings page, a card offers Reload. Only the working root and the session mode (independent / shared) still need agentj service restart.

agentj skill install installs the bundled agentj-config guide for Claude Code, Codex and OpenCode; ask your AI and it does it. agentj skill uninstall removes only its own links. Existing same-name skills are not overwritten. Your local AI can use this guide and agentj doctor --offline --json for personalization; an Agent in an independent session can't see Agent J's settings file, so change settings from the shared session or the phone's Settings.

Wake phrase defaults to 嘿 + your Agent name; rename propagates when connected. Android background listening is opt-in. Unfamiliar names may need explicit pronunciation. The Android APK is a review build; measured arbitrary-name accuracy and battery acceptance are still pending. the iOS web app cannot wake in the background.

ASR defaults to your host. Cloud ASR uses your own OpenRouter key and sends audio directly to that provider. TTS defaults to installed local phone voices; host TTS and own-key OpenAI or ElevenLabs TTS are alternatives. Cloud TTS sends reply text directly to the selected provider; returned audio crosses our relay as ciphertext. Generic Android notification speech is local and does not expose conversation on the lockscreen. Background phone/cloud autoplay depends on OS/browser policy.

With OpenAI, cloud speech now defaults to gpt-realtime-2.1-mini. OpenAI retires the old gpt-4o-mini-tts on 2027-01-06: if your settings still carry that old default, Agent J switches it to the new model when it starts; any other model you picked yourself stays as it is, and agentj doctor reminds you to check it. With ElevenLabs, eleven_v4 is used unless you name a model.

You can also use a speech program of your own: set voice.tts.mode to host and voice.tts.provider to command, and put the command in voice.tts.command as a list of arguments, with {output} where the file should be written. The program reads the reply text on standard input and writes a WAV file; it is stopped after voice.tts.command_timeout (60 seconds by default). Keep keys out of the command.

Telegram is optional and off by default, and uses a bot of your own. To connect it, save the bot key, then run agentj channel add telegram (or tap 「Re-pair Telegram」 in the phone's Settings): the phone shows a one-time 6-digit code; send /start <code> to your bot in a private chat and that chat becomes the owner. No other bot is needed to look up your ID; anyone else who writes to the bot only gets their own numeric ID back, and a code sent in a group does not count. Text, photos, voice messages, videos and files all work, up to 20 MB each; speech in voice messages and videos is transcribed on your computer, even if the phone is set to cloud recognition. Long-press a message in Telegram, tap Reply and write: the message you replied to goes to the Agent with yours, marked as a quote of a Telegram message (who wrote it and when; up to 300 characters — select part of it first to quote only that part; photos and voice notes appear as "[photo]", "[voice]" and are not downloaded again). Commands inside a quote never run; only what you type yourself counts as a command.

To let this bot receive guests too, turn on 「Let my Agent J Telegram bot receive guests」 in a customer-service bot: your private chat stays the main conversation, and everyone else is served by that bot on its own. See Customer service bots.

On macOS, put Telegram and provider keys in ~/Library/LaunchAgents/net.agentj.host.env, using the variable name specified by key_env. The file must be owned by your user, mode 0600, and not a symlink. After saving it, run agentj service restart. Keep keys out of the plist, chat and command arguments.

For group chats, list each group's ID and the numeric IDs of the members allowed to talk in telegram.groups; a message is handled only when both match. In a proxy group (the default) the bot answers only when mentioned or replied to; in a family group, ordinary messages from listed members are handled too. Before anything goes back to a group, web addresses, paths and similar details are taken out.

telegram: {
  groups: [
    { id: "-1001234567890", members: [123456789], profile: "family", label: "Home" }
  ]
}

Group members can be given names in names (only numeric IDs on the list), so the Agent knows who is speaking. List your own domains in telegram.private_domains: replies to any group hide them and their subdomains; e-mail addresses are always hidden. A family-group message the gate stops gets a polite refusal in the group, and your phone gets one line without the words. Each batch is handled in the order your private chat, family groups, proxy groups; an album is one turn; a group upgraded to a supergroup is followed to its new ID; your private-chat command menu and the family group's /notification are synced to Telegram.

Replies in your private chat and groups render common Markdown as Telegram formatting; if Telegram rejects a formatted part, the same words are sent as plain text.

telegram.owner_commands lets a command in your private chat be answered directly by a program on your computer, without the Agent: its output goes back to your private chat only — never into the conversation, history or logs —, it is rate-limited per hour, and the program must be your own executable that nobody else can modify. The share button under each reply on the phone sends it to your own private chat in one tap once Telegram is set up (telegram.forward, on by default); without Telegram it uses the phone's own share sheet.

Telegram never approves anything. End-to-end encryption and signed paired-device approvals cannot be disabled by configuration.

Preinstalled-image preparation: preseed the JSON5 file, validate it, then run agentj init and the first-run guide. Never clone identity keys, device approval state or cloud keys into an image. The remote pairing password and device pairing remain human steps. No image is shipped here.

Restricted regions: configure a proxy

Prefer Claude Code. If the model provider is unreachable where you are (Hong Kong, for example), the simplest way is to tell the Agent on your computer: "Set my proxy to http://127.0.0.1:7890" (the port of your local proxy app). It runs agentj config set proxy.https http://127.0.0.1:7890. Never paste proxy passwords, subscription links or model keys into phone chat.

The setting reaches only the Claude Code, Codex or OpenCode process Agent J starts for you, as HTTPS_PROXY, HTTP_PROXY and NO_PROXY; local addresses bypass it. Voice, updates and the phone connection are not affected. The Agent's process restarts before your next message and the conversation continues. A shared session uses your own desktop process: set its proxy before starting it, and restart it yourself after a change.

A proxy that needs a username and password is not written into the settings. Ask the Agent to keep it in an environment variable and set only the variable's name, for example proxy.https_env: "AJ_HTTPS_PROXY" (also proxy.http_env and proxy.no_proxy_env). If both are set, the address wins.

OpenCode needs a provider connection and a matching provider/model. An existing v1 auth.json or v2 opencode.db does not prove a working key. The v1 runtime diagnostic uses GET /provider and its connected list; this records configured connections, not a live balance or key test. After you replace a key with opencode auth login, Agent J restarts the OpenCode it started before your next message and keeps the conversation; you can also ask the Agent to run agentj agent restart. If Agent J is attached to your own desktop OpenCode server, restart that server yourself. Phone failure lines and agentj doctor name the kind of failure: sign-in or key (401), region (403/451), access (403), balance or quota, rate limit, model name, network.

Both OpenCode v1 and v2 work: the official install script now installs v2 (2.0.x), and Agent J detects the version when it starts OpenCode, in the independent (default) and the shared mode alike. v2 can store several keys for one provider (for example "DeepSeek 2"), but only the selected one is used; after adding a new key, run opencode auth switch <provider> to select it. If OpenCode has no key at all for the selected provider (for example, the key is only exported in your terminal, which the background service cannot see), the phone says so and names the provider; store the key, then just send again. An OpenCode server you started yourself (agent.shared_opencode_port and agent.shared_session_id set) can be attached on v1 and v2: the phone sends text and answers approvals, and what you type at the computer (and the replies) shows up on the phone; model changes and slash commands stay on the computer. On a v2 server of your own, high-risk warnings are unavailable — to use them, remove the port setting so Agent J starts OpenCode itself. If your server has a password, Agent J never reads another program's environment: the phone shows an agentj secret request --name OPENCODE_SERVER_PASSWORD --purpose "Your OpenCode server password" --dest "env:<Agent J service env file>#OPENCODE_SERVER_PASSWORD" line — run it on the computer, paste the password on the phone's secret card, then agentj service restart. HTTP 403 can mean region or account/model access restrictions, not necessarily an invalid key.

If a third-party provider gave you a base_url and a key (OpenAI-compatible or Anthropic-compatible), ask the Agent to run agentj provider add <name> --base-url <url> --model <model>. It declares the provider in OpenCode's config, which references the key by variable name only; you paste the key itself on the phone's secret card, so the Agent never sees it. Then switch the model to <name>/<model> and restart the service once.

Add a remote for another computer

Once the target computer 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 target computer's terminal isn't needed. Confirm either way: with your passkey (none on this computer? choose Use a phone or tablet in the prompt and confirm on your phone), or with that computer's remote pairing password. After a passkey confirmation, the same session doesn't ask again for ten minutes; 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 computer 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 your computer.

Account-page pairing is on by default. The target computer’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.

Shared Claude takes phone messages without confirming each one on the computer. When you select it, when Agent J starts and in agentj doctor, Agent J checks the value Claude Code really uses in your work folder (organization policy, then the folder's private .claude/settings.local.json, then its .claude/settings.json, then your ~/.claude/settings.json). A hold in your user or private local settings is switched to accept where it is; a hold in the shared project file is overridden from your private local layer, never by editing the team file. Organization policy, refuse and your own agentj config claude-inbound off are only reported. Settings are backed up first. A Claude Code session started before the change keeps the old setting until you run /clear in it or start a new one. If the phone reports an unacknowledged message, it names the reason: organization policy, project settings, you turned it off, the session needs /clear, or the computer is busy. Check the computer before sending again because the original may still arrive. agentj config claude-inbound on|off|status changes or shows the effective setting. On macOS/Linux, Claude makes the auth frame optional; Agent J always sends the local peer token authentication frame. Other processes of the same user can also send.

Shared mode uses your live desktop session login. Before switching to independent mode, Agent J checks that the service has a login; otherwise it keeps shared mode. Run claude and /login in a computer terminal (Keychain on Mac), or claude setup-token and write the token yourself in the service's private 0600 env file: Linux ~/.config/systemd/user/agentj.env, Mac ~/Library/LaunchAgents/net.agentj.host.env. Never paste it into chat. An older Mac service needs agentj service install once to add the env-file path; then restart with agentj service restart after changing the env file. Token values are never embedded in the LaunchAgent plist.

No need to go back to the computer when a login expires: phone Settings → Emergency repair → ③ AI account signed out → AI login rescue signs it in again (Codex device code; Claude authorize link, the code only into the secret card). A long-lived Claude token stored from the phone has its date written down; one year on is its expiry, you are reminded on day 7, 3 and 1 before it, and Renew now replaces it after one approval on the phone — only once the new token passes a live check, otherwise the old one stays. Logins without a fixed expiry (subscription /login, Codex's ChatGPT sign-in, provider keys) get one very short tool-free test message a day; a failure is reported at once.

Shared Claude model and quota bars

Selecting shared Claude also turns these bars on: the phone shows the same model, effort, weekly/5-hour quota and context readings, and tells you once. If you run agentj config claude-statusline off, that choice is remembered and it is never switched back on by itself. The original status-line command receives the same input and keeps its output. Settings are backed up and written atomically; off restores the original value exactly (a private local file created only for the tap is removed) and refuses to overwrite later edits. Only matching-session measurements are used; the phone reports their age even after reconnect. An organization policy that sets the status line is never changed; agentj doctor reports it.

The tap goes into the settings layer Claude Code really uses for your work folder; an existing local or project status line is chained from your private local layer and keeps running. If a higher layer hides it, status says shadowed, agentj doctor names that layer and the phone shows —; agentj config claude-statusline on (and the next start, unless you turned it off) chains it again at the layer in effect. The model/effort label and /model <name> [effort] switch the shared session through Claude Code's own /model picker, for this session only, when the desktop is idle; success needs the session's own status line to show the new model, and /cost shows Claude Code's own cost for the session. To give the main Agent your own standing rules, point agent.private_instructions_file at one local text file: it is appended after the core identity as text only and grants no permission; check it with agentj config private-instructions status.

Upgrade recovery runs in a separate service-manager job, so it continues after the calling session exits: a systemd user task on Linux and a one-shot launchd task on macOS. A failed recovery appears in doctor and on the phone at the next start. Run agentj service start, then agentj doctor. agentj service stop stops the background service while retaining its installation; start installs it if needed.

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; run codex login on the computer when login expires. Redacted native errors remain under Details.

Set up AI command-line tools · agentj command reference

Keep your computer awake: commands, system settings and a request to send your Agent.

Agent J's own browser and staying signed in: sign-ins, the daily check, the phone QR card and "good morning".

Kimi Code

agentj agent kimi --dir <folder>: connect Kimi Code CLI (kimi 2.2.0+). Add --region global when the Kimi membership is on kimi.ai; the default is kimi.com (--region mainland-cn). Independent session only.
agentj agent switch kimi: the guarded switch from another tool (checked first, switched back on failure) — see Switch AI coding tool.
agentj agent detect lists Kimi Code with its version and whether a login exists; agentj doctor also names allow rules in ~/.kimi-code/config.toml that would run without a phone card.
Sign in with kimi login --region mainland-cn (or global) in your own terminal, or from the phone's AI login rescue (device code).

Qwen Code

agentj agent qwen --dir <folder>: connect Qwen Code (qwen 0.25+); add --model qwen3.8-flash to save Credits. Independent session only.
agentj agent switch qwen: the guarded switch from another tool — see Switch AI coding tool.
agentj agent detect lists Qwen Code with its version and whether a key or your own settings exist; agentj doctor also counts permissions.allow rules in ~/.qwen/settings.json that would run without a phone card.
The key: agentj provider bailian prints the phone key card (BAILIAN_TOKEN_PLAN_API_KEY); see Bailian Token Plan.

DeepSeek dsh

agentj agent dsh --dir <folder> --base-url https://<server>/v1 --model <model id>: connect DeepSeek's coding agent dsh (DeepSeek Harness 0.2.0-rc.2+, a developer preview) to an Olares Router or any OpenAI-compatible server. Without --base-url it uses your own dsh setup or a DeepSeek API key. Independent session only.
agentj agent switch dsh: the guarded switch from another tool — see Switch AI coding tool.
agentj agent detect lists dsh with its version and whether a route or login exists; if a file in ~/.dsh would change dsh's approvals or plugins, Agent J does not start it and agentj doctor names the file — move it aside.
The key: if the server needs one, the Agent sends a phone key card (DSH_ROUTER_API_KEY; DeepSeek's own API: DEEPSEEK_API_KEY); see DeepSeek dsh.

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