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

搜索文档和页面Search docs and pages

文档Docs

安装Installing Agent J

先选你的电脑（Windows、macOS、Linux），再选一种装法：自己一条命令、让电脑上的 AI 装、云端安装助手，或者请人帮你装。Pick your computer (Windows, macOS, Linux), then one way to install: one command yourself, the AI on your computer, the cloud installation assistant, or a helper.

四种装法装出来的是同一个 Agent J，装好以后都在手机上跟它说话。拿不准就选①。

Windows

适用于 Windows 10 和 Windows 11（64 位）。Agent J 运行在微软的 Linux 子系统（WSL2）里的 Ubuntu 上，安装命令会先把它装好，你不用提前准备。

① 自己装：一条命令

什么时候选它： 电脑上还没有 AI 工具，或者你想自己动手。全程只用一个码：账户页空席位卡上的安装码（AJI- 开头）。

预计时间： 通常 15 到 30 分钟，大部分是在下载；第一次装 WSL 可能要重启一次。要你动手的部分加起来几分钟。

  1. 在账户页 https://agentj.app/account/ 的空席位卡点「获取专属安装命令」，再点「复制安装命令」。在 Windows 上打开账户页，给的就是 PowerShell 那一条；不是的话点「换成 Windows（PowerShell）命令」。
  2. 打开 PowerShell（开始菜单里搜 PowerShell，不用管理员身份），粘贴，回车。命令长这样：$env:AGENTJ_CODE='AJI-…'; irm https://agentj.app/install.ps1 | iex
  3. 照屏幕走。每一步开头都写着这是第几步、在做什么：
屏幕上你要做的
安装码命令里带了码就直接用；没带会让你粘贴一次（不显示）
WSL2 和 Ubuntu弹出管理员确认窗口时点同意；要重启就重启，重启后再粘贴同一条命令
Ubuntu 用户起个用户名（直接回车用默认的），设一个密码（输入时不显示，记住它）
系统组件不用做，Windows 上不问密码
AI已经登录过 Claude Code 或 Codex 就直接用。没有就选一条路：连不上官方服务选 Agents Relay 中转（见香港和中国大陆），能连就在浏览器里登录官方账号
Agent J不用做：装好、启动后台服务、用同一个码绑定这个席位
手机屏幕上出现二维码：用你自己的手机打开 https://m.agentj.app ，点「扫二维码」扫它
接上 AI不用做：AI 先真实回复一次才接上
  1. 看到「✅ 全部完成」，就在手机上跟它打个招呼。以后要在电脑上用 agentj，从开始菜单打开「Ubuntu」，不是 PowerShell。

出了问题：

  • 中途哪一步失败，屏幕上会写一行「怎么办：…」。修好后粘贴同一条命令，做完的步骤会跳过。
  • 安装码只能用一次，24 小时内有效（卡片上写着到期时间）。
  • 只差 AI 没接上：在「Ubuntu」里再运行一次 curl -fsSL https://agentj.app/install.sh | bash（不用带码），它只补这一步。
  • 确认 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 时，也会用一句话告诉你这两步。

② 让电脑上的 AI 帮你装

什么时候选它： 你已经在 WSL 的 Ubuntu 里用 Claude Code、Codex 或 OpenCode，想让它替你操作、边装边解释。Windows 上 Agent J 只能装在 WSL2 里，装在 Windows 本身的 AI 会停下来告诉你；还没有 WSL 的话，选①更省事。

  1. 已经买了席位：在账户页空席位卡上点「复制安装提示词」，发给 Ubuntu 里的 AI。
  2. 还没买：把下面这句话原样发给它，它会带你注册账号、买席位：

请用 curl 把 https://agentj.app/install.md 下载到本地，用读文件的工具完整读完，然后一步一步照着做，每一步开始前重读那一节。需要我动手的时候告诉我。

AI 每一步做什么、哪几步会停下来叫你，见让 AI 装的时候。

③ 远程安装助手（云端）

什么时候选它： 身边没人帮忙，电脑上也没有 AI，装到一半卡住了想问人。

现在这样用：

  1. 照①的命令装。这条命令本身就是安装助手：每一步在做什么都写在屏幕上，出错时会写一行「怎么办：…」。照着修好，再粘贴同一条命令接着装。
  2. 还是弄不明白，而 Agent J 已经装上了：在「Ubuntu」里运行下面这条命令。它把你的问题和去掉了密钥的体检结果发给我们服务器上的客服，一般几分钟内回你具体步骤。
