文档Docs
手机上完成管理员授权和密钥录入Admin rights and API keys, from your phone
Agent 需要管理员权限或者某个 API key 时，会在你手机上弹一张卡片：密码和密钥在手机上输入，加密后直接交给你的电脑，Agent 自己看不到。When the Agent needs admin rights or an API key, a card appears on your phone: you type the password or paste the key there, it goes encrypted straight to your computer, and the Agent never sees it.
有些事 Agent 自己做不了：装系统软件要管理员密码，接一个新服务要你的 API key。以前只能请你回到电脑前，在终端里输 sudo 密码，或者把 key 贴进对话里，key 就这样留在了聊天记录里，也发给了模型厂商。
现在这两件事都在手机上完成。Agent 发起请求，你的手机弹出一张卡片；你在卡片上输入密码或粘贴 key，内容加密后直接交给你的电脑。Agent 只拿到结果，看不到密码，也看不到 key。
管理员密码卡
Agent 需要以管理员身份运行一条命令时，会运行：
agentj sudo --why '<为了做什么，用大白话写>' --effect '<会改动什么>' -- <命令>你的手机上会弹出一张卡片，标题是「需要管理员权限」，上面写着：
- 「为了做什么」：Agent 用大白话写的用途，排在最前面；
- 「要执行的命令」：完整的命令，一个字不少；
- 「会改动什么」：Agent 写的影响；
- 倒计时：卡片 2 分钟内有效。
看清楚以后，输入这台电脑的登录密码（管理员密码），点「同意并执行」；不想让它做，就点「拒绝」。
「为了做什么」写得太短，或者只是把命令抄一遍，卡片不会弹出来，Agent 得先把用途写清楚。管理 Agent J 自己的后台服务（启动、重启、停止）也不会弹这张卡：这些事不需要管理员密码，切换 AI 工具也一样，见 换 AI 编程工具。
- 密码在手机上加密，只有你的电脑、只有这一张卡片能解开。电脑用它运行一次 sudo，就把它清掉，不保存，也不写进任何日志。
- Agent 只拿到命令的输出和退出码，拿不到密码。
- 密码输错了，卡片会重新弹出，告诉你还能试几次。一张卡片最多试 3 次。连续输错 3 次，所有密码卡锁定 1 分钟；再错，锁定时间翻倍，最长 1 小时。
- 点「全部停下」，所有还开着的卡片立刻作废。Agent 那边的命令中途停了，密码卡也会自动撤回（密钥卡不会，见下）。
密钥卡
Agent 需要一个 API key 时，会运行：
agentj secret request --name ELEVENLABS_API_KEY --purpose '<用途>' --dest env:<文件>手机上弹出的卡片标题是「需要一个密钥」，写着「名称」「用途」「存到电脑上的位置」，以及「保存后的校验」怎么做。输入框里的字显示成星号。粘贴好以后点「保存到电脑」或按回车；没粘贴就点，卡片只会提示你先粘贴，不会当成拒绝。不想给就点下面单独一行的「不提供」，要连点两次。卡片 10 分钟内有效。
- 加密后的 key 直接写进你电脑上的文件，只有你的系统用户能读。存进
.env这类文件时，只改ELEVENLABS_API_KEY=这一行，文件里别的内容一个字节都不动。 - 保存以后可以马上验一下 key 能不能用：要么访问一个只读的 https 地址，要么运行一条只读命令（key 只放在这条命令的环境变量里）。卡片上写明了用哪种方式。
- 校验没通过、而且 key 比这家服务商常见的短很多时，手机会多提示一句：key 可能没复制完整。这时回服务商后台重新完整复制一次再贴。这个判断只看长度，不看 key 的内容。
- Agent 收到的回执只有：名称、存放位置、长度、指纹的前几位，以及校验有没有通过。它从来拿不到 key 本身，也被要求不去读、不打印那个文件。程序要用 key 时，直接从那个文件里读。
- Agent 那边的命令就算中途被打断（比如它的终端超时了），密钥卡也照样留在手机上，你提交后照常保存。Agent 之后运行
agentj secret result <卡片编号>就能看到结果。 - 每次批准、拒绝都记在电脑上的审计日志里，里面没有密码、没有 key，
agentj secret log可以复核。
密钥领取卡：把自己的密钥拿到手机上
反过来，你想从电脑上拿回自己的东西，比如代理的 SS 链接、带密码的配置文件，Agent 会运行：
agentj secret send --name 'Shadowrocket SS 链接' --value-from file:<文件>手机上弹出「Agent 发来一张密钥领取卡」，内容先遮住。点「用 Face ID 查看」，验证通过后电脑才把内容发过来，可以复制或下载。看完点「完成」就从页面清除；聊天记录里只留「已领取」和时间。10 分钟内能领一次，过期后电脑也会把它从内存里清掉。没设 Face ID 的手机领不了，卡片上有「设置 Face ID」按钮。这张卡只发给你自己已配对的手机；Telegram、群聊和好友那边照样拿不到这些密钥。
管理员小助手（可选）
每次都输密码嫌麻烦，可以装一个管理员小助手：
agentj sudo-helper install
agentj sudo-helper installagentj sudo-helper status
agentj sudo-helper statusagentj sudo-helper sync
agentj sudo-helper syncagentj sudo-helper uninstall
agentj sudo-helper uninstallinstall：装一次，需要在手机上通过一张普通的密码卡，输一次密码。- 装好以后，已配对的手机再收到管理员卡片，按钮变成「同意并执行（无需密码）」，不用再输密码。
- 小助手以管理员身份运行，执行之前自己核对三件事：这个同意是你那台手机签的名、时间是刚刚、这一次的编号没有用过。Agent 可以调用小助手，但它造不出你手机的签名，所以这不等于让 Agent 不用密码就能当管理员。小助手只执行卡片上那一条命令。
sync：配对了新手机或者解绑了旧手机以后运行，更新小助手认的手机名单（也要过一张密码卡）。解绑手机后名单不会自动更新，记得运行一次。status看装没装好，uninstall卸掉。
支持与限制
- 已配对手机可用通行密钥（如 Face ID）确认，再输入电脑密码；电脑本机的 Touch ID 是另一条授权路径。
- Windows 上还不能用。
- Mac 已在真机上用过：2026-10-08 多台客户 Mac 实际使用密码卡和密钥卡成功。开启 sudo 指纹 / Touch ID 的 Mac 仍可能在电脑本机再弹一次验证；请在电脑前关闭 sudo 的 Touch ID，保留密码认证，具体检查与处理见电脑不休眠。
- key 存进文件以后，Agent 和你用的是同一个系统用户，技术上它读得到那个文件。我们保证的是：key 不经过对话、日志、git，也不以明文经过手机和电脑之间的通道；Agent 被明确要求不去读、不打印它。
Some things the Agent can't do alone: installing system software needs the admin password, and hooking up a new service needs your API key. Until now that meant going back to the computer to type a sudo password in a terminal, or pasting the key into the chat — where it stayed in the history and went to the model vendor too.
Both now happen on the phone. The Agent asks, your phone shows a card, you type the password or paste the key into it, and it travels encrypted straight to your computer. The Agent only gets the result; it never sees the password or the key.
The admin password card
When the Agent needs to run a command as admin, it runs:
agentj sudo --why '<what it is for, in plain words>' --effect '<what it changes>' -- <command>A card titled "Admin rights needed" appears on your phone, showing:
- "What it's for": the purpose in plain words, as the Agent wrote it, shown first;
- "Command": the full command, nothing left out;
- "What it changes": as the Agent wrote it;
- a countdown: the card is valid for 2 minutes.
When you've read it, type this computer's login (admin) password and tap "Approve and run"; if you don't want it to happen, tap "Decline".
If "What it's for" is too short, or just repeats the command, the card is not shown at all: the Agent has to say what the command is for first. Managing Agent J's own background service (start, restart, stop) never shows this card either: it needs no admin password, and neither does switching AI tools — see Switch AI coding tool.
- The password is encrypted on the phone so that only your computer, and only for this one card, can open it. The computer uses it for a single sudo run and then wipes it; it's never stored and never written to any log.
- The Agent gets the command's output and exit code, never the password.
- If the password is wrong, the card comes back and tells you how many tries are left — three per card. Three wrong passwords in a row lock all password cards for a minute; each further miss doubles the lock, up to an hour.
- "Stop everything" voids every open card at once. If the Agent's command is interrupted, a password card is withdrawn as well (a key card is not — see below).
The key card
When the Agent needs an API key, it runs:
agentj secret request --name ELEVENLABS_API_KEY --purpose '<what it is for>' --dest env:<file>The card on your phone is titled "A key is needed" and shows "Name", "Purpose", "Saved on the computer at", and how the "Check after saving" works. What you paste shows as dots. Tap "Save to computer" (or Enter) when it's in; tapping it with nothing pasted only asks you to paste first, it never counts as a no. "Don't provide" sits on its own line below and needs a second tap. The card is valid for 10 minutes.
- The key is encrypted and written straight into a file on your computer that only your system user can read. In a
.env-style file only theELEVENLABS_API_KEY=line changes; every other byte of the file stays as it was. - Right after saving, the key can be tested: either by a read-only request to an https address, or by a read-only command that gets the key only in its environment. The card says which.
- When the check fails and the key is much shorter than this provider's keys usually are, the phone adds that it may not have been copied completely. Copy it again in full from the provider's dashboard and paste it. This looks at the length only, never at the key itself.
- The Agent's receipt holds only the name, where it was saved, its length, the first few characters of a fingerprint, and whether the check passed. It never gets the key itself and is told not to read or print that file; programs that need the key read it from the file directly.
- Even if the Agent's command is interrupted (say its terminal timed out), the key card stays on your phone and is saved when you submit. The Agent reads the outcome later with
agentj secret result <card-id>. - Every approval and refusal is recorded in an audit log on the computer, with no password and no key in it;
agentj secret loglets you check it.
The pickup card: your own secrets, on your phone
The other way round — you want back something of yours from the computer, like a proxy ss:// link or a config file with a password — the Agent runs:
agentj secret send --name 'Shadowrocket SS link' --value-from file:<file>Your phone shows "Your Agent sent a secret pickup card", contents hidden. Tap "View with Face ID"; only then does the computer send it, and you can copy or download it. Tap "Done" and it is cleared from the page; the chat keeps only "picked up" and the time. It can be picked up once within 10 minutes, then the computer wipes it from memory. A phone without Face ID can't open it (the card offers "Set up Face ID"). It goes only to your own paired phones; Telegram, groups and friends still can't get these secrets.
The admin helper (optional)
If typing the password each time gets old, install the admin helper:
agentj sudo-helper install
agentj sudo-helper installagentj sudo-helper status
agentj sudo-helper statusagentj sudo-helper sync
agentj sudo-helper syncagentj sudo-helper uninstall
agentj sudo-helper uninstallinstall: done once, through one ordinary password card on your phone.- After that, admin cards on your paired phones show "Approve and run (no password)" instead of asking for the password.
- The helper runs as admin and checks three things itself before running anything: the approval was signed by your phone, it was given just now, and its one-time number hasn't been used. The Agent can call the helper but can't forge your phone's signature, so this does not give the Agent password-free admin rights. The helper only ever runs the one command shown on the card.
sync: run it after pairing a new phone or removing one, so the helper's list of phones is current (it takes one password card too). Removing a phone doesn't update the list by itself, so remember to run it.statusshows whether it's installed;uninstallremoves it.
Support and limits
- A paired phone can confirm with a passkey (such as Face ID) before entering the computer password. Touch ID on the computer is a separate authorization path.
- It doesn't work on Windows.
- Macs have been used successfully on real hardware: password and secret cards worked on multiple customer Macs on 2026-10-08. A Mac with sudo fingerprint / Touch ID enabled may still show another authorization dialog on the computer. At the computer, disable sudo Touch ID while preserving password authentication; see Keep the computer awake for checks and recovery.
- Once a key is in a file, the Agent runs as the same system user as you, so technically it could read that file. What we guarantee is that the key never passes through the chat, logs or git, and never crosses the phone-to-computer channel in plain text; the Agent is explicitly told not to read or print it.
Our servers only pass along encrypted data and never see your password or key. More in Data security; everything else on the phone is in Using it on your phone.