文档Docs
安装Installing Agent J
先选你的Agent J 主机(Windows、macOS、Linux),再选一种装法:自己一条命令、让Agent J 主机上的 AI 装、云端安装助手,或者请人帮你装。Pick the Agent J host (Windows, macOS, Linux), then one way to install: one command yourself, the AI on the Agent J host, the cloud installation assistant, or a helper.
四种装法装出来的是同一个 Agent J,装好以后都在手机上跟它说话。拿不准就选①。
Windows
适用于 Windows 10 和 Windows 11(64 位)。Agent J 运行在微软的 Linux 子系统(WSL2)里的 Ubuntu 上,安装命令会先把它装好,你不用提前准备。
① 自己装:一条命令
什么时候选它: Agent J 主机上还没有 AI 工具,或者你想自己动手。全程只用一个码:账户页空席位卡上的安装码(AJI- 开头)。
预计时间: 通常 15 到 30 分钟,大部分是在下载;第一次装 WSL 可能要重启一次。要你动手的部分加起来几分钟。
- 在账户页 https://agentj.app/account/ 的空席位卡点「获取专属安装命令」,再点「复制安装命令」。在 Windows 上打开账户页,给的就是 PowerShell 那一条;不是的话点「换成 Windows(PowerShell)命令」。
- 打开 PowerShell(开始菜单里搜 PowerShell,不用管理员身份),粘贴,回车。命令长这样:
$env:AGENTJ_CODE='AJI-…'; irm https://agentj.app/install.ps1 | iex - 照屏幕走。每一步开头都写着这是第几步、在做什么:
| 屏幕上 | 你要做的 |
|---|---|
| 安装码 | 命令里带了码就直接用;没带会让你粘贴一次(不显示) |
| WSL2 和 Ubuntu | 弹出管理员确认窗口时点同意;要重启就重启,重启后再粘贴同一条命令 |
| Ubuntu 用户 | 起个用户名(直接回车用默认的),设一个密码(输入时不显示,记住它) |
| 系统组件 | 不用做,Windows 上不问密码 |
| AI | 已经登录过 Claude Code 或 Codex 就直接用。没有就选一条路:连不上官方服务选 Agents Relay 中转(见香港和中国大陆),能连就在浏览器里登录官方账号 |
| Agent J | 不用做:装好、启动后台服务、用同一个码绑定这个席位 |
| 手机 | 屏幕上出现二维码:用你自己的手机打开 https://m.agentj.app ,点「扫二维码」扫它 |
| 接上 AI | 不用做:AI 先真实回复一次才接上 |
| 永不休眠 | 显示要你自己在 PowerShell 里做的 Windows 电源设置;Ubuntu 里不改任何东西(详细说明) |
多一个选项:AI 那一步的菜单里还有第 6 项「用 OpenCode 自带的免费模型先跑起来」:不登录、不填 key,先用起来;对话和代码会发给 OpenCode 和它的模型供应商。它优先选不拿对话训练的免费模型;免费模型有限流、随时可能下线,敏感工作请之后换成自己的模型(手机「模型与 Key」)。其他选项和默认推荐都不变。
- 看到「✅ 全部完成」,就在手机上跟它打个招呼。以后要在Agent J 主机上用
agentj,从开始菜单打开「Ubuntu」,不是 PowerShell。
出了问题:
- 中途哪一步失败,屏幕上会写一行「怎么办:…」。修好后粘贴同一条命令,做完的步骤会跳过。
- 安装码只能用一次,24 小时内有效(卡片上写着到期时间)。
- 已经装好、只差 AI,或旧版升不上去:在「Ubuntu」里再运行一次
curl -fsSL https://agentj.app/install.sh | bash(不用带码)。它先看版本:旧版会直接从 agentj.app 下载签名安装包修复升级(不用旧版的agentj update,不连 GitHub;席位、配对和设置都保留),再只补接 AI 这一步。 - 确认 systemd 已开启:后台服务靠它运行。在「Ubuntu」里运行
ps -p 1 -o comm=,应该显示systemd。不是的话,在「Ubuntu」里运行printf '[boot]\nsystemd=true\n' | sudo tee -a /etc/wsl.conf(文件里[boot]下已经有systemd=true就跳过),再在 PowerShell 里运行wsl --shutdown,重新打开「Ubuntu」后运行agentj service install。安装命令会自己做这两步;agentj service install和升级遇到没开 systemd 时,也会用一句话告诉你这两步。
② 让Agent J 主机上的 AI 帮你装
什么时候选它: 你已经在 WSL 的 Ubuntu 里用 Claude Code、Codex 或 OpenCode,想让它替你操作、边装边解释。Windows 上 Agent J 只能装在 WSL2 里,装在 Windows 本身的 AI 会停下来告诉你;还没有 WSL 的话,选①更省事。
- 已经买了席位:在账户页空席位卡上点「复制安装提示词」,发给 Ubuntu 里的 AI。
- 还没买:把下面这句话原样发给它,它会带你注册账号、买席位:
请用 curl 把 https://agentj.app/install.md 下载到本地,用读文件的工具完整读完,然后一步一步照着做,每一步开始前重读那一节。需要我动手的时候告诉我。
AI 每一步做什么、哪几步会停下来叫你,见让 AI 装的时候。
③ 远程安装助手(云端)
什么时候选它: 身边没人帮忙,Agent J 主机上也没有 AI,装到一半卡住了想问人。
现在这样用:
- 照①的命令装。这条命令本身就是安装助手:每一步在做什么都写在屏幕上,出错时会写一行「怎么办:…」。照着修好,再粘贴同一条命令接着装。
- 还是弄不明白,而 Agent J 已经装上了:在「Ubuntu」里运行下面这条命令。它把你的问题和去掉了密钥的体检结果发给我们服务器上的客服,一般几分钟内回你具体步骤。
agentj support ask "<你的问题>" --attach-doctor
- 还没装上,或者连不上我们:发邮件到 feedback@agentj.app,写清卡在哪一步、报错原文,附上截图(先遮住安装码、key 和二维码)。
提示:后续版本计划让云端助手直接在你的手机上给出下一步建议,你点了才执行。
④ 请人帮你装:在旁边或远程
什么时候选它: 你不熟悉Agent J 主机或终端,有家人、朋友或同事能坐在旁边,或者通过视频通话、屏幕共享帮你。
现在的做法:
- 帮手照①带着你做。码只在你自己的账户页复制,只粘在你自己的Agent J 主机上;远程帮的时候你共享屏幕、帮手口头指挥,码和 key 不要发进聊天。
- 中途会弹出 Windows 的管理员确认窗口,可能还要重启一次。帮手提前跟你说一声,你就不会慌。
- 扫二维码配手机,用你自己的手机。如果扫的是帮手的手机,它就成了这台Agent J 主机的遥控器:装完以后运行
agentj devices找到它的设备号,再运行agentj revoke <设备号>把它移走。 - 当时手机不在手边,或者扫码那一步没配上,不用重装:装好以后在账户页这台Agent J 主机的席位卡上点「添加遥控器」,用通行密钥确认,再用你的手机扫码。
提示:一键帮手配对计划在后续版本推出:帮手用自己的手机临时连上,在手机上带你装完;你的手机配好、AI 接上以后,帮手自动断开。
macOS
适用于 Apple 芯片和 Intel 芯片的 Mac。
① 自己装:一条命令
什么时候选它: Agent J 主机上还没有 AI 工具,或者你想自己动手。全程只用一个码:账户页空席位卡上的安装码(AJI- 开头)。
预计时间: 一般 10 分钟以内。机器自己跑只要几分钟(我们的测试机上约 2 分钟),其余是你登录 AI、扫码的时间。
- 在账户页 https://agentj.app/account/ 的空席位卡点「获取专属安装命令」,再点「复制安装命令」。在 Mac 上打开账户页,给的就是终端那一条;不是的话点「换成 macOS / Linux 命令」。
- 打开终端(按 Command + 空格,搜 Terminal),粘贴,回车。命令长这样:
curl -fsSL https://agentj.app/install.sh | bash -s -- AJI-… - 照屏幕走。每一步开头都写着这是第几步、在做什么:
| 屏幕上 | 你要做的 |
|---|---|
| 安装码 | 命令里带了码就直接用;没带会让你粘贴一次(不显示) |
| 系统组件 | 可能要输入一次Agent J 主机密码(输入时不显示) |
| AI | 已经登录过 Claude Code 或 Codex 就直接用。没有就选一条路:连不上官方服务选 Agents Relay 中转(见香港和中国大陆),能连就在浏览器里登录官方账号 |
| Agent J | 不用做:装好、启动后台服务、用同一个码绑定这个席位 |
| 手机 | 屏幕上出现二维码:用你自己的手机打开 https://m.agentj.app ,点「扫二维码」扫它 |
| 接上 AI | 不用做:AI 先真实回复一次才接上 |
| 永不休眠 | 手机配对好以后问一次。直接回车就是同意(推荐):插着电不自动睡眠。合盖会再问一次;同意后合上盖子的 Mac 既不睡也不关机,出门前要自己关机。每项改动都在手机上弹密码卡(详细说明) |
多一个选项:AI 那一步的菜单里还有第 6 项「用 OpenCode 自带的免费模型先跑起来」:不登录、不填 key,先用起来;对话和代码会发给 OpenCode 和它的模型供应商。它优先选不拿对话训练的免费模型;免费模型有限流、随时可能下线,敏感工作请之后换成自己的模型(手机「模型与 Key」)。其他选项和默认推荐都不变。
- 看到「✅ 全部完成」,就在手机上跟它打个招呼。装完以后,同一个终端窗口里就能直接用
agentj status。
出了问题:
- 中途哪一步失败,屏幕上会写一行「怎么办:…」。修好后粘贴同一条命令,做完的步骤会跳过。
- 安装码只能用一次,24 小时内有效(卡片上写着到期时间)。
- 已经装好、只差 AI,或旧版升不上去:再运行一次
curl -fsSL https://agentj.app/install.sh | bash(不用带码)。它先看版本:旧版会直接从 agentj.app 下载签名安装包修复升级(不用旧版的agentj update,不连 GitHub;席位、配对和设置都保留),再只补接 AI 这一步。
② 让Agent J 主机上的 AI 帮你装
什么时候选它: 你已经在用 Claude Code、Codex 或 OpenCode,想让它替你操作、边装边解释。
- 已经买了席位:在账户页空席位卡上点「复制安装提示词」,发给Agent J 主机上的 AI。
- 还没买:把下面这句话原样发给它,它会带你注册账号、买席位:
请用 curl 把 https://agentj.app/install.md 下载到本地,用读文件的工具完整读完,然后一步一步照着做,每一步开始前重读那一节。需要我动手的时候告诉我。
AI 每一步做什么、哪几步会停下来叫你,见让 AI 装的时候。
③ 远程安装助手(云端)
什么时候选它: 身边没人帮忙,Agent J 主机上也没有 AI,装到一半卡住了想问人。
现在这样用:
- 照①的命令装。这条命令本身就是安装助手:每一步在做什么都写在屏幕上,出错时会写一行「怎么办:…」。照着修好,再粘贴同一条命令接着装。
- 还是弄不明白,而 Agent J 已经装上了:在终端里运行下面这条命令。它把你的问题和去掉了密钥的体检结果发给我们服务器上的客服,一般几分钟内回你具体步骤。
agentj support ask "<你的问题>" --attach-doctor
- 还没装上,或者连不上我们:发邮件到 feedback@agentj.app,写清卡在哪一步、报错原文,附上截图(先遮住安装码、key 和二维码)。
提示:后续版本计划让云端助手直接在你的手机上给出下一步建议,你点了才执行。
④ 请人帮你装:在旁边或远程
什么时候选它: 你不熟悉Agent J 主机或终端,有家人、朋友或同事能坐在旁边,或者通过视频通话、屏幕共享帮你。
现在的做法:
- 帮手照①带着你做。码只在你自己的账户页复制,只粘在你自己的Agent J 主机上;远程帮的时候你共享屏幕、帮手口头指挥,码和 key 不要发进聊天。
- 要输入Agent J 主机密码的时候由你自己输,不要告诉帮手。
- 扫二维码配手机,用你自己的手机。如果扫的是帮手的手机,它就成了这台Agent J 主机的遥控器:装完以后运行
agentj devices找到它的设备号,再运行agentj revoke <设备号>把它移走。 - 当时手机不在手边,或者扫码那一步没配上,不用重装:装好以后在账户页这台Agent J 主机的席位卡上点「添加遥控器」,用通行密钥确认,再用你的手机扫码。
提示:一键帮手配对计划在后续版本推出:帮手用自己的手机临时连上,在手机上带你装完;你的手机配好、AI 接上以后,帮手自动断开。
Linux
适用于 Ubuntu、Debian 等常见发行版,台式机、笔记本和云服务器都可以。只能用 SSH 登录、没有桌面的云服务器,还要看安装说明里云服务器那一节。
完整云服务器方案选带 systemd 的虚拟机。普通容器可能不支持隔离或后台服务:安装包后、初始化/登录/绑定席位前,运行 agentj doctor --isolation-only --json。它只用临时文件测试真实隔离,不读客户身份、不联网。退出码非零就停下看 JSON 里失败的 checks(有 reason 再看);通过也不代表平台允许长期后台运行。没有 systemd 用户会话时,tmux/nohup 下的 agentj serve 只是手动降级路线:升级、重启、崩溃后要自行启动,不承诺救援守护、手机紧急修复或 systemd 用户定时任务。详见完整安装说明。
① 自己装:一条命令
什么时候选它: Agent J 主机上还没有 AI 工具,或者你想自己动手。全程只用一个码:账户页空席位卡上的安装码(AJI- 开头)。
预计时间: 一般 10 分钟以内。机器自己跑只要几分钟(我们的测试机上约 2 分钟),其余是你登录 AI、扫码的时间。
- 在账户页 https://agentj.app/account/ 的空席位卡点「获取专属安装命令」,再点「复制安装命令」。在 Linux 上打开账户页,给的就是终端那一条;不是的话点「换成 macOS / Linux 命令」。
- 打开终端,粘贴,回车。命令长这样:
curl -fsSL https://agentj.app/install.sh | bash -s -- AJI-… - 照屏幕走。每一步开头都写着这是第几步、在做什么:
| 屏幕上 | 你要做的 |
|---|---|
| 安装码 | 命令里带了码就直接用;没带会让你粘贴一次(不显示) |
| 系统组件 | 会装 bubblewrap(Agent J 隔离);只有 Claude Code 自带沙箱需要 socat,可能要输入一次Agent J 主机密码(输入时不显示) |
| AI | 已经登录过 Claude Code 或 Codex 就直接用。没有就选一条路:连不上官方服务选 Agents Relay 中转(见香港和中国大陆),能连就在浏览器里登录官方账号 |
| Agent J | 不用做:装好、启动后台服务、用同一个码绑定这个席位 |
| 手机 | 屏幕上出现二维码:用你自己的手机打开 https://m.agentj.app ,点「扫二维码」扫它 |
| 接上 AI | 不用做:AI 先真实回复一次才接上 |
| 永不休眠 | 手机配对好以后问一次。直接回车就是同意(推荐):插着电不自动睡眠,合上盖子也不睡,开机不用登录 Agent J 也自动运行。每项改动都在手机上弹密码卡(详细说明) |
多一个选项:AI 那一步的菜单里还有第 6 项「用 OpenCode 自带的免费模型先跑起来」:不登录、不填 key,先用起来;对话和代码会发给 OpenCode 和它的模型供应商。它优先选不拿对话训练的免费模型;免费模型有限流、随时可能下线,敏感工作请之后换成自己的模型(手机「模型与 Key」)。其他选项和默认推荐都不变。
- 看到「✅ 全部完成」,就在手机上跟它打个招呼。装完以后,同一个终端窗口里就能直接用
agentj status。
出了问题:
- 中途哪一步失败,屏幕上会写一行「怎么办:…」。修好后粘贴同一条命令,做完的步骤会跳过。
- 安装码只能用一次,24 小时内有效(卡片上写着到期时间)。
- 已经装好、只差 AI,或旧版升不上去:再运行一次
curl -fsSL https://agentj.app/install.sh | bash(不用带码)。它先看版本:旧版会直接从 agentj.app 下载签名安装包修复升级(不用旧版的agentj update,不连 GitHub;席位、配对和设置都保留),再只补接 AI 这一步。
② 让Agent J 主机上的 AI 帮你装
什么时候选它: 你已经在用 Claude Code、Codex 或 OpenCode,想让它替你操作、边装边解释。
- 已经买了席位:在账户页空席位卡上点「复制安装提示词」,发给Agent J 主机上的 AI。
- 还没买:把下面这句话原样发给它,它会带你注册账号、买席位:
请用 curl 把 https://agentj.app/install.md 下载到本地,用读文件的工具完整读完,然后一步一步照着做,每一步开始前重读那一节。需要我动手的时候告诉我。
AI 每一步做什么、哪几步会停下来叫你,见让 AI 装的时候。
③ 远程安装助手(云端)
什么时候选它: 身边没人帮忙,Agent J 主机上也没有 AI,装到一半卡住了想问人。
现在这样用:
- 照①的命令装。这条命令本身就是安装助手:每一步在做什么都写在屏幕上,出错时会写一行「怎么办:…」。照着修好,再粘贴同一条命令接着装。
- 还是弄不明白,而 Agent J 已经装上了:在终端里运行下面这条命令。它把你的问题和去掉了密钥的体检结果发给我们服务器上的客服,一般几分钟内回你具体步骤。
agentj support ask "<你的问题>" --attach-doctor
- 还没装上,或者连不上我们:发邮件到 feedback@agentj.app,写清卡在哪一步、报错原文,附上截图(先遮住安装码、key 和二维码)。
提示:后续版本计划让云端助手直接在你的手机上给出下一步建议,你点了才执行。
④ 请人帮你装:在旁边或远程
什么时候选它: 你不熟悉Agent J 主机或终端,有家人、朋友或同事能坐在旁边,或者通过视频通话、屏幕共享帮你。
现在的做法:
- 帮手照①带着你做。码只在你自己的账户页复制,只粘在你自己的Agent J 主机上;远程帮的时候你共享屏幕、帮手口头指挥,码和 key 不要发进聊天。
- 要输入Agent J 主机密码的时候由你自己输,不要告诉帮手。
- 扫二维码配手机,用你自己的手机。如果扫的是帮手的手机,它就成了这台Agent J 主机的遥控器:装完以后运行
agentj devices找到它的设备号,再运行agentj revoke <设备号>把它移走。 - 当时手机不在手边,或者扫码那一步没配上,不用重装:装好以后在账户页这台Agent J 主机的席位卡上点「添加遥控器」,用通行密钥确认,再用你的手机扫码。
提示:一键帮手配对计划在后续版本推出:帮手用自己的手机临时连上,在手机上带你装完;你的手机配好、AI 接上以后,帮手自动断开。
Olares 盒子
Agent J 也能装在 Olares 盒子上(Olares 1.12 或更新),数据留在盒子里。
- 从 Olares 应用市场安装 Agent J:打开应用,把账户页空席位的整段安装提示词粘进设置页。应用自带 OpenCode,默认接 Olares Router,不用另填 Router API key。
- 打开 Olares 应用内的终端:在 Agent J 应用设置页点「打开网页终端」,或在已配对遥控器的「设置」→「安全」点「打开 Olares 网页终端」。新标签页由 Olares 验证登录,终端使用 Agent J 应用内同一个用户、主目录和配置。用
agentj status查看状态,用agentj tasks list --json查看自己的后台任务;不要打印密码、密钥、令牌或完整进程命令行。它不要求开启 Agent J 行模式终端或额外的 Agent J Face ID,也不提供行模式的输出遮挡、操作日志和命令确认。见 Olares 网页终端。 - 到应用市场「管理 → 更新」升级 Agent J:手机
/update和agentj update apply会提示去应用市场;不要在应用内重装 Agent J 或安装 systemd。 - 直接装在盒子 Ubuntu 上的普通安装:用普通用户(不用 root),按云服务器步骤安装和升级;不要装进其他应用的容器。AI 会请你运行一次
sudo loginctl enable-linger <用户名>(密码你自己输),重新登录后安装服务。 - 为 Ubuntu 普通安装接模型:在 Olares Router 应用里新建 API key,通过 DeepSeek 的 dsh 或 OpenCode 接上,key 只粘贴在手机卡片里。见 DeepSeek dsh。
- 远程维护:用官方的 LarePass VPN。助记词由你自己在 LarePass 里导入,绝不交给 AI。手机连 Agent J 不需要这个 VPN。
- 买来时已经预装了 Agent J?:预装的只有软件。激活以后,你用自己的 Agent J 账号登录,自己建席位。
香港和中国大陆:AI 怎么选
注意:在香港和中国大陆,Claude Code、Codex 的官方服务通常连不上。一条命令装到 AI 那一步时会先测网络,连不上就推荐 Agents Relay 中转:先在 https://agentsrelay.net/onboard/ 注册、拿到 key,再回到终端粘贴(输入时不显示)。key 只粘在终端里,不要发进聊天,也不要告诉帮手。
中国大陆也可以用 OpenCode 加国产模型,见装好 AI 命令行工具。
用火山方舟、Kimi、阿里百炼或 DeepSeek,或者还没决定买哪家:见按你用的模型选。
截图之前先遮码
注意:截图发给别人之前,包括发给帮手和客服,先遮住屏幕上的安装码(AJI- 开头)、key 和二维码。这些东西落到别人手里,可能被拿去占用你的席位,或者申请连你的Agent J 主机。
让 AI 装的时候
为什么要先下载、完整读完:有的 AI 用网页工具只读到一份摘要,摘要会把安全规矩和要停下来问你的地方省掉。它开始之前可能先跟你讲讲风险、问你要不要继续,这很正常。
如果别人已经给你付了一个席位,他会发你一句更长的话,里面带一个 ajt_ 开头的设置码。那就直接发那一句,不用发上面这句。
接下来它会自己干活。遇到只有你本人能做的事,它会停下来,用你看得懂的话告诉你要做什么,等你说「好了」再继续。
install.md 是给 AI 看的安装说明,所以用英文写。这一页是同一套流程的大白话版,步骤编号跟它一一对应。
哪些事要你本人来做
AI 不会替你做下面这些事,也不会让你把密码、验证码、口令这类东西发给它。到了这些地方,它一定会停下来叫你:
- 设遥控器配对密码(安装结束时会问你一句,可选,推荐设;在终端里配对时必须有);
它要报告问题时,会先把原文给你看。你同意,才发。见 广场与反馈。
每一步在做什么
下面的编号和 install.md 一样。标了 ✋ 的步骤整步都要你动手,没标的步骤里也可能有一两处要叫你。
第 1 步:核对安装说明
下载安装说明,核对两件事:网站公布的校验值对得上,网站那份和 GitHub 公开那份一字不差。对不上它会停下来告诉你,不会继续装。
第 2 步:准备好反馈
AI 先开一个反馈通道,以后哪一步出了问题,可以把问题报给我们。开通道时不带任何内容,我们只看到你Agent J 主机的 IP 和时间。之后每次发反馈,它都会先把原文给你看。
第 3 步:检查Agent J 主机环境
AI 会检查你的系统,看看 curl、git、uv 在不在。Linux 上还要查 bubblewrap,Mac 不用装,系统自带。它也会看哪些 AI 编程工具已经装好并登录了。至于你用 iPhone 还是安卓,等到第 11 步要用时再问。
Ubuntu 24.04 还会检查 AppArmor 对用户命名空间的限制,并实际试启动一次隔离。限制值是 1 不一定有问题:只要 bubblewrap 的专用权限配置已生效,隔离就能正常运行。缺少 bubblewrap 时需要你确认安装;如果权限仍被拦住,诊断会给出只放行 /usr/bin/bwrap 的 /etc/apparmor.d/bwrap-agentj 配置步骤。已有配置不会自动覆盖,也不会关掉整个系统的限制。安装助手会在启动后台服务前检查;没通过就暂停并保留续装记录,修好后重跑原命令即可。具体命令见 安装说明 的云服务器一节。
这一步可能要你动手:
- 装 bubblewrap 或别的系统软件时,输入你的Agent J 主机密码;
- Claude Code 或 Codex 没登录时,在你自己的终端里登录;
- 在中国大陆,或者一个能用的都没有时,AI 会帮你装 OpenCode。模型账号要你自己去模型厂商那里注册、充值、建 key,再在你自己的终端里运行
opencode auth login把 key 存好。AI 不会碰你的 key,也不会问你要。
第 4 步:安装 agentj 程序
AI 安装Agent J 主机端程序 agentj,装的是固定的一个版本:
uv tool install "git+https://github.com/preangelleo/agentj@v0.30.69#subdirectory=host"
agentj doctor
agentj doctor 会逐行检查,告诉你哪些已就绪、哪些还没好。如果 GitHub 太慢或打不开(比如在中国大陆),AI 会自动改从我们网站下载同一个程序,先核对校验值再安装。
装好以后,你自己的终端也要能找到 agentj,因为第 8 步和第 11 步要你自己运行它。新开的终端找不到的话,AI 会先问你能不能运行 uv tool update-shell:它会在你终端的启动文件里加一行。你同意了它才运行,之后新开一个终端窗口就能用。不想改启动文件,就在要用的终端里先输入 export PATH="$HOME/.local/bin:$PATH",或者新开一个终端试试。
第 5 步:生成这台Agent J 主机的身份
agentj init
这一步给这台Agent J 主机生成它自己的钥匙。钥匙只存在这台Agent J 主机上,谁也不该去碰它,包括 AI。
第 6 步:✋ 注册账号、买席位
如果你发给 AI 的那句话里有设置码(别人给你付的席位),跳过这一步:钱已经付了,你不用注册,也不用付款。
否则,AI 会请你:
- 用浏览器打开账号后台 https://agentj.app/account ,在Agent J 主机上或手机上都行。填邮箱,点「发送验证码」,把邮件里的 6 位验证码填在网页上,点「登录」。验证码 10 分钟内有效,邮件来自 noreply@mail.agentj.app,没收到就看看垃圾邮件。验证码只填在网页上,别发给 AI。
- 按网页提示点「在这台设备上创建通行密钥」,用指纹、面容或屏幕锁确认。要在收到验证码后 10 分钟内做完。Linux 遥控器浏览器一般没有自带的通行密钥:在弹出的窗口里选用手机(扫一下屏幕上的二维码),或者用 USB 安全钥匙;更简单的办法是这一步直接在手机上做。
- 「团队名称(选填)」可以不填,点「开通账号」。
- 在「账单」里买 1 个席位:选「月付」或「年付」,「买几个席位」填 1;有优惠码或邀请码就填在「优惠码或邀请码(可不填)」里;点「购买席位」,到 Stripe 的页面付款。价格和优惠码的规矩见 账号与付款。
- 付完回到账号后台,在「空席位」卡片上点「复制安装提示词」,把这句话发给Agent J 主机上的 AI。它就接着往下装了。
Stripe 付款页上的价格是美元,商户名是 AgentJ.app。第一次付款后 7 天内不想用了,可以全额退款。付完回到账号后台,如果页面让你登录:钱已经付成功了,用通行密钥或邮箱验证码再登录一次就好,别再付一次。
第 7 步:✋ 把这台Agent J 主机加到账号里
AI 先问你:这个 Agent 叫什么名字?比如「小助手」「店铺助手」,或者你自己起的名字。长度最多 13:中文每个字算 1.6,英文字母、数字、空格和符号每个算 1,也就是纯中文最多 8 个字、纯英文最多 13 个字母。然后它用那句话里的设置码,把这台Agent J 主机加到账号的这个席位上,再把加入的是哪个账号告诉你。请你核对一下账号 ID,不对的话它会马上退出来。用完以后,它会把存设置码的那个临时文件删掉。
安装提示词不能用时,回到同一张空席位卡再次复制,会签发新的七天单次码,并作废之前未使用的码。旧八位码入口已经退役,重试不要再买一个席位。
第 8 步:✋ 用账户页通行密钥批准
第一台遥控器只有两个入口:账号页席位卡「添加遥控器」,或自己在终端运行 agentj pair。本地 127.0.0.1 设置页只给账号页跳转。账号页出二维码后保持打开,扫码后自动显示等待配对的遥控器、六位确认码和「批准」按钮;核对两边一致再批准。之后的遥控器打开 https://m.agentj.app 自助申请,由已配对遥控器扫码、核对并批准。
安装结束时会问你要不要设遥控器配对密码(可选,推荐):直接回车就跳过,以后随时运行 agentj passphrase set。Agent 不能替你选择或输入。在终端里配对(agentj pair、agentj pair --link)必须有这个密码,没设的话 agentj pair 会先请你设;agentj pair --check 会在出二维码之前告诉你现在走哪条路。
第 9 步:接上 AI 编程工具
AI 先把自己能查的都查清楚,再用一条短消息一次问你,只问必须你拍板的事。每一项都标好推荐,你回一句「好」就全按推荐办。
- 用哪个 AI 编程工具。
agentj agent detect --json会列出能用的。只有一个能用就直接用它,不问你;有两个以上,它列出来让你选。只有这一项不给推荐,因为它不替你挑。 - Agent 在哪个文件夹里干活。 它先找你平时放项目的文件夹(比如
~/coding),找到就推荐它;没有就推荐新建~/coding。第一次用,新建一个空文件夹(比如~/agentj-work)也行。然后运行:
agentj agent claude --dir ~/agentj-work
用 Codex 就把 claude 换成 codex。用 OpenCode 还要写上模型:
agentj agent opencode --dir ~/agentj-work --model zhipuai/glm-5.3
Agent 会在一个隔离的环境里运行:用你自己的登录和设置,但碰不到 agentj 自己的钥匙和设置。AI 还会看看你Agent J 主机上有没有开着会认你身份的本地服务(比如浏览器的调试端口),用一句话告诉你隔离挡不住什么。
它不会问你浏览器里有没有登录邮箱、购物网站或银行。原因是这样的:手机上的 Agent 以你的身份干活,如果这台Agent J 主机上有浏览器开着调试端口,Agent 就能操作它,用上里面所有已登录的网站。但在任何网站上付款、下单、转账,都一定会先停下来,到手机上问你,不管你登录了什么,所以问了也不会改变什么。真有这样的端口开着,AI 会点名告诉你。
它还会装上「工作流设计向导」,配对好以后,你在手机上说「帮我设计工作流」就能用。
这一步有两件事 AI 一定会做,不会跳过:问你 Agent 在哪个文件夹里干活;单独发一条消息,告诉你隔离挡不住什么。你看过了它再往下走。
第 10 步:让它一直运行
agentj service install
装成系统服务后,Agent J 主机开机登录后它会自己启动,不用你每次手动开。装完 AI 会运行 agentj doctor,把以 ! 开头的每一行用人话告诉你。常见的一种:Claude Code 只靠环境变量登录,后台服务拿不到这个登录。这时你在终端里运行一次 claude 正常登录,再让 AI 重装一次服务就好。在云服务器上,AI 可能会请你运行一次 loginctl enable-linger $USER(可能要输密码),这样你退出 SSH 后它也照样运行。
第 11 步:✋ 配对手机
配对之前,Agent J 主机上的 Agent J 要在运行(第 10 步)。
- 经账户页批准的配对不需要终端六位码,等手机连上即可。
Agent J 主机离线或账户页添加遥控器已关闭时(agentj pair --check 会告诉你),用本机备选:运行 agentj pair(或 agentj pair --link),在那台Agent J 主机上输入手机六位码和遥控器配对密码(还没设会先请你设一个)。
第 12 步:在手机上试一试
AI 会请你在手机上:
- 发一句「列出这个文件夹里有什么」,看能不能收到回复;
- 让它建一个测试文件再删掉。手机上会弹出卡片,按住「长按批准」大约一秒,按钮填满再松手。删除要你单独点头,所以那张卡片标着 ⚠,按钮照样是「长按批准」。用 Codex 的话,它会告诉你会看到什么;
- 想要锁屏提醒的话,点「开启锁屏提醒」。
然后 AI 会问你要不要给我们发一条「装完了」的反馈,写用了多久、哪里不顺。发之前先给你看原文,你说不发就不发。
第 13 步:交接
最后,AI 运行 agentj handover --lang zh,把这台Agent J 主机上填好真实信息的交接说明原样转给你:Agent 名、账号 ID、配了哪些手机、手机上打开 https://m.agentj.app 、丢了手机怎么办(agentj devices 找到设备号,再 agentj revoke <设备号>)、忘了遥控器配对密码怎么办(它只存在这台Agent J 主机上;有已配对的手机用 agentj passphrase reset --phone,手机确认后在终端输新密码,所有手机保持配对;没有就用 agentj passphrase reset,所有手机都要重新配对)、有新版本怎么升级、「恢复」「定时任务」「命令」在哪、怎么退款、卸载不等于取消订阅。这段话是程序写的,AI 不改、不加命令。
它还会问你:要不要把「先查文档」这条规矩记到它的长期记忆里。你同意的话,它会自己运行 agentj docs-rule --write,程序把这条规矩加到 AI 记忆文件的末尾(只加一次),并给你看加了什么。记下以后,你在新的对话里问它 Agent J 的事,它会先查这些文档,查不到再帮你问我们。手机上的 Agent 本来就知道这条规矩。
装到一半想停下
直接告诉 AI 先停。它会问你要不要把停在第几步报给我们(同样先给你看)。下次再把那句话发给它,从头核对一遍再继续就行。
想全部卸掉,在终端里运行:
agentj service uninstall
uv tool uninstall agentj
这样只会卸掉 Agent J 自己的程序,不会动你的 Claude Code、Codex、OpenCode,也不会动 Agent 的工作文件夹。改用系统定时的 Agent J 定时任务也会一起关掉。卸载不会停止扣费:席位和订阅要在账号后台的「管理账单」里取消,见 账号与付款。
每个已付费且未绑定的席位各可领取一张安装码。两个空余付费席位可领两张码;未使用码作废或过期后可重领,仍受安装服务日额度限制,UTC 零点重置。
从其他设备给席位添加遥控器
第一台遥控器只有两个入口:账号页席位卡「添加遥控器」,或自己在终端运行 agentj pair。本地 127.0.0.1 设置页只给账号页跳转。账号页出二维码后保持打开,扫码后自动显示等待配对的遥控器、六位确认码和「批准」按钮;核对两边一致再批准。之后的遥控器打开 https://m.agentj.app 自助申请,由已配对遥控器扫码、核对并批准。
默认允许账户页添加;目标Agent J 主机的主人可用 agentj remote-pair off 关闭。离线时不排队,开机后重试;旧版本按提示运行 agentj update apply 或从已有手机升级。新设备来源显示「经账户页添加」,其他遥控器收到通知。
账户页配对依赖签名控制平面。配对材料只以浏览器临时公钥加密回传,后端不保存明文;签名服务被攻破仍可能增加设备,关闭开关可拒绝此路径。遥控器配对密码只在那台Agent J 主机上散列保存。在账户页输入它时,浏览器先用那台Agent J 主机临时给出的一次性公钥把它加密,只有那台Agent J 主机能解开、核对;我们的服务器只转发看不懂的密文,也不保存。连续输错 5 次,那台Agent J 主机会锁定一段时间。
macOS 系统版本
先试运行 opencode --version(或所选 Agent 的 --version);能正常运行就能继续安装,不按 macOS 版本号拦截。一键安装也会实际试运行它下载的固定版 OpenCode。如果看到 dyld: Symbol not found: _ubrk_clone 和 /usr/lib/libicucore.A.dylib 后退出,才说明该二进制与系统库不兼容;PATH 或 npm 重装不能修复,请升级系统、换Agent J 主机,或用能正常运行的其他 Agent 按手动路线安装。一键安装优先从本站下载固定版本 uv,托管 Python 使用镜像,包依赖失败时重试镜像;旧预览下载路径已停用。
已安装 Agent J 的Agent J 主机也能使用 AJI 安装码:重新运行账户页的一键安装命令,会保留配置,只升级并绑定席位。也可把码放在权限为 0600 的文件中,运行 agentj login --install-code-file <文件> --name <名字>。AJI 码只能用一次;ajt_ 设置码只用于绑定已安装的Agent J 主机。绑定后到账户页添加遥控器,每次发起和批准都用新的账号通行密钥确认后扫码;主机要求的配对密码是额外验证。
手动安装时,如果提示要填 Installation code (AJI-…),去账号后台点「复制安装码」,只粘贴这串 AJI- 开头的码。
Intel Mac 安装和升级都会限制 cryptography<49。如果旧安装器报 openssl-sys 或找不到 OpenSSL,在 uv tool install 后加 --with "cryptography<49" 再试。
让Agent J 主机保持唤醒:命令、系统设置和可发给 Agent 的请求。
同一台Agent J 主机给第二个人安装
每人各用自己的付费席位、安装码与手机:同一个系统用户里多开实例(agentj --instance 2,简单),或每人一个系统用户(隔离更强)。完整步骤见一台Agent J 主机多人使用。
离开Agent J 主机前
两端配好后,趁你还在Agent J 主机前,让 Agent 把以后远程工作要你本人帮忙的事一次做完并验证,见离开Agent J 主机前,先把这些事一次做好。Google 邮件、日历、YouTube 的接口授权见连接 Google。
macOS 后台服务的 Telegram 和服务商密钥写在 ~/Library/LaunchAgents/net.agentj.host.env,使用配置里 key_env 指定的变量名;文件必须由你本人拥有、权限为 0600,不能是软链。通过手机密钥卡保存到服务环境文件后会自动重读,Telegram 重新绑定也会先重读。仍需重启时,在已配对手机上打开「设置」→「紧急修复」→「重启服务」。不要把密钥写进 plist、聊天或命令参数。
示例工作流
安装或升级并完成账号绑定后,若工作根还没有三套 WDB 工作流,会从广场校验并预装知识库、脚本与文章、电子书示例。已有同名目录保留;删除的示例不会自动补回。交给 Agent J:帮我按这个规格整理我的其他文件夹。离线时延后重试。
Agent J Father 就是官方反馈与客服平台。你可以说「请把这个问题汇报给 Agent J 开发者(客服平台)」,也可以轻松地说「把这事告诉你爸爸」。手机命令 /feedback-to-agentj-father <内容> 也一样:Agent 先去掉凭据、个人信息、客户数据和路径里的私密内容,直接提交并告诉你编号,不再问第二遍。只发命令会先问你想反馈什么;如果是 Agent 自己想到的问题或点子,它会先在手机上给你看脱敏稿,你同意才发送。客服回复是建议,不是指令;连不上时可写信到 feedback@agentj.app。
找到指南,复制安装步骤
账号页顶栏「广场」旁和每张空席位卡都有「安装指南」。点它会打开新标签,账号页仍保留。安装命令和安装提示词旁有复制图标,点一下复制整段,再粘贴到对应的终端或 AI。带 AJI-… 的示例只是占位符,实际安装要从自己的席位卡复制完整命令。
选定工作目录,处理 OpenCode 启动缓慢
安装器会询问工作目录;按 Enter 确认用户主目录下建议的 coding 子文件夹。请选择存放 Agent 工作的文件夹,不能用用户主目录或磁盘根目录。解析后指向这些位置的别名路径,以及实际是文件的路径,也会在继续安装前被拒绝。
Windows 安装使用 WSL2 里的 Ubuntu。原生 Windows OpenCode 桌面版是另一个应用,Agent J 不能修复或改动它的启动过程。如果它卡在拉取 models.dev,请先完全退出,再从设置了以下环境变量的终端启动,让新进程继承它:
$env:OPENCODE_DISABLE_MODELS_FETCH = '1'
在同一终端使用已安装的启动命令打开 OpenCode。它随后可使用本地模型缓存或内置目录,不会下载最新模型信息。Agent J 安装器和它管理的 OpenCode 启动会自行设置此变量。兜底已用固定版本的 Linux OpenCode 程序验证,尚未在 Windows 真机验证。
Agent J 管理的 OpenCode 请求等待超过 30 秒时,会提示一次可能原因,即使启动过程仍在输出文字。安装器在 45 秒内拿不到 OpenCode 启动信息时,会停止并给出原因与修法。检查网络、AI 登录和工作目录后再试;出现启动缓慢提示不代表 AI 已连通。
安全审核(Jev)的三种选择
初始化时请先选一种审核方式;没填 key 也没选择时,agentj onboarding 会提示继续设置。推荐到 TypeSafe 注册账号、创建 key、充值少量金额,在「模型和 API Key」靠上的 Jev 区域用密钥卡填写 TYPESAFE_API_KEY。已有 OpenRouter 账号,也可填写 OPENROUTER_API_KEY。已有 key 会自动沿用(同时存在时沿用 OpenRouter),也能在 设置 → 安全 选择来源。
Jev 会给客服、好友消息增加模型审核,也会复查脱敏内容、辅助审批判断;必要的脱敏文本直达所选服务商,费用由你的账号承担。TypeSafe 走官方接口,OpenRouter 走其中的 Jev 模型,两者受各自的数据政策约束。模型可能误判,也会增加延迟。选择的服务不可用时保留该通道的失败处理,不会自动变成关闭。
你也可在 设置 → 安全 关闭总开关,明确确认「跳过,我知道安全性会弱一点」。主机会记录 jev.mode=off、签名设备与确认时间。关闭后所有 Jev 模型审核都跳过,客服和好友流程可继续;本地正则、凭据过滤、权限审批和工具授权仍保留。关闭可减少延迟与误拦,同时失去这层防护。即使有 key 也能关闭。Agent 不能代签或通过改配置自行关闭;只有主人在已配对手机上的签名选择才生效,签名设备被解绑后这份关闭授权失效。
macOS「登录项与扩展」中的 Agent J 使用带名字、图标和开发者签名的 App。主机保持手机连接;救援守护在主机卡住时提供救援,建议都保持开启。每周任务按各自时间运行,可停用不需要的任务。升级会重写主机与救援登录项,并迁移旧的每周通知任务;若提示签名 App 下载失败,联网后运行 agentj service install 重试。
第一台遥控器只有两个入口:账号页席位卡「添加遥控器」,或自己在终端运行 agentj pair。本地 127.0.0.1 设置页只给账号页跳转。账号页出二维码后保持打开,扫码后自动显示等待配对的遥控器、六位确认码和「批准」按钮;核对两边一致再批准。之后的遥控器打开 https://m.agentj.app 自助申请,由已配对遥控器扫码、核对并批准。
首台遥控器,按你的情况选:
- 有账号:打开
agentj pair --check --json返回的account_url,在这台主机的席位卡点「添加遥控器」,扫码后核对六位码并批准。 - 只有席位:请你本人在主机终端敲下面这一行:
agentj pair。你亲自设置并输入遥控器配对密码(至少 8 位),再输入遥控器显示的六位码;AI 不得代设、读取或代输密码。 - 账号是别人开的:请公司的账号负责人在账号页批准。没有账号、又不愿操作终端时,请负责人协助。
agentj pair 默认同时显示二维码与链接;--link 保留兼容。方法一:手机扫码。方法二:把同一个链接粘到电脑浏览器地址栏直接打开。链接 5 分钟、一次有效,是配对密钥,不要发给别人或 AI;iPhone 请粘到主屏幕图标内的配对链接框。
首台配好后:手机先配 → 建议在常用电脑浏览器打开 https://m.agentj.app,用已配对手机扫电脑显示的码,核对后在手机确认;电脑先配 → 建议在电脑浏览器的「设置 → 遥控器管理 → 添加遥控器(配对新遥控器)」打开二维码,用手机遥控器扫码,核对后在电脑浏览器上确认。两台都配好并验收首条消息再结束安装。
从旧版本升级
升级后,主 Agent 播报和手机更新说明只显示适用于你当前 AI 编程工具的内容;所有工具通用的变化仍会显示。
普通主机先运行 agentj update apply,再核对 agentj --version 和 agentj doctor。只有命令不存在或旧更新器失败(例如提示连不上 GitHub)时,在同一系统用户下再运行一次 curl -fsSL https://agentj.app/install.sh | bash(不用带码):它按同一套哈希和发行签名从 agentj.app 修复升级;以前用 sudo 留下了不归你账号的文件夹时,它会给出一条 sudo chown 命令,问过你再运行。配置与绑定保留,不要 unlink、删除状态或另建席位。Olares Market 应用仍从 Market 升级。
自动升级没成功怎么办
下载、校验或安装准备失败时,Agent J 会提示仍是原版本。先让你的 Agent 运行 agentj doctor 看原因,不要删除配置、解绑账号或重新建席位。
如果升级后已经回滚,旧版程序能运行就会记为回滚成功;后台服务或自检仍有问题时会单独列出,继续处理这些问题即可。旧更新器只有成功安装新版后才能得到这些改进。旧版 uv 安装仍无法升级时,在 Agent J 主机的终端里按 旧更新器自救步骤 运行当前安装器的修复升级命令;不需要新安装码,保留配置和绑定。Olares Market 应用通过 Market 升级。
旧主机反复提示「依赖下载失败」,怎样升级?
如果 Agent J 是用 uv 安装的,而且这台主机可以访问 agentj.app 和 PyPI 文件服务器 files.pythonhosted.org,请用原安装账号打开主机终端,运行下面的命令。使用公司专用软件源的主机,请先确认公司允许从 PyPI 下载文件。
curl --proto '=https' --tlsv1.2 -fsSL https://agentj.app/install-assistant.sh | sh -s -- --upgrade-only --repair-index
修复程序会核对 Agent J 的发行签名,按发行清单下载并校验适合这台主机的依赖文件,然后安装并重启。席位、配对和设置都会保留。完成后运行 agentj --version 和 agentj doctor 核对结果。若仍失败,请把显示的错误代码和版本号交给客服。通过 Olares 应用市场安装的主机请在市场内更新。
首次启动 AI 失败
把报错里的 AJ_START_* 原因码留给你的 Agent,让它运行 agentj doctor --offline。如果是后台环境问题,先在手机设置里检查模型代理;安装 AI 命令行工具后,运行 agentj service install 更新服务配置,再检查一次。
已有火山方舟、阿里百炼或 Kimi 账号,可以继续用原来的服务商。服务商设置会直接打开手机密钥卡;已有密钥会复用,不需要重复提交。等卡片确认完成后再切换模型,密钥不要发进聊天。
从桌面 App 安装后找不到 Agent
从 ChatGPT 等桌面 App 里安装也可以。后台服务会使用登录终端里的稳定程序路径,并补上常见的用户安装目录,不会记住 App 里的临时路径。如果终端能运行 Claude Code,Agent J 却说没装,先运行 agentj doctor;它提示服务路径缺少程序时,运行一次 agentj service install 修复,再检查一次。这个操作会重启 Agent J,手机会短暂断开后自动重连;不需要重新安装 Claude Code,也不要把登录文件或密钥发到聊天里。
OpenCode 版本兼容
Agent J 会自动选择 OpenCode 1.x 或 2.x 对应的连接方式,已在隔离环境测试 1.19.4 和 2.1.4。已有 1.x 可以继续用,Homebrew 装的 2.x 不必降级。升级 OpenCode 不要求清空对话;只有你想另开对话时才清空。
启动或切换失败时,在主机运行 agentj doctor。Agent J 会先检查本地服务能否启动,再完成切换。另一个只处理私聊、不开放工具的执行器需要旧版命令行的 --dir 参数;OpenCode 2.1.4 没有这个参数,会在启动私聊进程前拒绝。这个通道可改用受支持的 Claude Code 或 Codex 执行器。
只读应急诊断先试当前免费列表里的 DeepSeek Flash,再试 opencode/glm-5.3-flash-free(当天官方模型页须明确承诺不留存、不训练),最后才用你明确安装的本地 Ollama 模型。LongCat 和 Space Bunny 不进入兜底顺序。每次重新核实可用性,不自动选付费模型,也不重发原任务。云端诊断只收到固定错误信号。
OpenCode 2.1 已移除旧的详细模型列表命令。Agent J 会自动读取原生价格目录来识别免费模型,不要求你运行那个旧命令。安装器先使用Agent J 主机核实的模型列表,再试模型能否回复。
All four ways install the same Agent J, and afterwards you talk to it from your phone. Not sure? Choose ①.
Windows
For Windows 10 and Windows 11 (64-bit). Agent J runs in Ubuntu inside Microsoft's Linux subsystem (WSL2); the install command sets that up first, so there is nothing to prepare.
① Install it yourself: one command
When to choose it: the Agent J host has no AI tool yet, or you would rather do it yourself. You need one code from start to finish: the installation code (it starts with AJI-) on an empty seat card in your account.
Time: usually 15 to 30 minutes, mostly downloading; the first WSL install may need one restart. The parts that need you add up to a few minutes.
- On https://agentj.app/account/ press "Get installation command" on the empty seat card, then "Copy installation command". Opened on Windows, the page gives you the PowerShell line; if not, press "Windows (PowerShell) command".
- Open PowerShell (search Start for PowerShell; no administrator needed), paste and press Enter. The command looks like
$env:AGENTJ_CODE='AJI-…'; irm https://agentj.app/install.ps1 | iex - Follow the screen. Every step starts with its number and what it is doing:
| On screen | What you do |
|---|---|
| Installation code | Taken from the command; if it is missing you paste it once (hidden) |
| WSL2 and Ubuntu | Allow the Windows administrator prompt; restart if asked, then paste the same command again |
| Ubuntu user | Pick a user name (Enter takes the suggestion) and a password (hidden; remember it) |
| System parts | Nothing; Windows does not ask for a password |
| AI | Reuses Claude Code or Codex if you are signed in. Otherwise pick a route: if the official services are unreachable choose the Agents Relay route (see Hong Kong and mainland China); if they work, sign in with your own account in the browser |
| Agent J | Nothing: it installs, starts the background service and links this seat with the same code |
| Phone | A QR code appears: open https://m.agentj.app on your own phone, tap "Scan QR code" and scan it |
| Connect the AI | Nothing: the AI must answer one real request before it is connected |
| Keep it awake | Shows the Windows power steps to do in PowerShell yourself; nothing changes inside Ubuntu (details) |
One more option: the AI step's menu also has item 6, 「用 OpenCode 自带的免费模型先跑起来」 (start now with OpenCode's own free model): no sign-in, no key, ready at once; your conversations and code go to OpenCode and its model provider. It prefers free models whose provider does not train on your conversations; free models are rate-limited and can disappear, so switch to a model of your own for sensitive work later (Models & Key on the phone). The other choices and the recommended default are unchanged.
- When you see "✅ 全部完成" (all done), say hello to it from your phone. To use
agentjon the Agent J host later, open "Ubuntu" from the Start menu, not PowerShell.
If something goes wrong:
- If a step fails, the screen says what to do. Fix it and paste the same command again; finished steps are skipped.
- The installation code works once and expires after 24 hours (the card shows the time).
- Already installed, but the AI is missing or an old version will not upgrade? In "Ubuntu" run
curl -fsSL https://agentj.app/install.sh | bashagain (no code). It checks the version first: an older Agent J is repaired forward with the signed package from agentj.app (not the oldagentj update, no GitHub; seat, pairing and settings stay), then only the AI step runs. - Confirm systemd is on: the background service runs on it. In "Ubuntu" run
ps -p 1 -o comm=; it should printsystemd. If not, in "Ubuntu" runprintf '[boot]\nsystemd=true\n' | sudo tee -a /etc/wsl.conf(skip it when the file already hassystemd=trueunder[boot]), then in PowerShell runwsl --shutdown, reopen "Ubuntu" and runagentj service install. The install command does both steps itself;agentj service installand upgrades also name these two steps in one sentence when systemd is off.
② Let the AI on the Agent J host install it
When to choose it: you already use Claude Code, Codex or OpenCode inside Ubuntu on WSL and want it to do the work and explain as it goes. On Windows Agent J installs only inside WSL2, and an AI running on Windows itself stops and tells you so; without WSL yet, ① is simpler.
- Already bought a seat: press "Copy installation prompt" on the empty seat card in your account and send it to the AI in Ubuntu.
- Not yet: send it this sentence exactly as written, and it walks you through opening an account and buying a seat:
Please download https://agentj.app/install.md with curl, read the whole file with your file-reading tool, then follow it step by step, re-reading each section before you do it. Tell me when you need me to do something.
What the AI does at each step, and where it stops for you: When the AI installs it.
③ Remote installation assistant (cloud)
When to choose it: nobody is around to help, there is no AI on the Agent J host, and you are stuck halfway and want to ask someone.
How it works today:
- Install with the command from ①. That command is the installation assistant: the screen says what each step is doing, and when something fails it says what to do. Fix it and paste the same command again to carry on.
- Still stuck, and Agent J is already installed: run this command in "Ubuntu". It sends your question and a health check with the secrets removed to our support desk, which usually answers with concrete steps within a few minutes.
agentj support ask "<your question>" --attach-doctor
- Not installed yet, or you cannot reach us: email feedback@agentj.app with the step, the exact error and a screenshot (cover the installation code, keys and QR code first).
Tip: In a later planned release the cloud assistant suggests the next step right on your phone, and nothing runs until you tap it.
④ Get someone to help: beside you or remotely
When to choose it: you are not at home with computers or terminals, and a family member, friend or colleague can sit with you or help over a video call or screen sharing.
What to do today:
- The helper walks you through ①. The code is copied only from your own account page and pasted only on your own computer; when helping remotely, you share your screen and the helper tells you what to do. Never put the code or a key into a chat.
- A Windows administrator prompt appears along the way, and there may be one restart. A helper who warns you in advance saves you a fright.
- Scan the pairing QR code with your own phone. If the helper's phone scans it, that phone becomes a remote for the Agent J host: afterwards run
agentj devicesto find its device ID, thenagentj revoke <device-id>to remove it. - Phone not at hand, or the scan did not work? No need to reinstall: once it is installed, press "Add a remote" on the Agent J host's seat card in your account, confirm with your passkey, and scan with your phone.
Tip: One-step helper pairing arrives in a later planned release: the helper connects their own phone for a while and guides you through the install from it; once your phone is paired and the AI is connected, the helper is disconnected automatically.
macOS
For Macs with Apple silicon and Intel processors.
① Install it yourself: one command
When to choose it: the Agent J host has no AI tool yet, or you would rather do it yourself. You need one code from start to finish: the installation code (it starts with AJI-) on an empty seat card in your account.
Time: usually under 10 minutes. the Agent J host's own work takes a few minutes (about 2 on our test machine); the rest is you signing in to an AI and scanning a code.
- On https://agentj.app/account/ press "Get installation command" on the empty seat card, then "Copy installation command". Opened on a Mac, the page gives you the Terminal line; if not, press "macOS / Linux command".
- Open Terminal (press Command + Space and search for Terminal), paste and press Enter. The command looks like
curl -fsSL https://agentj.app/install.sh | bash -s -- AJI-… - Follow the screen. Every step starts with its number and what it is doing:
| On screen | What you do |
|---|---|
| Installation code | Taken from the command; if it is missing you paste it once (hidden) |
| System parts | You may be asked for the Agent J host password once (hidden) |
| AI | Reuses Claude Code or Codex if you are signed in. Otherwise pick a route: if the official services are unreachable choose the Agents Relay route (see Hong Kong and mainland China); if they work, sign in with your own account in the browser |
| Agent J | Nothing: it installs, starts the background service and links this seat with the same code |
| Phone | A QR code appears: open https://m.agentj.app on your own phone, tap "Scan QR code" and scan it |
| Connect the AI | Nothing: the AI must answer one real request before it is connected |
| Keep it awake | Asked once your phone is paired. Press Enter for yes (recommended): no sleep while plugged in. A second question covers the closed lid; with that yes a closed Mac neither sleeps nor shuts down, so shut it down yourself before travel. Each change is a password card on your phone (details) |
One more option: the AI step's menu also has item 6, 「用 OpenCode 自带的免费模型先跑起来」 (start now with OpenCode's own free model): no sign-in, no key, ready at once; your conversations and code go to OpenCode and its model provider. It prefers free models whose provider does not train on your conversations; free models are rate-limited and can disappear, so switch to a model of your own for sensitive work later (Models & Key on the phone). The other choices and the recommended default are unchanged.
- When you see "✅ 全部完成" (all done), say hello to it from your phone. Afterwards
agentj statusworks in the same Terminal window.
If something goes wrong:
- If a step fails, the screen says what to do. Fix it and paste the same command again; finished steps are skipped.
- The installation code works once and expires after 24 hours (the card shows the time).
- Already installed, but the AI is missing or an old version will not upgrade? Run
curl -fsSL https://agentj.app/install.sh | bashagain (no code). It checks the version first: an older Agent J is repaired forward with the signed package from agentj.app (not the oldagentj update, no GitHub; seat, pairing and settings stay), then only the AI step runs.
② Let the AI on the Agent J host install it
When to choose it: you already use Claude Code, Codex or OpenCode and want it to do the work and explain as it goes.
- Already bought a seat: press "Copy installation prompt" on the empty seat card in your account and send it to the AI on the Agent J host.
- Not yet: send it this sentence exactly as written, and it walks you through opening an account and buying a seat:
Please download https://agentj.app/install.md with curl, read the whole file with your file-reading tool, then follow it step by step, re-reading each section before you do it. Tell me when you need me to do something.
What the AI does at each step, and where it stops for you: When the AI installs it.
③ Remote installation assistant (cloud)
When to choose it: nobody is around to help, there is no AI on the Agent J host, and you are stuck halfway and want to ask someone.
How it works today:
- Install with the command from ①. That command is the installation assistant: the screen says what each step is doing, and when something fails it says what to do. Fix it and paste the same command again to carry on.
- Still stuck, and Agent J is already installed: run this command in Terminal. It sends your question and a health check with the secrets removed to our support desk, which usually answers with concrete steps within a few minutes.
agentj support ask "<your question>" --attach-doctor
- Not installed yet, or you cannot reach us: email feedback@agentj.app with the step, the exact error and a screenshot (cover the installation code, keys and QR code first).
Tip: In a later planned release the cloud assistant suggests the next step right on your phone, and nothing runs until you tap it.
④ Get someone to help: beside you or remotely
When to choose it: you are not at home with computers or terminals, and a family member, friend or colleague can sit with you or help over a video call or screen sharing.
What to do today:
- The helper walks you through ①. The code is copied only from your own account page and pasted only on your own computer; when helping remotely, you share your screen and the helper tells you what to do. Never put the code or a key into a chat.
- When the Agent J host asks for its password, you type it yourself; don't tell your helper.
- Scan the pairing QR code with your own phone. If the helper's phone scans it, that phone becomes a remote for the Agent J host: afterwards run
agentj devicesto find its device ID, thenagentj revoke <device-id>to remove it. - Phone not at hand, or the scan did not work? No need to reinstall: once it is installed, press "Add a remote" on the Agent J host's seat card in your account, confirm with your passkey, and scan with your phone.
Tip: One-step helper pairing arrives in a later planned release: the helper connects their own phone for a while and guides you through the install from it; once your phone is paired and the AI is connected, the helper is disconnected automatically.
Linux
For Ubuntu, Debian and other common distributions, on desktops, laptops and cloud servers. A cloud server you reach only over SSH (no desktop) also needs the cloud-server section of the install guide.
A VM with systemd is the full cloud-server setup. For a generic container, the fence and background service may fail: after installing the package, before init/login or binding a seat, run agentj doctor --isolation-only --json. It tests the real fence using temporary files without customer identity or network access. If the exit status is nonzero, stop and inspect the failed JSON checks entry (reason when present); a pass does not prove the platform permits a persistent background process. With no systemd user session, agentj serve under tmux/nohup is only a manual fallback: restart it after an update, reboot or crash; rescue, emergency repair and systemd user timers are not guaranteed. See the full install guide.
① Install it yourself: one command
When to choose it: the Agent J host has no AI tool yet, or you would rather do it yourself. You need one code from start to finish: the installation code (it starts with AJI-) on an empty seat card in your account.
Time: usually under 10 minutes. the Agent J host's own work takes a few minutes (about 2 on our test machine); the rest is you signing in to an AI and scanning a code.
- On https://agentj.app/account/ press "Get installation command" on the empty seat card, then "Copy installation command". Opened on Linux, the page gives you the terminal line; if not, press "macOS / Linux command".
- Open a terminal, paste and press Enter. The command looks like
curl -fsSL https://agentj.app/install.sh | bash -s -- AJI-… - Follow the screen. Every step starts with its number and what it is doing:
| On screen | What you do |
|---|---|
| Installation code | Taken from the command; if it is missing you paste it once (hidden) |
| System parts | Installs bubblewrap for Agent J isolation; socat is needed only for Claude Code's own sandbox; you may be asked for the Agent J host password once (hidden) |
| AI | Reuses Claude Code or Codex if you are signed in. Otherwise pick a route: if the official services are unreachable choose the Agents Relay route (see Hong Kong and mainland China); if they work, sign in with your own account in the browser |
| Agent J | Nothing: it installs, starts the background service and links this seat with the same code |
| Phone | A QR code appears: open https://m.agentj.app on your own phone, tap "Scan QR code" and scan it |
| Connect the AI | Nothing: the AI must answer one real request before it is connected |
| Keep it awake | Asked once your phone is paired. Press Enter for yes (recommended): no sleep while plugged in, also with the lid closed, and Agent J starts at boot without a login. Each change is a password card on your phone (details) |
One more option: the AI step's menu also has item 6, 「用 OpenCode 自带的免费模型先跑起来」 (start now with OpenCode's own free model): no sign-in, no key, ready at once; your conversations and code go to OpenCode and its model provider. It prefers free models whose provider does not train on your conversations; free models are rate-limited and can disappear, so switch to a model of your own for sensitive work later (Models & Key on the phone). The other choices and the recommended default are unchanged.
- When you see "✅ 全部完成" (all done), say hello to it from your phone. Afterwards
agentj statusworks in the same terminal window.
If something goes wrong:
- If a step fails, the screen says what to do. Fix it and paste the same command again; finished steps are skipped.
- The installation code works once and expires after 24 hours (the card shows the time).
- Already installed, but the AI is missing or an old version will not upgrade? Run
curl -fsSL https://agentj.app/install.sh | bashagain (no code). It checks the version first: an older Agent J is repaired forward with the signed package from agentj.app (not the oldagentj update, no GitHub; seat, pairing and settings stay), then only the AI step runs.
② Let the AI on the Agent J host install it
When to choose it: you already use Claude Code, Codex or OpenCode and want it to do the work and explain as it goes.
- Already bought a seat: press "Copy installation prompt" on the empty seat card in your account and send it to the AI on the Agent J host.
- Not yet: send it this sentence exactly as written, and it walks you through opening an account and buying a seat:
Please download https://agentj.app/install.md with curl, read the whole file with your file-reading tool, then follow it step by step, re-reading each section before you do it. Tell me when you need me to do something.
What the AI does at each step, and where it stops for you: When the AI installs it.
③ Remote installation assistant (cloud)
When to choose it: nobody is around to help, there is no AI on the Agent J host, and you are stuck halfway and want to ask someone.
How it works today:
- Install with the command from ①. That command is the installation assistant: the screen says what each step is doing, and when something fails it says what to do. Fix it and paste the same command again to carry on.
- Still stuck, and Agent J is already installed: run this command in a terminal. It sends your question and a health check with the secrets removed to our support desk, which usually answers with concrete steps within a few minutes.
agentj support ask "<your question>" --attach-doctor
- Not installed yet, or you cannot reach us: email feedback@agentj.app with the step, the exact error and a screenshot (cover the installation code, keys and QR code first).
Tip: In a later planned release the cloud assistant suggests the next step right on your phone, and nothing runs until you tap it.
④ Get someone to help: beside you or remotely
When to choose it: you are not at home with computers or terminals, and a family member, friend or colleague can sit with you or help over a video call or screen sharing.
What to do today:
- The helper walks you through ①. The code is copied only from your own account page and pasted only on your own computer; when helping remotely, you share your screen and the helper tells you what to do. Never put the code or a key into a chat.
- When the Agent J host asks for its password, you type it yourself; don't tell your helper.
- Scan the pairing QR code with your own phone. If the helper's phone scans it, that phone becomes a remote for the Agent J host: afterwards run
agentj devicesto find its device ID, thenagentj revoke <device-id>to remove it. - Phone not at hand, or the scan did not work? No need to reinstall: once it is installed, press "Add a remote" on the Agent J host's seat card in your account, confirm with your passkey, and scan with your phone.
Tip: One-step helper pairing arrives in a later planned release: the helper connects their own phone for a while and guides you through the install from it; once your phone is paired and the AI is connected, the helper is disconnected automatically.
Olares box
Agent J runs on an Olares box (Olares 1.12 or newer) too, and your data stays on the box.
- Install Agent J from Olares Market, open the app and paste the entire installation prompt from an empty seat on the account page into its setup page. The app includes OpenCode and connects to Olares Router by default, without a Router API key.
- Open the terminal inside the Olares app: choose Open web terminal on the Agent J app’s setup page, or Open Olares web terminal under Settings → Safety on a paired remote. Olares verifies sign-in in the new tab. The shell uses the same user, home and configuration inside the Agent J app. Use
agentj statusfor status andagentj tasks list --jsonfor your background tasks; do not print passwords, keys, tokens or complete process command lines. This does not require enabling Agent J’s line-mode terminal or an extra Agent J Face ID check, and does not provide line mode’s output masking, operation log or command confirmation. See Olares web terminal. - Upgrade Agent J in Market → Manage → Updates. The phone's
/updateandagentj update applydirect you to Market; do not reinstall Agent J or install systemd inside the app. - For a separate installation directly on the box's Ubuntu: use a normal user (not root), following the cloud-server installation and upgrade steps. Do not install inside another app's container. The AI asks you to run
sudo loginctl enable-linger <user>once (you type your password), log in again, and then installs the service. - Connect a model for the Ubuntu installation: create an API key in Olares Router and connect it through DeepSeek's dsh or OpenCode; paste the key only into the card on your phone. See DeepSeek dsh.
- Remote maintenance: use the official LarePass VPN. You import your own mnemonic in LarePass yourself; never give it to an AI. Your phone reaches Agent J without the VPN.
- Box came with Agent J pre-installed? Only the software is pre-installed. After activation you sign in to your own Agent J account and create your own seat.
Hong Kong and mainland China: which AI
Note: In Hong Kong and mainland China the official Claude Code and Codex services are usually unreachable. When the one-command install reaches the AI step it tests the network first and, if they are unreachable, recommends the Agents Relay route: sign up at https://agentsrelay.net/onboard/, get a key, then paste it into the terminal (hidden). Paste the key only into the terminal, never into a chat, and don't tell it to your helper.
In mainland China you can also use OpenCode with a Chinese model: see Install the AI command-line tools.
On Volcano Ark, Kimi, Alibaba Bailian or DeepSeek, or not sure which to buy: see Choose by your model.
Cover the codes before a screenshot
Note: Before you send anyone a screenshot, your helper and our support desk included, cover the installation code (starting with AJI-), keys and QR codes on the screen. In someone else's hands they could be used to take your seat or to ask to connect to the Agent J host.
When the AI installs it
Why download it and read it whole: some AIs read web pages through a tool that only returns a summary, and a summary drops the safety rules and the points where the AI must stop and ask you. Before it starts, your AI may first tell you about the risks and ask whether to go on — that's normal.
If someone has already paid for a seat for you, they give you a longer sentence with a setup code starting with ajt_. Send that one instead.
From there the AI does the work. Whenever something needs you in person, it stops, tells you in plain words what to do, and waits until you say it's done.
install.md is the install guide written for your AI, which is why it is in English and fairly technical. This page is the same process for people, and the step numbers match.
What only you can do
The AI will not do these for you, and it will never ask you to paste a password, a code or your passphrase into the chat. At each of these points it stops and asks you:
- typing the Agent J host password (
sudo, for example to install bubblewrap); - signing in to Claude Code or Codex, or storing your model key in your own terminal (with OpenCode);
- signing in to the account dashboard: your email, the 6-digit code you receive, creating a passkey, opening the account;
- paying on Stripe's page and entering a promo code;
- tapping "Copy installation prompt" in the account dashboard and giving that sentence to the AI on the Agent J host;
- naming your Agent;
- setting a remote pairing password (asked once at the end of the installation; optional, recommended; required to pair at the terminal);
- choosing the AI coding tool when more than one is available, and the folder the Agent works in;
- confirming Add a remote on the account page with your passkey, then scanning the QR code or pasting the pairing link on your phone;
- sending the first message from the phone and tapping "Approve" for the first time;
- saying yes or no when the AI wants to run
uv tool update-shell(it adds a line to your shell's startup files); - saying yes or no to a feedback report; and, if you want the AI to remember the "look it up first" rule, running one command yourself (Step 13).
Whenever it wants to report a problem to us, it first shows you the exact text and sends it only after you say yes. See Plaza and feedback.
Step by step
The numbers are the same as in install.md. Steps marked ✋ are yours from start to finish; the others may still need you once or twice.
Step 1: Verify the install guide
The AI downloads the install guide and checks two things: the fingerprint published on our site matches, and the copy on our site is identical to the public copy on GitHub. If they disagree it stops and tells you instead of going on.
Step 2: Set up feedback
The AI opens a feedback channel first, so it can tell us if a later step goes wrong. Opening it sends no content; we only see the Agent J host's IP address and the time. You see every report before it is sent.
Step 3: Check the prerequisites
The AI checks your system, curl, git, uv and, on Linux, bubblewrap (a Mac has what it needs built in). It also looks at which AI coding tools are installed and signed in. Whether you use an iPhone or an Android phone it asks only at Step 11, where the answer matters.
On Ubuntu 24.04 the check also reads the AppArmor user-namespace restriction and starts a real isolation probe. A restriction value of 1 is compatible with a working bubblewrap profile. You may need to approve installing bubblewrap; if the probe is still blocked, the diagnostic gives the exact /etc/apparmor.d/bwrap-agentj profile for /usr/bin/bwrap only. It does not replace an existing profile or disable the system-wide restriction. The installation assistant checks before starting the background service, pauses on failure and keeps its resume record. Fix the policy and rerun the original command. The cloud-server section of the installation guide has the commands.
It may need you here:
- to type the Agent J host password when it installs bubblewrap or another system package;
- to sign in to Claude Code or Codex in your own terminal if you haven't yet;
- in mainland China, or when none of the tools is usable, it installs OpenCode for you. You sign up with a model vendor yourself, top up and create a key there, then run
opencode auth loginin your own terminal to store the key. The AI never asks for your key and never touches it.
Step 4: Install the agentj program
The AI installs agentj, the program on the Agent J host, at one fixed version:
uv tool install "git+https://github.com/preangelleo/agentj@v0.30.69#subdirectory=host"
agentj doctor
agentj doctor lists, one line each, what is ready and what isn't. If GitHub is slow or blocked (mainland China, for example), the AI downloads the same program from our site instead and checks its fingerprint before installing it.
Your own terminal has to find agentj too, because you run it yourself in Steps 8 and 11. If a new terminal can't find it, the AI first asks whether it may run uv tool update-shell, which adds one line to your shell's startup files; only with your yes, and then you open a new terminal window. If you'd rather not, type export PATH="$HOME/.local/bin:$PATH" in the terminal you use, or try a new terminal.
Step 5: Create the Agent J host's identity
agentj init
This gives the Agent J host its own keys. They stay on the Agent J host, and nothing — the AI included — should touch them.
Step 6: ✋ Open an Agent J account and buy a seat
If the sentence you sent contains a setup code (a seat someone paid for), skip this step: it's paid already, so you don't sign up or pay anything.
Otherwise the AI asks you to:
- Open the account dashboard at https://agentj.app/account in a browser — on the Agent J host or on your phone. Enter your email, tap "Send code", type the 6-digit code from the email into the page and tap "Sign in". The code works for 10 minutes; it comes from noreply@mail.agentj.app — check your spam folder if it doesn't arrive. The code goes into the page only, never into the chat with the AI.
- Tap "Create a passkey on this device" when the page asks, and confirm with your fingerprint, face or screen lock — within 10 minutes of the email code. A browser on a Linux computer usually has no passkey of its own: in the window that pops up, choose to use your phone (it scans a QR code on the screen), or use a USB security key. Easier still: do this step on your phone.
- Leave "Team name (optional)" empty if you like and tap "Open my account".
- Buy one seat under "Billing": pick "Monthly" or "Yearly", put 1 in "Seats to buy", type your promo or invite code into "Promo or invite code (optional)" if you have one, tap "Buy seats" and pay on Stripe's page. Prices and the promo code rules: Account and billing.
- Back in the account dashboard, on the "Empty seat" card tap "Copy installation prompt", and send that sentence to the AI on the Agent J host. It carries on from there.
Stripe's payment page shows the price in US dollars, and the merchant is AgentJ.app. Change your mind within 7 days of your first payment and we refund it in full. Back in the account dashboard after paying and the page asks you to sign in? The payment went through: sign in again with your passkey or an email code, and don't pay a second time.
Step 7: ✋ Add the Agent J host to the Agent J account
First the AI asks what the Agent should be called — "Wren", "Shop assistant", whatever you like. Length: at most 13, where each Chinese character counts 1.6 and each letter, digit, space or symbol counts 1 — up to 8 Chinese characters or 13 letters. Then it uses the setup code in the sentence to add the Agent J host to that seat of your account, and tells you which account it joined. Please check the account ID; if it's wrong, the AI leaves that account right away. Afterwards it deletes the temporary file that held the setup code.
If setup instructions fail, copy the installation prompt from the same empty seat again. It issues a new seven-day single-use code and invalidates the previous unused code. The old eight-character login entry has retired; do not buy another seat to retry.
Step 8: ✋ Human: approve with an account passkey
After the Agent J host is bound, open its seat card on the account page and select Add a remote. Confirm each start and approval with a fresh account passkey and scan. A host pairing password, when required, is an additional check. The same account page can add a phone to another bound, online computer.
At the end of the installation you're asked whether to set a remote pairing password (optional, recommended): press Enter to skip, and set it any time later with agentj passphrase set. The Agent must never choose or enter it. Pairing at the terminal (agentj pair, agentj pair --link) requires it; without one, agentj pair asks you to set it first. agentj pair --check says which route works before any QR code.
Step 9: Connect the AI coding tool
The AI first finds out what it can by itself, then asks you once, in one short message, only what you have to decide. Each line carries its recommendation: reply "OK" to take them all.
- Which AI coding tool.
agentj agent detect --jsonshows which ones are usable. Exactly one → it uses that and doesn't ask. More than one → it lists them and you choose; this is the one question without a recommendation, because it never picks for you. - Which folder the Agent works in. It looks for a folder you already use for your projects (such as
~/coding) and recommends it; with none, it recommends creating~/coding. For a first try a new, empty folder such as~/agentj-workis fine too. Then:
agentj agent claude --dir ~/agentj-work
For Codex replace claude with codex. OpenCode also needs the model:
agentj agent opencode --dir ~/agentj-work --model zhipuai/glm-5.3
The Agent runs in a fenced-off space: it keeps your own sign-in and settings, but it cannot reach the keys and settings of agentj itself. The AI also looks for local services on the Agent J host that already trust you (a browser's debugging port, for example) and tells you in one sentence what the fence can't stop.
It doesn't ask whether your browsers are signed in to email, shops or your bank. Here is why that matters and why it needn't ask: the phone's Agent works as you, so if a browser on the Agent J host has a debugging port open, the Agent can drive it and use every site signed in there. But paying, placing an order or moving money on any website always stops and asks you on the phone first, whatever you are signed in to — so the answer would change nothing. If such a port is open, the AI names it.
It installs the workflow design wizard too; once your phone is paired, say "帮我设计工作流" (help me design my workflows) on the phone to start it.
Two things in this step the AI always does, never skips: it asks you which folder the Agent works in, and it tells you, in a message of its own, what the fence can't stop. It goes on once you've read it.
Step 10: Keep it running
agentj service install
As a service it starts by itself whenever the Agent J host starts and you log in, so you never have to launch it by hand. Then the AI runs agentj doctor and tells you, in plain words, every line that starts with !. A common one: Claude Code logged in only through an environment variable, which the background service doesn't get. Run claude once in a terminal and log in there, then have the AI reinstall the service. On a cloud server the AI may ask you to run loginctl enable-linger $USER once (it may ask for your password), so it keeps running after you leave SSH.
Step 11: ✋ Pair the phone
Agent J has to be running on the Agent J host first (Step 10).
- On the phone, open https://m.agentj.app, add it to your Home Screen and open it from that icon. The top of the page says "Not paired yet".
- In the account dashboard, find the Agent J host’s seat card and choose Add a remote. Use a fresh passkey confirmation for each pairing start and approval. The account page can be open on another computer.
- On the phone, tap Scan QR code and scan the code shown on the account page. If needed, use Copy pairing link and paste it into the Home Screen app under Or paste the pairing link. Do not paste it into an AI chat.
- The account page automatically shows the waiting remote and six-digit confirmation code. Compare it with the phone, then choose Approve. The phone connects after approval.
When the Agent J host is offline or account-page pairing is off (agentj pair --check tells you), the local alternative is agentj pair (or agentj pair --link): type the phone's six-digit code and the remote pairing password on that computer (it asks you to set one first if there is none).
The link is the pairing key: it works once, for 5 minutes. Never send it through WeChat, a group chat or email, and never to any AI.
Step 12: Try it on the phone, then offer the completion feedback
The AI asks you to:
- send "list the files in this folder" from the phone and check that a reply comes back;
- ask it to create a test file and delete it. A card pops up on the phone: press and hold "Hold to approve" for about a second, until the button fills up. Deleting always needs your own OK, so that card is marked ⚠; the button is still "Hold to approve". With Codex, the AI tells you what to expect;
- tap "Turn on lock-screen alerts" if you want them.
Then the AI asks whether it may send us a short "finished" report — how long it took and what was awkward. You see the text first; say no, and it isn't sent.
Step 13: Handover
Finally the AI runs agentj handover --lang en and passes on, word for word, the handover note the program writes with the real facts of the Agent J host: the Agent's name, the account ID, the paired phones, https://m.agentj.app on the phone, what to do if you lose a phone (agentj devices to find its id, then agentj revoke <id>) or forget the remote pairing password (it is kept only on this Agent J host; with a paired phone, agentj passphrase reset --phone keeps every phone paired after you confirm on the phone and type the new one in the terminal; without one, agentj passphrase reset unpairs every phone), updates, where "Resume", "Schedules" and "Commands" are, refunds, and that uninstalling doesn't cancel the billing. The program writes it; the AI doesn't change it or add commands.
It also asks whether you want the "look it up first" rule in its long-term memory. If you do, it runs agentj docs-rule --write itself; the program adds the rule once to the end of the AI's memory file and shows what it added. From then on, when you ask it about Agent J in a later conversation, it checks these pages first and asks us for you if they don't answer it. The Agent on your phone already knows that rule.
Stopping halfway
Just tell the AI to stop. It asks whether to report which step you stopped at (and shows you that report first). Next time, send it the same sentence again; it checks everything from the top and carries on.
To remove it completely, run in a terminal:
agentj service uninstall
uv tool uninstall agentj
This removes only Agent J's own program. Your Claude Code, Codex or OpenCode and the Agent's work folder are left alone. Agent J scheduled tasks moved to the system scheduler are switched off too. Uninstalling doesn't stop the billing: cancel the seat and the subscription under "Manage billing" in the account dashboard — see Account and billing.
Every paid, unbound seat has its own one-line installation code. Two empty paid seats can claim two codes. Unused expired or revoked codes can be replaced, subject to the service’s daily allowance (midnight UTC reset).
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.
macOS requirements
First run opencode --version (or your selected agent’s --version). If it works, continue installing; there is no macOS version-number gate. The one-line installer also probes its downloaded, pinned OpenCode binary. Only an actual failure such as dyld: Symbol not found: _ubrk_clone in /usr/lib/libicucore.A.dylib indicates incompatible system libraries. PATH changes or npm reinstalls cannot fix that; upgrade macOS, use another computer, or choose another working agent with the manual installation guide. The one-line installer downloads pinned uv from our site first, uses a managed-Python mirror, and retries package dependencies via a mirror; the obsolete preview path is no longer supported.
An installed computer can also use an AJI installation code. Rerun the account-page installation command to preserve its configuration, upgrade and link its seat. Alternatively, keep the code in a mode-0600 file and run agentj login --install-code-file <file> --name <name>. AJI codes are single-use; ajt_ setup codes only link an installed computer. After linking, add a remote from the account page, confirm each start and approval with a fresh account passkey, and scan. Any required host pairing password is an additional check.
If a manual installation asks for Installation code (AJI-…), choose "Copy installation code" on the account page and paste only that AJI- code.
Intel Mac installations keep cryptography<49, including updates. If an older installer fails while compiling OpenSSL (openssl-sys), add --with "cryptography<49" to uv tool install.
Set up AI command-line tools · agentj command reference
Keep the Agent J host awake: commands, system settings and a request to send your Agent.
A second person on the Agent J host
Give each person a paid seat, their own installation code and phone pairing: either another instance on the same OS user (agentj --instance 2, simple) or an OS user per person (stronger separation). See sharing a computer.
Before you leave the Agent J host
With both remotes paired, let your Agent finish and verify everything remote work will need from you while you are still at the Agent J host. See Before you leave the Agent J host. For Gmail, Calendar and YouTube API access, see Connect Google.
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. Keys saved to the managed service environment file through the phone secret card are reread automatically; Telegram rebind rereads the file too. If a restart is needed, use Settings → Emergency repair → Restart service on a paired phone. Keep keys out of the plist, chat and command arguments.
示例工作流 / Example workflows
After account linking, installation or upgrade downloads three signed plaza examples (knowledge wiki, scripts and articles, ebook writing) into the configured working root if it has fewer than three WDB workflows. Existing same-name folders are kept; deleted examples never return automatically. Tell Agent J: organise my other folders to this spec. Offline downloads retry on a later start.
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.
Find the guide and copy instructions
On your account page, Installation guide sits beside Plaza and on each empty-seat card. It opens a new tab so your account stays open. Installation commands and prompts have a copy icon: press it to copy the whole block, then paste it into the named terminal or AI. Examples containing AJI-… are placeholders; copy your own complete installation command from your seat card.
Choose a working folder and handle a slow OpenCode start
The installer asks for a working folder; Enter confirms the suggested coding subfolder in your home. Choose a folder for the Agent's work, not your home folder or the root of a disk. Paths resolving to either of those, including aliases, and paths that are files are refused before installation proceeds.
Windows installation uses Ubuntu in WSL2. Native Windows OpenCode Desktop is a separate app: Agent J cannot repair or change that app's startup. If it stalls while fetching models.dev, fully quit it and launch it from a terminal that sets this environment variable, so the new app process inherits it:
$env:OPENCODE_DISABLE_MODELS_FETCH = '1'
Launch OpenCode from that same terminal using its installed launcher. It can then use its local model cache or bundled catalog; this does not download fresh model information. The Agent J installer and managed OpenCode launches set this flag themselves. This fallback was checked with the pinned Linux OpenCode binary, not a Windows machine.
A managed OpenCode request still waiting after 30 seconds shows a one-time explanation, even if startup keeps printing. If the installer cannot get OpenCode's startup information within 45 seconds, it stops with a reason and repair steps. Check network access, the AI login and the working folder, then retry. A slow-start notice is not proof the AI connected.
Three choices for safety review (Jev)
Choose a review route during setup. If you have neither a key nor a choice, agentj onboarding prompts you to finish this step. Recommended: register with TypeSafe, create a key and add a small balance, then enter TYPESAFE_API_KEY using the secret card in the Jev section near the top of Models & API keys. An existing OpenRouter account also works: enter OPENROUTER_API_KEY. Existing keys are selected automatically (OpenRouter when both exist); change the route in Settings → Safety.
Jev adds model review to bot and friend messages, rechecks redacted content and helps approvals assess unclear commands. Necessary redacted text goes directly to the selected provider, charged to your account under its data policy. TypeSafe uses its official API; OpenRouter routes to Jev. Review can misjudge and adds delay. An unavailable selected provider retains the channel's existing failure handling; it never silently turns review off.
You can turn the master switch off in Settings → Safety and explicitly confirm “Skip — I understand safety is weaker”. The host records jev.mode=off, the signing device and confirmation time. All Jev model review is then bypassed and bot/friend flows continue; local patterns, credential filters, permission approvals and tool authorization remain. Off avoids model delay and false positives while removing this protection, even when a key is present. The Agent cannot sign for you or disable review by editing configuration. Only your paired phone's signed choice counts; unpairing that signing device invalidates the off authorization.
Agent J uses a named, Developer ID-signed app with its own icon in macOS Login Items & Extensions. Host keeps the phone connected; Rescue watchdog helps when the host is stuck. Keep both enabled. Weekly tasks run on their schedules; disable tasks you no longer need. Upgrades rewrite Host and Rescue entries and migrate old weekly notification jobs. If the signed app download fails, go online and retry agentj service install.
First remote: use Add a remote on the account-page seat card, or run agentj pair in your terminal. The local 127.0.0.1 settings page only links to the account page. Keep the account page open after it shows the QR: scanning automatically brings up the waiting remote, six-digit confirmation code and Approve. Compare the codes on both screens before approving. Later remotes open https://m.agentj.app to request pairing; a paired remote scans, compares the codes and approves.
First remote — choose your situation:
- Own account: open
account_urlreturned byagentj pair --check --json, choose Add a remote on this host's seat card, scan, compare the six digits and approve. - Seat only: type this line yourself in the host's terminal:
agentj pair. Set and enter your own remote pairing password (at least 8 characters), then enter the remote's six digits; AI must never set, read or type the password for you. - Someone else opened the account: ask the account manager to approve on the account page. If you have no account and prefer not to use the terminal, ask that manager for help.
agentj pair shows both QR and link by default; --link remains compatible. Way 1: scan with your phone. Way 2: paste the same link into a computer browser's address bar. The link is a pairing key, valid for 5 minutes and one use; never share it with anyone or an AI. On iPhone paste into the pairing-link box inside the Home Screen icon.
After the first remote: phone first → open https://m.agentj.app in your usual computer browser, scan its code with the paired phone, compare and confirm on the phone; computer first → on the computer open Settings → Remotes → Add a remote, scan with your phone remote, compare and confirm on the computer. Finish installation after both remotes and the first message are verified.
Upgrade an older installation
After an upgrade, your main Agent's announcement and the phone's update notes show only changes for your current AI coding tool, together with changes shared by all tools.
On an ordinary host, first run agentj update apply, then check agentj --version and agentj doctor. Only when that command is unavailable or the old updater fails (for example it cannot reach GitHub), run curl -fsSL https://agentj.app/install.sh | bash again as the same OS user (no code): it repairs forward from agentj.app with the same hash and release-signature checks; if an earlier sudo run left folders to another account, it prints one sudo chown command and asks before running it. Keep configuration and bindings; do not unlink, delete state or create another seat. Olares Market applications still update through Market.
When an automatic upgrade fails
If downloading, verification or installation preparation fails, Agent J reports that the previous version remains installed. Ask your Agent to run agentj doctor and check the cause. Keep your configuration, account binding and existing seat.
After a rollback, a working old program counts as a successful rollback; any remaining service or health-check problem is reported separately and still needs attention. Older updaters gain these improvements only after installing the new version successfully. If an old uv updater cannot finish, use the repair command in the old-updater FAQ from the computer's terminal as the same system user. It needs no new installation code and preserves configuration and bindings. Update Olares Market apps through Market.
How can I upgrade a host that repeatedly reports a dependency download failure?
For an existing uv installation, use the original OS account to run this command in a terminal on the host. It requires access to agentj.app and the PyPI file server, files.pythonhosted.org. If your organization uses a private package index, check that its policy permits downloads from PyPI.
curl --proto '=https' --tlsv1.2 -fsSL https://agentj.app/install-assistant.sh | sh -s -- --upgrade-only --repair-index
The repair verifies the Agent J release signature, downloads the dependency wheels selected for your platform, checks their hashes against the release manifest, and restarts the host after installation. Your seat, pairing and settings are preserved. Run agentj --version and agentj doctor to check the result. If it still fails, send support the displayed error code and version. Update Olares Market installations through the Market.
If the AI cannot start for the first time
Keep the AJ_START_* diagnostic code for your Agent and ask it to run agentj doctor --offline. For a background-service environment problem, check the model proxy in phone Settings. After installing an AI command-line tool, run agentj service install to refresh the service configuration and check again.
You can keep an existing Volcano Ark, Alibaba Bailian or Kimi account. Provider setup opens the phone key card directly and reuses saved keys rather than asking again. Wait for the card to confirm completion before switching models. Never send keys in chat.
An Agent is missing after installing from a desktop app
Installing from a desktop app such as ChatGPT works too. The background service builds a stable PATH from your login shell and common user installation folders; it does not save the app’s temporary paths. If Claude Code works in your terminal but Agent J says it is missing, run agentj doctor. When it reports a missing program in the service PATH, run agentj service install once, then check again. This restarts Agent J and your phone reconnects after a brief interruption. You do not need to reinstall Claude Code or share login files or keys in chat.
OpenCode compatibility
Agent J selects the native protocol for OpenCode 1.x or 2.x automatically. Isolated tests cover 1.19.4 and 2.1.4. Existing 1.x installs keep working; a Homebrew 2.x install does not need downgrading. Start a new conversation only if you want one: upgrading OpenCode does not require clearing your conversation.
If starting or switching fails, run agentj doctor on the host. Agent J checks that its local server starts before completing a switch. The separate tool-free private-message executor requires the older CLI's --dir contract; OpenCode 2.1.4 does not offer it and is refused before a private-message process starts. Use a supported Claude Code or Codex executor for that channel.
Read-only emergency diagnosis tries freshly listed free DeepSeek Flash first, then opencode/glm-5.3-flash-free only when the current official model page confirms zero retention and no training, then an explicitly installed local Ollama model. LongCat and Space Bunny are excluded. Availability is checked again; no paid model is selected automatically, and the original task is never replayed. Cloud diagnosis receives fixed error signals only.
OpenCode 2.1 removed the old verbose model-list command. Agent J checks its native price catalogue automatically, so free-model discovery does not require that command. The installer uses the host’s verified model list before trying a model.