agentj support ask "<你的问题>" --attach-doctor
  1. 还没装上，或者连不上我们：发邮件到 feedback@agentj.app，写清卡在哪一步、报错原文，附上截图（先遮住安装码、key 和二维码）。

提示：后续版本计划让云端助手直接在你的手机上给出下一步建议，你点了才执行。

④ 请人帮你装：在旁边或远程

什么时候选它： 你不熟悉电脑或终端，有家人、朋友或同事能坐在旁边，或者通过视频通话、屏幕共享帮你。

现在的做法：

  1. 帮手照①带着你做。码只在你自己的账户页复制，只粘在你自己的电脑上；远程帮的时候你共享屏幕、帮手口头指挥，码和 key 不要发进聊天。
  2. 中途会弹出 Windows 的管理员确认窗口，可能还要重启一次。帮手提前跟你说一声，你就不会慌。
  3. 扫二维码配手机，用你自己的手机。如果扫的是帮手的手机，它就成了这台电脑的遥控器：装完以后运行 agentj devices 找到它的设备号，再运行 agentj revoke <设备号> 把它移走。
  4. 当时手机不在手边，或者扫码那一步没配上，不用重装：装好以后在账户页这台电脑的席位卡上点「添加遥控器」，用通行密钥确认，再用你的手机扫码。

提示：一键帮手配对计划在后续版本推出：帮手用自己的手机临时连上，在手机上带你装完；你的手机配好、AI 接上以后，帮手自动断开。

macOS

适用于 Apple 芯片和 Intel 芯片的 Mac。

① 自己装：一条命令

什么时候选它： 电脑上还没有 AI 工具，或者你想自己动手。全程只用一个码：账户页空席位卡上的安装码（AJI- 开头）。

预计时间： 一般 10 分钟以内。机器自己跑只要几分钟（我们的测试机上约 2 分钟），其余是你登录 AI、扫码的时间。

  1. 在账户页 https://agentj.app/account/ 的空席位卡点「获取专属安装命令」，再点「复制安装命令」。在 Mac 上打开账户页，给的就是终端那一条；不是的话点「换成 macOS / Linux 命令」。
  2. 打开终端（按 Command + 空格，搜 Terminal），粘贴，回车。命令长这样：curl -fsSL https://agentj.app/install.sh | bash -s -- AJI-…
  3. 照屏幕走。每一步开头都写着这是第几步、在做什么：
屏幕上你要做的
安装码命令里带了码就直接用；没带会让你粘贴一次（不显示）
系统组件可能要输入一次电脑密码（输入时不显示）
AI已经登录过 Claude Code 或 Codex 就直接用。没有就选一条路：连不上官方服务选 Agents Relay 中转（见香港和中国大陆），能连就在浏览器里登录官方账号
Agent J不用做：装好、启动后台服务、用同一个码绑定这个席位
手机屏幕上出现二维码：用你自己的手机打开 https://m.agentj.app ，点「扫二维码」扫它
接上 AI不用做：AI 先真实回复一次才接上
  1. 看到「✅ 全部完成」，就在手机上跟它打个招呼。装完以后，同一个终端窗口里就能直接用 agentj status。

出了问题：

  • 中途哪一步失败，屏幕上会写一行「怎么办：…」。修好后粘贴同一条命令，做完的步骤会跳过。
  • 安装码只能用一次，24 小时内有效（卡片上写着到期时间）。
  • 只差 AI 没接上：再运行一次 curl -fsSL https://agentj.app/install.sh | bash（不用带码），它只补这一步。

② 让电脑上的 AI 帮你装

什么时候选它： 你已经在用 Claude Code、Codex 或 OpenCode，想让它替你操作、边装边解释。

  1. 已经买了席位：在账户页空席位卡上点「复制安装提示词」，发给电脑上的 AI。
  2. 还没买：把下面这句话原样发给它，它会带你注册账号、买席位：

请用 curl 把 https://agentj.app/install.md 下载到本地，用读文件的工具完整读完，然后一步一步照着做，每一步开始前重读那一节。需要我动手的时候告诉我。

AI 每一步做什么、哪几步会停下来叫你，见让 AI 装的时候。

③ 远程安装助手（云端）

什么时候选它： 身边没人帮忙，电脑上也没有 AI，装到一半卡住了想问人。

现在这样用：

  1. 照①的命令装。这条命令本身就是安装助手：每一步在做什么都写在屏幕上，出错时会写一行「怎么办：…」。照着修好，再粘贴同一条命令接着装。
  2. 还是弄不明白，而 Agent J 已经装上了：在终端里运行下面这条命令。它把你的问题和去掉了密钥的体检结果发给我们服务器上的客服，一般几分钟内回你具体步骤。
agentj support ask "<你的问题>" --attach-doctor
  1. 还没装上，或者连不上我们：发邮件到 feedback@agentj.app，写清卡在哪一步、报错原文，附上截图（先遮住安装码、key 和二维码）。

提示：后续版本计划让云端助手直接在你的手机上给出下一步建议，你点了才执行。

④ 请人帮你装：在旁边或远程

什么时候选它： 你不熟悉电脑或终端，有家人、朋友或同事能坐在旁边，或者通过视频通话、屏幕共享帮你。

现在的做法：

  1. 帮手照①带着你做。码只在你自己的账户页复制，只粘在你自己的电脑上；远程帮的时候你共享屏幕、帮手口头指挥，码和 key 不要发进聊天。
  2. 要输入电脑密码的时候由你自己输，不要告诉帮手。
  3. 扫二维码配手机，用你自己的手机。如果扫的是帮手的手机，它就成了这台电脑的遥控器：装完以后运行 agentj devices 找到它的设备号，再运行 agentj revoke <设备号> 把它移走。
  4. 当时手机不在手边，或者扫码那一步没配上，不用重装：装好以后在账户页这台电脑的席位卡上点「添加遥控器」，用通行密钥确认，再用你的手机扫码。

提示：一键帮手配对计划在后续版本推出：帮手用自己的手机临时连上，在手机上带你装完；你的手机配好、AI 接上以后，帮手自动断开。

Linux

适用于 Ubuntu、Debian 等常见发行版，台式机、笔记本和云服务器都可以。只能用 SSH 登录、没有桌面的云服务器，还要看安装说明里云服务器那一节。

① 自己装：一条命令

什么时候选它： 电脑上还没有 AI 工具，或者你想自己动手。全程只用一个码：账户页空席位卡上的安装码（AJI- 开头）。

预计时间： 一般 10 分钟以内。机器自己跑只要几分钟（我们的测试机上约 2 分钟），其余是你登录 AI、扫码的时间。

  1. 在账户页 https://agentj.app/account/ 的空席位卡点「获取专属安装命令」，再点「复制安装命令」。在 Linux 上打开账户页，给的就是终端那一条；不是的话点「换成 macOS / Linux 命令」。
  2. 打开终端，粘贴，回车。命令长这样：curl -fsSL https://agentj.app/install.sh | bash -s -- AJI-…
  3. 照屏幕走。每一步开头都写着这是第几步、在做什么：
屏幕上你要做的
安装码命令里带了码就直接用；没带会让你粘贴一次（不显示）
系统组件会装 bubblewrap 和 socat（让 Agent 在隔离里运行），可能要输入一次电脑密码（输入时不显示）
AI已经登录过 Claude Code 或 Codex 就直接用。没有就选一条路：连不上官方服务选 Agents Relay 中转（见香港和中国大陆），能连就在浏览器里登录官方账号
Agent J不用做：装好、启动后台服务、用同一个码绑定这个席位
手机屏幕上出现二维码：用你自己的手机打开 https://m.agentj.app ，点「扫二维码」扫它
接上 AI不用做：AI 先真实回复一次才接上
  1. 看到「✅ 全部完成」，就在手机上跟它打个招呼。装完以后，同一个终端窗口里就能直接用 agentj status。

出了问题：

  • 中途哪一步失败，屏幕上会写一行「怎么办：…」。修好后粘贴同一条命令，做完的步骤会跳过。
  • 安装码只能用一次，24 小时内有效（卡片上写着到期时间）。
  • 只差 AI 没接上：再运行一次 curl -fsSL https://agentj.app/install.sh | bash（不用带码），它只补这一步。

② 让电脑上的 AI 帮你装

什么时候选它： 你已经在用 Claude Code、Codex 或 OpenCode，想让它替你操作、边装边解释。

  1. 已经买了席位：在账户页空席位卡上点「复制安装提示词」，发给电脑上的 AI。
  2. 还没买：把下面这句话原样发给它，它会带你注册账号、买席位：

请用 curl 把 https://agentj.app/install.md 下载到本地，用读文件的工具完整读完，然后一步一步照着做，每一步开始前重读那一节。需要我动手的时候告诉我。

AI 每一步做什么、哪几步会停下来叫你，见让 AI 装的时候。

③ 远程安装助手（云端）

什么时候选它： 身边没人帮忙，电脑上也没有 AI，装到一半卡住了想问人。

现在这样用：

  1. 照①的命令装。这条命令本身就是安装助手：每一步在做什么都写在屏幕上，出错时会写一行「怎么办：…」。照着修好，再粘贴同一条命令接着装。
  2. 还是弄不明白，而 Agent J 已经装上了：在终端里运行下面这条命令。它把你的问题和去掉了密钥的体检结果发给我们服务器上的客服，一般几分钟内回你具体步骤。
agentj support ask "<你的问题>" --attach-doctor
  1. 还没装上，或者连不上我们：发邮件到 feedback@agentj.app，写清卡在哪一步、报错原文，附上截图（先遮住安装码、key 和二维码）。

提示：后续版本计划让云端助手直接在你的手机上给出下一步建议，你点了才执行。

④ 请人帮你装：在旁边或远程

什么时候选它： 你不熟悉电脑或终端，有家人、朋友或同事能坐在旁边，或者通过视频通话、屏幕共享帮你。

现在的做法：

  1. 帮手照①带着你做。码只在你自己的账户页复制，只粘在你自己的电脑上；远程帮的时候你共享屏幕、帮手口头指挥，码和 key 不要发进聊天。
  2. 要输入电脑密码的时候由你自己输，不要告诉帮手。
  3. 扫二维码配手机，用你自己的手机。如果扫的是帮手的手机，它就成了这台电脑的遥控器：装完以后运行 agentj devices 找到它的设备号，再运行 agentj revoke <设备号> 把它移走。
  4. 当时手机不在手边，或者扫码那一步没配上，不用重装：装好以后在账户页这台电脑的席位卡上点「添加遥控器」，用通行密钥确认，再用你的手机扫码。

提示：一键帮手配对计划在后续版本推出：帮手用自己的手机临时连上，在手机上带你装完；你的手机配好、AI 接上以后，帮手自动断开。

Olares 盒子

Agent J 也能装在 Olares 盒子上（Olares 1.12 或更新），数据留在盒子里。

  • 装在盒子自己的 Ubuntu 上，用普通用户（不用 root），和装云服务器一样。不要装进 Olares 应用里：在那些容器里，Agent J 的安全围栏起不来。
  • 让它一直运行： AI 会请你运行一次 sudo loginctl enable-linger <用户名>（密码你自己输），再重新登录一次，然后它把服务装好。
  • 模型： 用盒子自带的 Olares Router。在 Router 应用里新建一把 API key，AI 通过 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 和二维码。这些东西落到别人手里，可能被拿去占用你的席位，或者申请连你的电脑。

让 AI 装的时候

为什么要先下载、完整读完：有的 AI 用网页工具只读到一份摘要，摘要会把安全规矩和要停下来问你的地方省掉。它开始之前可能先跟你讲讲风险、问你要不要继续，这很正常。

如果别人已经给你付了一个席位，他会发你一句更长的话，里面带一个 ajt_ 开头的设置码。那就直接发那一句，不用发上面这句。

接下来它会自己干活。遇到只有你本人能做的事，它会停下来，用你看得懂的话告诉你要做什么，等你说「好了」再继续。

install.md 是给 AI 看的安装说明，所以用英文写。这一页是同一套流程的大白话版，步骤编号跟它一一对应。

哪些事要你本人来做

AI 不会替你做下面这些事，也不会让你把密码、验证码、口令这类东西发给它。到了这些地方，它一定会停下来叫你：

  • 设遥控器配对密码（安装结束时会问你一句，可选，推荐设；在终端里配对时必须有）；

它要报告问题时，会先把原文给你看。你同意，才发。见 广场与反馈。

每一步在做什么

下面的编号和 install.md 一样。标了 ✋ 的步骤整步都要你动手，没标的步骤里也可能有一两处要叫你。

第 1 步：核对安装说明

下载安装说明，核对两件事：网站公布的校验值对得上，网站那份和 GitHub 公开那份一字不差。对不上它会停下来告诉你，不会继续装。

第 2 步：准备好反馈

AI 先开一个反馈通道，以后哪一步出了问题，可以把问题报给我们。开通道时不带任何内容，我们只看到你电脑的 IP 和时间。之后每次发反馈，它都会先把原文给你看。

第 3 步：检查电脑环境

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 或别的系统软件时，输入你的电脑密码；
  • Claude Code 或 Codex 没登录时，在你自己的终端里登录；
  • 在中国大陆，或者一个能用的都没有时，AI 会帮你装 OpenCode。模型账号要你自己去模型厂商那里注册、充值、建 key，再在你自己的终端里运行 opencode auth login 把 key 存好。AI 不会碰你的 key，也不会问你要。

第 4 步：安装 agentj 程序

AI 安装电脑端程序 agentj，装的是固定的一个版本：

uv tool install "git+https://github.com/preangelleo/agentj@v0.23.0a1#subdirectory=host"
agentj doctor

agentj doctor 会逐行检查，告诉你哪些已就绪、哪些还没好。如果 GitHub 太慢或打不开（比如在中国大陆），AI 会自动改从我们网站下载同一个程序，先核对校验值再安装。

装好以后，你自己的终端也要能找到 agentj，因为第 8 步和第 11 步要你自己运行它。新开的终端找不到的话，AI 会先问你能不能运行 uv tool update-shell：它会在你终端的启动文件里加一行。你同意了它才运行，之后新开一个终端窗口就能用。不想改启动文件，就在要用的终端里先输入 export PATH="$HOME/.local/bin:$PATH"，或者新开一个终端试试。

第 5 步：生成这台电脑的身份

agentj init

这一步给这台电脑生成它自己的钥匙。钥匙只存在这台电脑上，谁也不该去碰它，包括 AI。

第 6 步：✋ 注册账号、买席位

如果你发给 AI 的那句话里有设置码（别人给你付的席位），跳过这一步：钱已经付了，你不用注册，也不用付款。

否则，AI 会请你：

  1. 用浏览器打开账号后台 https://agentj.app/account ，在电脑上或手机上都行。填邮箱，点「发送验证码」，把邮件里的 6 位验证码填在网页上，点「登录」。验证码 10 分钟内有效，邮件来自 noreply@mail.agentj.app，没收到就看看垃圾邮件。验证码只填在网页上，别发给 AI。
  2. 按网页提示点「在这台设备上创建通行密钥」，用指纹、面容或屏幕锁确认。要在收到验证码后 10 分钟内做完。Linux 电脑的浏览器一般没有自带的通行密钥：在弹出的窗口里选用手机（扫一下屏幕上的二维码），或者用 USB 安全钥匙；更简单的办法是这一步直接在手机上做。
  3. 「团队名称（选填）」可以不填，点「开通账号」。
  4. 在「账单」里买 1 个席位：选「月付」或「年付」，「买几个席位」填 1；有优惠码或邀请码就填在「优惠码或邀请码（可不填）」里；点「购买席位」，到 Stripe 的页面付款。价格和优惠码的规矩见 账号与付款。
  5. 付完回到账号后台，在「空席位」卡片上点「复制安装提示词」，把这句话发给电脑上的 AI。它就接着往下装了。

Stripe 付款页上的价格是美元，商户名是 AgentJ.app。第一次付款后 7 天内不想用了，可以全额退款。付完回到账号后台，如果页面让你登录：钱已经付成功了，用通行密钥或邮箱验证码再登录一次就好，别再付一次。

第 7 步：✋ 把这台电脑加到账号里

AI 先问你：这个 Agent 叫什么名字？1 到 32 个字，比如「小助手」「店铺助手」，或者你自己起的名字。然后它用那句话里的设置码，把这台电脑加到账号的这个席位上，再把加入的是哪个账号告诉你。请你核对一下账号 ID，不对的话它会马上退出来。用完以后，它会把存设置码的那个临时文件删掉。

安装提示词不能用时，回到同一张空席位卡再次复制，会签发新的七天单次码，并作废之前未使用的码。旧八位码入口已经退役，重试不要再买一个席位。

第 8 步：✋ 用账户页通行密钥批准

电脑绑定完成后，在账户页这台电脑的席位卡上点「添加遥控器」，用通行密钥（或这台电脑的遥控器配对密码）确认，扫码即可。同一账户页也能给另一台已绑定、在线的电脑添加手机。

安装结束时会问你要不要设遥控器配对密码（可选，推荐）：直接回车就跳过，以后随时运行 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 以你的身份干活，如果这台电脑上有浏览器开着调试端口，Agent 就能操作它，用上里面所有已登录的网站。但在任何网站上付款、下单、转账，都一定会先停下来，到手机上问你，不管你登录了什么，所以问了也不会改变什么。真有这样的端口开着，AI 会点名告诉你。

它还会装上「工作流设计向导」，配对好以后，你在手机上说「帮我设计工作流」就能用。

这一步有两件事 AI 一定会做，不会跳过：问你 Agent 在哪个文件夹里干活；单独发一条消息，告诉你隔离挡不住什么。你看过了它再往下走。

第 10 步：让它一直运行

agentj service install

装成系统服务后，电脑开机登录后它会自己启动，不用你每次手动开。装完 AI 会运行 agentj doctor，把以 ! 开头的每一行用人话告诉你。常见的一种：Claude Code 只靠环境变量登录，后台服务拿不到这个登录。这时你在终端里运行一次 claude 正常登录，再让 AI 重装一次服务就好。在云服务器上，AI 可能会请你运行一次 loginctl enable-linger $USER（可能要输密码），这样你退出 SSH 后它也照样运行。

第 11 步：✋ 配对手机

配对之前，电脑上的 Agent J 要在运行（第 10 步）。

  1. 经账户页批准的配对不需要终端六位码，等手机连上即可。

电脑离线或账户页添加遥控器已关闭时（agentj pair --check 会告诉你），用本机备选：运行 agentj pair（或 agentj pair --link），在那台电脑上输入手机六位码和遥控器配对密码（还没设会先请你设一个）。

第 12 步：在手机上试一试

AI 会请你在手机上：

  1. 发一句「列出这个文件夹里有什么」，看能不能收到回复；
  2. 让它建一个测试文件再删掉。手机上会弹出卡片，按住「长按批准」大约一秒，按钮填满再松手。删除要你单独点头，所以那张卡片标着 ⚠，按钮照样是「长按批准」。用 Codex 的话，它会告诉你会看到什么；
  3. 想要锁屏提醒的话，点「开启锁屏提醒」。

然后 AI 会问你要不要给我们发一条「装完了」的反馈，写用了多久、哪里不顺。发之前先给你看原文，你说不发就不发。

第 13 步：交接

最后，AI 运行 agentj handover --lang zh，把这台电脑上填好真实信息的交接说明原样转给你：Agent 名、账号 ID、配了哪些手机、手机上打开 https://m.agentj.app 、丢了手机怎么办（agentj devices 找到设备号，再 agentj revoke <设备号>）、忘了遥控器配对密码怎么办（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 的工作文件夹。卸载不会停止扣费：席位和订阅要在账号后台的「管理账单」里取消，见 账号与付款。

每个已付费且未绑定的席位各可领取一张安装码。两个空余付费席位可领两张码；未使用码作废或过期后可重领，仍受安装服务日额度限制，UTC 零点重置。

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

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

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

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

macOS 系统版本

先试运行 opencode --version（或所选 Agent 的 --version）；能正常运行就能继续安装，不按 macOS 版本号拦截。一键安装也会实际试运行它下载的固定版 OpenCode。如果看到 dyld: Symbol not found: _ubrk_clone 和 /usr/lib/libicucore.A.dylib 后退出，才说明该二进制与系统库不兼容；PATH 或 npm 重装不能修复，请升级系统、换电脑，或用能正常运行的其他 Agent 按手动路线安装。一键安装优先从本站下载固定版本 uv，托管 Python 使用镜像，包依赖失败时重试镜像；旧预览下载路径已停用。

已安装 Agent J 的电脑也能使用 AJI 安装码：重新运行账户页的一键安装命令，会保留配置，只升级并绑定席位。也可把码放在权限为 0600 的文件中，运行 agentj login --install-code-file <文件> --name <名字>。AJI 码只能用一次；ajt_ 设置码只用于绑定已安装的电脑。绑定后到账户页添加遥控器，用通行密钥或遥控器配对密码确认后扫码。

手动安装时，如果提示要填 Installation code (AJI-…)，去账号后台点「复制安装码」，只粘贴这串 AJI- 开头的码。

Intel Mac 安装和升级都会限制 cryptography<49。如果旧安装器报 openssl-sys 或找不到 OpenSSL，在 uv tool install 后加 --with "cryptography<49" 再试。

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

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

同一台电脑给第二个人安装

每人各用自己的付费席位、安装码与手机：同一个系统用户里多开实例（agentj --instance 2，简单），或每人一个系统用户（隔离更强）。完整步骤见一台电脑多人使用。

离开电脑前

两端配好后，趁你还在电脑前，让 Agent 把以后远程工作要你本人帮忙的事一次做完并验证，见离开电脑前，先把这些事一次做好。Google 邮件、日历、YouTube 的接口授权见连接 Google。

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

示例工作流

安装或升级并完成账号绑定后，若工作根还没有三套 WDB 工作流，会从广场校验并预装知识库、脚本与文章、电子书示例。已有同名目录保留；删除的示例不会自动补回。交给 Agent J：帮我按这个规格整理我的其他文件夹。离线时延后重试。

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

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 computer 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.

  1. 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".
  2. 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
  3. Follow the screen. Every step starts with its number and what it is doing:
On screenWhat you do
Installation codeTaken from the command; if it is missing you paste it once (hidden)
WSL2 and UbuntuAllow the Windows administrator prompt; restart if asked, then paste the same command again
Ubuntu userPick a user name (Enter takes the suggestion) and a password (hidden; remember it)
System partsNothing; Windows does not ask for a password
AIReuses 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 JNothing: it installs, starts the background service and links this seat with the same code
PhoneA QR code appears: open https://m.agentj.app on your own phone, tap "Scan QR code" and scan it
Connect the AINothing: the AI must answer one real request before it is connected
  1. When you see "✅ 全部完成" (all done), say hello to it from your phone. To use agentj on the computer 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).
  • Only the AI is missing? In "Ubuntu" run curl -fsSL https://agentj.app/install.sh | bash again (no code): it does just that step.
  • Confirm systemd is on: the background service runs on it. In "Ubuntu" run ps -p 1 -o comm=; it should print systemd. If not, in "Ubuntu" run printf '[boot]\nsystemd=true\n' | sudo tee -a /etc/wsl.conf (skip it when the file already has systemd=true under [boot]), then in PowerShell run wsl --shutdown, reopen "Ubuntu" and run agentj service install. The install command does both steps itself; agentj service install and upgrades also name these two steps in one sentence when systemd is off.

② Let the AI on your computer 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.

  1. Already bought a seat: press "Copy installation prompt" on the empty seat card in your account and send it to the AI in Ubuntu.
  2. 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 computer, and you are stuck halfway and want to ask someone.

How it works today:

  1. 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.
  2. 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
  1. 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:

  1. 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.
  2. 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.
  3. Scan the pairing QR code with your own phone. If the helper's phone scans it, that phone becomes a remote for this computer: afterwards run agentj devices to find its device ID, then agentj revoke <device-id> to remove it.
  4. Phone not at hand, or the scan did not work? No need to reinstall: once it is installed, press "Add a remote" on this computer'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 computer 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 computer'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.

  1. 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".
  2. 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-…
  3. Follow the screen. Every step starts with its number and what it is doing:
On screenWhat you do
Installation codeTaken from the command; if it is missing you paste it once (hidden)
System partsYou may be asked for your computer password once (hidden)
AIReuses 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 JNothing: it installs, starts the background service and links this seat with the same code
PhoneA QR code appears: open https://m.agentj.app on your own phone, tap "Scan QR code" and scan it
Connect the AINothing: the AI must answer one real request before it is connected
  1. When you see "✅ 全部完成" (all done), say hello to it from your phone. Afterwards agentj status works 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).
  • Only the AI is missing? Run curl -fsSL https://agentj.app/install.sh | bash again (no code): it does just that step.

② Let the AI on your computer 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.

  1. Already bought a seat: press "Copy installation prompt" on the empty seat card in your account and send it to the AI on the computer.
  2. 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 computer, and you are stuck halfway and want to ask someone.

How it works today:

  1. 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.
  2. 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
  1. 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:

  1. 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.
  2. When the computer asks for its password, you type it yourself; don't tell your helper.
  3. Scan the pairing QR code with your own phone. If the helper's phone scans it, that phone becomes a remote for this computer: afterwards run agentj devices to find its device ID, then agentj revoke <device-id> to remove it.
  4. Phone not at hand, or the scan did not work? No need to reinstall: once it is installed, press "Add a remote" on this computer'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.

① Install it yourself: one command

When to choose it: the computer 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 computer'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.

  1. 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".
  2. Open a terminal, paste and press Enter. The command looks like curl -fsSL https://agentj.app/install.sh | bash -s -- AJI-…
  3. Follow the screen. Every step starts with its number and what it is doing:
On screenWhat you do
Installation codeTaken from the command; if it is missing you paste it once (hidden)
System partsInstalls bubblewrap and socat (the Agent runs fenced); you may be asked for your computer password once (hidden)
AIReuses 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 JNothing: it installs, starts the background service and links this seat with the same code
PhoneA QR code appears: open https://m.agentj.app on your own phone, tap "Scan QR code" and scan it
Connect the AINothing: the AI must answer one real request before it is connected
  1. When you see "✅ 全部完成" (all done), say hello to it from your phone. Afterwards agentj status works 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).
  • Only the AI is missing? Run curl -fsSL https://agentj.app/install.sh | bash again (no code): it does just that step.

② Let the AI on your computer 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.

  1. Already bought a seat: press "Copy installation prompt" on the empty seat card in your account and send it to the AI on the computer.
  2. 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 computer, and you are stuck halfway and want to ask someone.

How it works today:

  1. 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.
  2. 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
  1. 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:

  1. 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.
  2. When the computer asks for its password, you type it yourself; don't tell your helper.
  3. Scan the pairing QR code with your own phone. If the helper's phone scans it, that phone becomes a remote for this computer: afterwards run agentj devices to find its device ID, then agentj revoke <device-id> to remove it.
  4. Phone not at hand, or the scan did not work? No need to reinstall: once it is installed, press "Add a remote" on this computer'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 it on the box's own Ubuntu, as a normal user (not root), the same way as on a cloud server. Don't install it inside an Olares app: Agent J's safety fence cannot start in those containers.
  • Keep it running: the AI asks you to run sudo loginctl enable-linger <user> once (you type your password), log in again, and then it installs the service.
  • The model: use the box's own Olares Router. Create an API key in the Router app; the AI connects it through DeepSeek's dsh or OpenCode, and you 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 your computer.

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 your computer 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 your computer;
  • 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 your computer'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 your computer 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 login in 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 your computer, at one fixed version:

uv tool install "git+https://github.com/preangelleo/agentj@v0.23.0a1#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 this computer's identity

agentj init

This gives the computer its own keys. They stay on this computer, 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:

  1. Open the account dashboard at https://agentj.app/account in a browser — on the computer 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.
  2. 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.
  3. Leave "Team name (optional)" empty if you like and tap "Open my account".
  4. 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.
  5. Back in the account dashboard, on the "Empty seat" card tap "Copy installation prompt", and send that sentence to the AI on your computer. 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 this computer to the Agent J account

First the AI asks what the Agent should be called: 1 to 32 characters — "Wren", "Shop assistant", whatever you like. Then it uses the setup code in the sentence to add this computer 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 this computer is bound, open its seat card on the account page and select Add a remote. Confirm with your passkey (or this computer's remote pairing password) and scan. 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 --json shows 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-work is 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 your computer 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 this computer 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 computer 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 computer first (Step 10).

  1. 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".
  2. In the account dashboard, find this computer’s seat card and choose Add a remote. Confirm with your passkey once; confirmation is reused for ten minutes on this session. The account page can be open on another computer.
  3. 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.
  4. This account-approved pairing needs no terminal code. Wait for the phone to connect.

When the computer 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:

  1. send "list the files in this folder" from the phone and check that a reply comes back;
  2. 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;
  3. 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 this computer: 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 passphrase (agentj passphrase reset, which 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. 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 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.

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 with your passkey or the remote pairing password, and scan.

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 your computer awake: commands, system settings and a request to send your Agent.

A second person on this computer

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 computer

With both remotes paired, let your Agent finish and verify everything remote work will need from you while you are still at the computer. See Before you leave your computer. 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. After saving it, run agentj service restart. 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.

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