5dive-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

5dive-cli

This skill teaches you to drive the

5dive

command on a 5dive runtime VM. You are running inside one such VM. You can spawn additional agents on the same host by shelling out to

sudo 5dive ...

and parsing the JSON envelope it emits when you pass

--json

本技能将教你在5dive运行时VM上使用

5dive

命令。你正运行在这样的VM中，你可以通过执行

sudo 5dive ...

并解析其添加

--json

参数后输出的JSON包，在同一主机上创建额外的Agent。

When to use this skill

何时使用本技能

Use it whenever the work in front of you would benefit from a second pair of hands — for example:

The user asks for a "worker", "sub-agent", "another agent", or "side task".
A long task could fan out into independent pieces (e.g. audit each route in parallel, run a different model on the same prompt, A/B two implementations).
You need to keep one agent on a hot context while a second one investigates something orthogonal.
The user wants to inspect / restart / pair / tear down an agent that already exists on the host.
You need a machine-readable health check of the host's coding-CLI stack.

If the user just wants you to do the work yourself, do not spawn an agent.

当你面前的工作需要额外的“帮手”时，就可以使用它——例如：

用户请求“worker”、“子Agent”、“另一个Agent”或“辅助任务”。
一项长任务可以拆分为独立的子任务并行处理（例如：并行审计每个路由、在同一提示词上运行不同模型、对两种实现进行A/B测试）。
你需要让一个Agent保持在热点上下文，同时让另一个Agent调查无关的内容。
用户想要检查/重启/配对/销毁主机上已存在的Agent。
你需要主机编码CLI栈的机器可读健康检查结果。

如果用户只是希望你自行完成工作，则无需创建Agent。

Mental model

心智模型

Everything the CLI does maps onto these resources on the host:

One agent = one Linux user (
```
agent-<name>
```
) + one systemd unit (
```
5dive-agent@<name>.service
```
) + one tmux session (
```
agent-<name>
```
) running the chosen CLI in a restart loop.
Auth is decoupled. You authenticate a type once; every agent of that type inherits the credentials via
```
EnvironmentFile
```
.
A channel (
```
telegram
```
/
```
discord
```
/
```
none
```
) is the inbound message surface. Channels are only supported by
```
claude
```
,
```
openclaw
```
,
```
hermes
```
.
The CLI is idempotent and safe to call from another agent — your agent user is in the
```
claude
```
group and has
```
sudo 5dive ...
```
whitelisted.

CLI的所有操作都对应主机上的以下资源：

一个Agent = 一个Linux用户（
```
agent-<name>
```
） + 一个systemd单元（
```
5dive-agent@<name>.service
```
） + 一个tmux会话（
```
agent-<name>
```
），会话中以重启循环的方式运行所选的CLI。
认证是解耦的。你只需对一种Agent类型进行一次认证；该类型的所有Agent都会通过
```
EnvironmentFile
```
继承凭证。
一个通道（
```
telegram
```
/
```
discord
```
/
```
none
```
）是入站消息界面。仅
```
claude
```
、
```
openclaw
```
、
```
hermes
```
支持通道功能。
CLI具有幂等性，可安全地从另一个Agent调用——你的Agent用户属于
```
claude
```
组，且拥有
```
sudo 5dive ...
```
的白名单权限。

Output contract — always pass

--json

输出约定——始终添加

--json

参数

Pass

--json

as a global flag (anywhere on the command line). Stdout becomes a stable envelope; progress lines stay on stderr.

bash

sudo 5dive agent create scout --type=claude --json

Success:

json

{ "ok": true, "data": { "name": "scout", "type": "claude", "created": true } }

Failure (exit code matches

error.code

json

{ "ok": false, "error": { "code": 6, "class": "auth_required", "message": "..." } }

Branch on
error.class
, not on the human message. Classes:

ok

usage

validation

not_found

conflict

auth_required

not_installed

not_running

pairing

permission

timeout

generic

See

references/exit-codes.md

for the full table.

添加

--json

作为全局标志（可放在命令行任意位置）。标准输出将变为稳定的JSON包；进度信息将输出到标准错误流。

bash

sudo 5dive agent create scout --type=claude --json

成功时输出：

json

{ "ok": true, "data": { "name": "scout", "type": "claude", "created": true } }

失败时输出（退出码与

error.code

匹配）：

json

{ "ok": false, "error": { "code": 6, "class": "auth_required", "message": "..." } }

根据
error.class
进行分支处理，而非人类可读消息。错误类别包括：

ok

usage

validation

not_found

conflict

auth_required

not_installed

not_running

pairing

permission

timeout

generic

。

完整列表请参考

references/exit-codes.md

。

Recipes

操作示例

Spawn a worker for a side task

为辅助任务创建worker

bash

undefined

bash

undefined

1. Pick a unique name (lowercase letters/digits/hyphens, ≤16 chars,

1. 选择一个唯一名称（仅包含小写字母/数字/连字符，长度≤16字符，必须以字母开头）。如果在意名称是否已存在，可先检查注册表：

must start with a letter). Check the registry first if you care:

—

sudo 5dive agent list --json | jq '.data.agents | keys'

2. Create the worker. --workdir scopes its tmux cwd; default is

2. 创建worker。--workdir指定其tmux会话的工作目录；默认是/home/claude/projects。

/home/claude/projects.

—

sudo 5dive agent create worker-1
--type=claude
--workdir=/home/claude/projects/myrepo
--json

3. Send it the task. tmux send-keys + Enter, so the text appears

3. 向其发送任务。tmux send-keys + Enter会将文本输入到worker正在运行的CLI提示符中。

in the worker's running CLI prompt.

—

sudo 5dive agent send worker-1
"audit the auth middleware for OWASP A01 issues; report back as a markdown bullet list"

sudo 5dive agent send worker-1
"审计认证中间件的OWASP A01问题；以Markdown项目符号列表形式返回报告"

4. Poll its output until it goes idle. --tmux dumps the scrollback.

4. 轮询其输出直到它进入空闲状态。--tmux参数会导出滚动缓冲区内容。

sudo 5dive agent logs worker-1 --tmux --lines=80

5. Tear it down when you're done — frees the systemd unit + Linux user.

5. 完成任务后销毁它——释放systemd单元和Linux用户。

sudo 5dive agent rm worker-1 --json

undefined

sudo 5dive agent rm worker-1 --json

undefined

Skill inheritance on agent-spawned children

Agent创建的子Agent的技能继承

When an agent (you,

SUDO_USER=agent-*

) creates another claude-typed agent, the CLI auto-installs the

5dive-cli

skill into the child so it inherits inter-agent comms knowledge. Humans creating from the dashboard don't get this default. Override either way:

--with-skills=<spec>[,<spec>...]

— explicit list. Each spec is a bare id (defaults to

5dive-com/skills

) or

<owner/repo>:<id>

. Example:

--with-skills=5dive-cli,acme/skills:db-tools

```
--no-skills
```
— opt out, even when called from another agent.

当一个Agent（即你，

SUDO_USER=agent-*

）创建另一个claude类型的Agent时，CLI会自动将

5dive-cli

技能安装到子Agent中，使其继承跨Agent通信的知识。通过仪表板创建Agent的人类用户不会获得此默认设置。你可以通过以下方式覆盖默认行为：

--with-skills=<spec>[,<spec>...]

—— 显式指定技能列表。每个spec可以是纯ID（默认来自

5dive-com/skills

）或

<owner/repo>:<id>

格式。示例：

--with-skills=5dive-cli,acme/skills:db-tools

。

```
--no-skills
```
—— 选择不继承技能，即使是从另一个Agent调用创建。

Create-then-auth:

--defer-auth

创建后认证：

--defer-auth

Use when you want the agent registered before its credentials are wired up (e.g. the agent's own first-run UI will handle sign-in). Skips the auth gate on

agent create

; combine with

--auth-profile=<name>

to bind a profile slot that doesn't yet have a

combined.env

bash

sudo 5dive agent create draft-bot --type=claude --defer-auth --json

当你希望先注册Agent，再配置其凭证时使用（例如：Agent的首次运行UI将处理登录）。此参数会跳过

agent create

时的认证检查；可与

--auth-profile=<name>

结合使用，绑定一个尚未配置

combined.env

的配置文件槽位。

bash

sudo 5dive agent create draft-bot --type=claude --defer-auth --json

Fan out: same prompt, three different models

任务分发：同一提示词，三种不同模型

Useful for "let me see how Codex/Gemini/Claude each approach this".

bash

for type in claude codex gemini; do
  sudo 5dive agent create "fan-${type}" --type="${type}" --json
  sudo 5dive agent send "fan-${type}" "$PROMPT"
done

适用于“让我看看Codex/Gemini/Claude分别如何处理这个任务”的场景。

bash

for type in claude codex gemini; do
  sudo 5dive agent create "fan-${type}" --type="${type}" --json
  sudo 5dive agent send "fan-${type}" "$PROMPT"
done

Wait, then collect the last 200 lines of each:

等待任务完成，然后收集每个Agent的最后200行输出：

for type in claude codex gemini; do echo "=== ${type} ===" sudo 5dive agent logs "fan-${type}" --tmux --lines=200 done

Cleanup.

清理资源。

for type in claude codex gemini; do sudo 5dive agent rm "fan-${type}" --json done

undefined

for type in claude codex gemini; do sudo 5dive agent rm "fan-${type}" --json done

undefined

Recover from

auth_required

从

auth_required

错误中恢复

bash

undefined

bash

undefined

If create fails with error.class=auth_required, the type isn't authenticated.

如果创建Agent时出现error.class=auth_required错误，说明该类型尚未完成认证。

Two paths — pick by what credentials you have:

有两种解决路径——根据你拥有的凭证选择：

A) Static API key in $KEY (preferred for automation)

A) 使用$KEY中的静态API密钥（自动化场景首选）

echo "$KEY" | sudo 5dive agent auth set claude --api-key=- --json

B) Device-code flow (when only a human can complete login)

B) 设备码流程（仅当需要人类完成登录时使用）

sudo 5dive agent auth start claude --json

-> session id; give the URL from

auth poll

to the user; they paste the

-> 返回会话ID；将

auth poll

输出的URL提供给用户；用户通过

auth submit

粘贴回调代码。

callback code back via

auth submit

—


Never call `5dive agent auth login <type>` from your own process — it
hands the TTY off to the upstream CLI's interactive flow and hangs your
agent. Use `auth start` / `auth set` instead.


切勿在你自己的进程中调用`5dive agent auth login <type>`——该命令会将TTY控制权转移给上游CLI的交互式流程，导致你的Agent挂起。请改用`auth start` / `auth set`。

Multi-account: the

account

noun

多账户：

account

名词

A 5dive account is a named auth profile — one bag of credentials that any number of agents can share via

--auth-profile=<name>

. Use it when the host has more than one human / billing identity (e.g. work + personal Anthropic sign-ins) and different agents should use different ones.

5dive account ...

is the user-facing surface; the lower-level

agent auth start|poll|submit|cancel

verbs are still what the dashboard's device-code flow uses, and what you should use from a script.

bash

undefined

5dive的账户是一个命名的认证配置文件——一组凭证，可通过

--auth-profile=<name>

被任意数量的Agent共享。当主机拥有多个用户/计费身份（例如：工作和个人Anthropic登录），且不同Agent需要使用不同身份时，可使用此功能。

5dive account ...

是面向用户的操作接口；底层的

agent auth start|poll|submit|cancel

命令仍是仪表板设备码流程使用的接口，也是你在脚本中应使用的接口。

bash

undefined

Inventory: which named accounts exist, what types each is signed into,

查看清单：已存在哪些命名账户，每个账户已登录的类型，以及有多少Agent绑定到该账户。

and how many agents are bound to each.

—

sudo 5dive account list --json

Detail for one account, including which env keys are populated.

查看单个账户的详细信息，包括已填充的环境变量键。

sudo 5dive account show acme-prod --json

Provision a new empty account, then sign it in (TTY-only — humans).

创建一个新的空账户，然后登录（仅支持TTY交互——供人类用户使用）。

sudo 5dive account add acme-prod sudo 5dive account login acme-prod --type=claude

Rebind an existing agent to a different account. Restarts the agent so

将现有Agent重新绑定到另一个账户。这会重启Agent，使新的EnvironmentFile生效。

the new EnvironmentFile takes effect.

—

sudo 5dive agent set-account worker-1 acme-prod --json sudo 5dive agent set-account worker-1 default --json # clears the override

sudo 5dive agent set-account worker-1 acme-prod --json sudo 5dive agent set-account worker-1 default --json # 清除覆盖设置，恢复默认

Rename / remove.

remove

refuses while any agents are still bound.

重命名/删除账户。当仍有Agent绑定到该账户时，

remove

命令会执行失败。

sudo 5dive account rename acme-prod acme-staging --json sudo 5dive account remove acme-staging --json


The reserved name `default` is rejected by `account add` / `rename` — at the
agent level, `auth-profile=default` already means "no override, use the shared
`/etc/5dive/connectors/<type>.env`".

sudo 5dive account rename acme-prod acme-staging --json sudo 5dive account remove acme-staging --json


保留名称`default`无法用于`account add` / `rename`命令——在Agent层面，`auth-profile=default`已表示“不使用覆盖设置，使用共享的`/etc/5dive/connectors/<type>.env`”。

Pair a Telegram channel without a bot reply

无需机器人回复即可配对Telegram通道

agent pair

accepts three input shapes:

bash

undefined

agent pair

支持三种输入形式：

bash

undefined

A) Classic — return a pairing code, user DMs the bot, paste the bot reply.

A) 经典方式——返回配对码，用户向机器人发送私信，然后粘贴机器人的回复。

sudo 5dive agent pair worker-1 --json sudo 5dive agent pair worker-1 --code=AB12CD --json

B) Auto-detect — long-poll Telegram for the next inbound message and

B) 自动检测——长轮询Telegram的下一条入站消息，并从第一个向机器人发送私信的用户那里生成access.json。适用于用户已打开机器人的引导流程。

seed access.json from whoever DMs the bot first. Useful in onboarding

—

flows where the user has the bot open already.

—

sudo 5dive agent telegram-discover --token="$BOT_TOKEN" --poll-secs=60 --json

-> {found:true, userId, chatId, ...}; re-poll on {found:false}.

-> {found:true, userId, chatId, ...}; 当返回{found:false}时重新轮询。

sudo 5dive agent pair worker-1 --user-id=<userId> --chat-id=<chatId> --json

C) Bot identity for deep links — fast getMe lookup so the dashboard can

C) 用于深度链接的机器人身份——快速执行getMe查询，以便仪表板在“发送/start”提示旁渲染可点击的t.me/<bot>链接。

render a tappable t.me/<bot> link alongside the "send /start" prompt.

—

sudo 5dive agent telegram-getme --token="$BOT_TOKEN" --json

-> {ok:true, data:{botId, username, firstName}}


`telegram-discover` and `telegram-getme` are read-only (no registry mutation,
no audit log) and do not require a bound agent.


`telegram-discover`和`telegram-getme`是只读操作（不会修改注册表，不会生成审计日志），且不需要绑定Agent。

Talking to other agents (inter-agent comms)

与其他Agent通信（跨Agent通信）

agent send

and

agent ask

work as a tiny message bus between agents on the same host. There is no separate channel — messages land in the receiver's running CLI as if a human had typed them.

agent send

和

agent ask

可作为同一主机上Agent之间的小型消息总线。不需要单独的通道——消息会直接进入接收方正在运行的CLI，就像人类输入的一样。

Sending: attribution is automatic

发送：自动添加来源标识

When you (an agent) shell out to

sudo 5dive agent send <name> "..."

, the CLI sees that

$SUDO_USER

agent-<you>

and wraps the payload as:

[5dive-msg from=<you> id=<8-hex>] <your text>

so the receiver can tell it's being pinged by a peer agent and which one. Override the inferred name with

--from=<label>

. Skip wrapping with

--raw

(useful when you're piping a prompt that already has its own structure).

Humans running

sudo 5dive agent send

directly never get auto-wrapped — only sends from

agent-*

users do.

当你（一个Agent）执行

sudo 5dive agent send <name> "..."

时，CLI会检测到

$SUDO_USER

是

agent-<you>

，并将消息内容包装为：

[5dive-msg from=<you> id=<8位十六进制>] <你的文本>

这样接收方就能识别出这是来自对等Agent的消息，以及具体是哪个Agent。你可以使用

--from=<label>

覆盖自动推断的名称。使用

--raw

参数可跳过包装（当你传递的提示词已有自己的结构时非常有用）。

直接执行

sudo 5dive agent send

的人类用户不会获得自动包装——仅当发送者是

agent-*

用户时才会自动包装。

Receiving: recognise the envelope and reply by name

接收：识别消息包并按名称回复

When a line like

[5dive-msg from=scout id=ab12cd34] please summarise the auth middleware audit

appears as your input, treat it as an inter-agent request. To reply, send back to the named sender:

bash

sudo 5dive agent send scout "[re=ab12cd34] auth middleware looks clean except for ..."

The

[re=<id>]

prefix is convention, not enforced — it lets the original sender match your reply to their question when they're juggling several at once. Drop it for casual back-and-forth.

当出现如下格式的输入行时：

[5dive-msg from=scout id=ab12cd34] 请总结认证中间件的审计结果

将其视为跨Agent请求。如需回复，发送消息给指定的发送者即可：

bash

sudo 5dive agent send scout "[re=ab12cd34] 认证中间件整体无问题，除了..."

[re=<id>]

前缀是约定俗成的，并非强制要求——它能让原始发送者在处理多个请求时，将你的回复与对应的问题匹配起来。在非正式的来回通信中可以省略该前缀。

One-shot synchronous calls:

agent ask

一次性同步调用：

agent ask

If you want a request/response in one CLI call (no manual polling of

agent logs

), use

ask

bash

sudo 5dive agent ask scout \
  "list the OWASP A01 issues you found, one per line" \
  --timeout=180 --json

It sends the wrapped envelope, then watches

tmux capture-pane

after the marker line and returns once the scrollback has been quiet for

--idle-secs

(default 5s). Stdout (text mode) is just the reply body; in

--json

mode the envelope is

{ok:true, data:{name, from, msg_id, reply}}

Caveats — read these before leaning on

ask

Idle-by-stability is heuristic. A receiver that streams progress continuously will keep
```
ask
```
awake until
```
--timeout
```
fires. If you're asking for something the receiver might narrate (long agentic work), prompt it for a terse final summary or use plain
```
send
```
+
```
logs
```
.
The reply is whatever was on screen. It includes any chrome the receiver CLI prints (cursor lines, status hints) — don't expect a clean JSON body unless the prompt asks for one.
No retries, no delivery confirmation. If the receiver crashed mid- reply you'll get a partial slice or a timeout, nothing in between.

如果你希望通过一次CLI调用完成请求/响应（无需手动轮询

agent logs

），可使用

ask

命令：

bash

sudo 5dive agent ask scout \
  "列出你发现的OWASP A01问题，每行一个" \
  --timeout=180 --json

该命令会发送包装后的消息包，然后在标记行之后监控

tmux capture-pane

的输出，当滚动缓冲区静默时间达到

--idle-secs

（默认5秒）时返回结果。文本模式下标准输出仅包含回复内容；

--json

模式下输出的包格式为

{ok:true, data:{name, from, msg_id, reply}}

。

注意事项——在依赖

ask

命令之前请阅读以下内容：

基于稳定性判断空闲状态是启发式的。如果接收方持续输出进度信息，
```
ask
```
会一直等待直到
```
--timeout
```
超时。如果你请求的内容可能会让接收方逐步输出（例如长耗时的智能任务），请提示其返回简洁的最终总结，或使用普通的
```
send
```
+
```
logs
```
组合。
回复内容就是屏幕上显示的内容。它包含接收方CLI输出的任何装饰信息（光标行、状态提示）——除非提示词明确要求，否则不要期望得到干净的JSON内容。
无重试，无送达确认。如果接收方在回复过程中崩溃，你会得到部分内容或超时错误，不会有中间状态的提示。

Rules of thumb

经验法则

For "fire-and-forget delegate, I'll check later":
```
agent send
```
+ poll
```
agent logs --tmux
```
when it suits you.
For "I need an answer to continue":
```
agent ask
```
.
For broadcast / fan-out across N agents: loop
```
agent send
```
(or
```
agent ask
```
in parallel via
```
&
```
+
```
wait
```
). Each call is independent.
Don't reuse
```
--from
```
labels for unrelated agents — pick a label that names you, so receivers can address replies correctly.

对于“触发即遗忘的委托任务，稍后再检查结果”：使用
```
agent send
```
+ 在合适的时候轮询
```
agent logs --tmux
```
。
对于“我需要一个答案才能继续”：使用
```
agent ask
```
。
对于向N个Agent进行广播/任务分发：循环执行
```
agent send
```
（或通过
```
&
```
+
```
wait
```
并行执行
```
agent ask
```
）。每个调用都是独立的。
不要为无关的Agent重复使用
```
--from
```
标签——选择一个能标识你自己的标签，以便接收方能正确回复。

Diagnose a sick host

诊断故障主机

bash

sudo 5dive doctor --json

Envelope is always

{ ok: true, data: { summary, checks } }

with exit 0. Branch on

data.summary.errors > 0

. Add

--repair

to attempt reversible fixes (apt installs, type installer recipes, registry reseed).

bash

sudo 5dive doctor --json

输出包始终为

{ ok: true, data: { summary, checks } }

，退出码为0。根据

data.summary.errors > 0

进行分支处理。添加

--repair

参数可尝试可逆修复操作（如apt安装、类型安装脚本、注册表重新生成）。

Rules of engagement

操作规则

Always pass
--json
. Parse the envelope. Don't grep stderr.
One name = one agent. Names are lowercase letters/digits/hyphens, start with a letter, max 16 chars. Reuse a name only after
```
agent rm
```
.
Don't share bot tokens. Two Telegram-channel agents on the same bot will race each other on
```
getUpdates
```
. Each agent needs its own.
Tear down what you spin up. A leaked
```
worker-N
```
agent stays running across reboots — it's a real systemd unit, not a thread. On task completion call
```
5dive agent rm <name>
```
.
Don't shell out to the underlying CLI binaries directly. Going around
```
5dive
```
skips the systemd unit, the audit log, and the env injection — the agent will run with broken auth and no restart loop.
Read
5dive --help
if a flag is rejected as unknown — the binary on the host may be newer or older than this skill. The help output is authoritative.
The
auth login <type>
path is interactive only. Never call it from your own session.

始终添加
--json
参数。解析JSON包，不要通过grep标准错误流获取信息。
一个名称对应一个Agent。名称仅包含小写字母/数字/连字符，以字母开头，最大长度16字符。只有在执行
```
agent rm
```
后才能复用名称。
不要共享机器人令牌。同一机器人上的两个Telegram通道Agent会在
```
getUpdates
```
时产生竞争。每个Agent需要独立的令牌。
销毁你创建的资源。泄露的
```
worker-N
```
Agent会在重启后继续运行——它是真实的systemd单元，而非线程。任务完成后请调用
```
5dive agent rm <name>
```
。
不要直接调用底层CLI二进制文件。绕过
```
5dive
```
会跳过systemd单元、审计日志和环境变量注入——Agent将在认证失效且无重启循环的状态下运行。
如果某个标志被判定为未知，请阅读
5dive --help
。主机上的二进制文件可能比本技能描述的版本更新或更旧。帮助输出是权威的。
auth login <type>
路径仅支持交互式操作。切勿在你自己的会话中调用该命令。

Reference

参考资料

```
references/commands.md
```
— every subcommand and flag, copy/pasteable.
```
references/exit-codes.md
```
— exit codes & error classes.
```
references/paths.md
```
— on-disk state layout (only for debugging).

```
references/commands.md
```
—— 所有子命令和标志，可直接复制粘贴使用。
```
references/exit-codes.md
```
—— 退出码和错误类别。
```
references/paths.md
```
—— 磁盘上的状态布局（仅用于调试）。

Going further

延伸阅读

The full reference manual lives at https://5dive.com/docs. If a flag in this skill conflicts with what the running binary accepts, trust the binary — run

sudo 5dive --help

sudo 5dive agent <sub> --help

directly and follow that.

完整的参考手册请访问https://5dive.com/docs。如果本技能中描述的标志与运行中的二进制文件接受的标志冲突，请以二进制文件为准——直接运行

sudo 5dive --help

或

sudo 5dive agent <sub> --help

并遵循其说明。

5dive-cli

Original

Translation

5dive-cli

5dive-cli

When to use this skill

何时使用本技能

Mental model

心智模型

Output contract — always pass --json

输出约定——始终添加--json参数

Recipes

操作示例

Spawn a worker for a side task

为辅助任务创建worker

1. Pick a unique name (lowercase letters/digits/hyphens, ≤16 chars,

1. 选择一个唯一名称（仅包含小写字母/数字/连字符，长度≤16字符，必须以字母开头）。如果在意名称是否已存在，可先检查注册表：

must start with a letter). Check the registry first if you care:

2. Create the worker. --workdir scopes its tmux cwd; default is

2. 创建worker。--workdir指定其tmux会话的工作目录；默认是/home/claude/projects。

/home/claude/projects.

3. Send it the task. tmux send-keys + Enter, so the text appears

3. 向其发送任务。tmux send-keys + Enter会将文本输入到worker正在运行的CLI提示符中。

in the worker's running CLI prompt.

4. Poll its output until it goes idle. --tmux dumps the scrollback.

4. 轮询其输出直到它进入空闲状态。--tmux参数会导出滚动缓冲区内容。

5. Tear it down when you're done — frees the systemd unit + Linux user.

5. 完成任务后销毁它——释放systemd单元和Linux用户。

Skill inheritance on agent-spawned children

Agent创建的子Agent的技能继承

Create-then-auth: --defer-auth

创建后认证：--defer-auth

Fan out: same prompt, three different models

任务分发：同一提示词，三种不同模型

Wait, then collect the last 200 lines of each:

等待任务完成，然后收集每个Agent的最后200行输出：

Cleanup.

清理资源。

Recover from auth_required

从auth_required错误中恢复

If create fails with error.class=auth_required, the type isn't authenticated.

如果创建Agent时出现error.class=auth_required错误，说明该类型尚未完成认证。

Two paths — pick by what credentials you have:

有两种解决路径——根据你拥有的凭证选择：

A) Static API key in $KEY (preferred for automation)

A) 使用$KEY中的静态API密钥（自动化场景首选）

B) Device-code flow (when only a human can complete login)

B) 设备码流程（仅当需要人类完成登录时使用）

-> session id; give the URL from auth poll to the user; they paste the

-> 返回会话ID；将auth poll输出的URL提供给用户；用户通过auth submit粘贴回调代码。

callback code back via auth submit.

Multi-account: the account noun

多账户：account名词

Inventory: which named accounts exist, what types each is signed into,

查看清单：已存在哪些命名账户，每个账户已登录的类型，以及有多少Agent绑定到该账户。

and how many agents are bound to each.

Detail for one account, including which env keys are populated.

查看单个账户的详细信息，包括已填充的环境变量键。

Provision a new empty account, then sign it in (TTY-only — humans).

创建一个新的空账户，然后登录（仅支持TTY交互——供人类用户使用）。

Rebind an existing agent to a different account. Restarts the agent so

将现有Agent重新绑定到另一个账户。这会重启Agent，使新的EnvironmentFile生效。

the new EnvironmentFile takes effect.

Rename / remove. remove refuses while any agents are still bound.

重命名/删除账户。当仍有Agent绑定到该账户时，remove命令会执行失败。

Pair a Telegram channel without a bot reply

无需机器人回复即可配对Telegram通道

A) Classic — return a pairing code, user DMs the bot, paste the bot reply.

A) 经典方式——返回配对码，用户向机器人发送私信，然后粘贴机器人的回复。

B) Auto-detect — long-poll Telegram for the next inbound message and

B) 自动检测——长轮询Telegram的下一条入站消息，并从第一个向机器人发送私信的用户那里生成access.json。适用于用户已打开机器人的引导流程。

seed access.json from whoever DMs the bot first. Useful in onboarding

flows where the user has the bot open already.

-> {found:true, userId, chatId, ...}; re-poll on {found:false}.

-> {found:true, userId, chatId, ...}; 当返回{found:false}时重新轮询。

C) Bot identity for deep links — fast getMe lookup so the dashboard can

C) 用于深度链接的机器人身份——快速执行getMe查询，以便仪表板在“发送/start”提示旁渲染可点击的t.me/<bot>链接。

render a tappable t.me/<bot> link alongside the "send /start" prompt.

-> {ok:true, data:{botId, username, firstName}}

-> {ok:true, data:{botId, username, firstName}}

Output contract — always pass
`--json`

输出约定——始终添加
`--json`
参数

Create-then-auth:
`--defer-auth`

创建后认证：
`--defer-auth`

Recover from
`auth_required`

从
`auth_required`
错误中恢复

-> session id; give the URL from
`auth poll`
to the user; they paste the

-> 返回会话ID；将
`auth poll`
输出的URL提供给用户；用户通过
`auth submit`
粘贴回调代码。

callback code back via
`auth submit`
.

Multi-account: the
`account`
noun

多账户：
`account`
名词

Rename / remove.
`remove`
refuses while any agents are still bound.

重命名/删除账户。当仍有Agent绑定到该账户时，
`remove`
命令会执行失败。

One-shot synchronous calls:
`agent ask`

一次性同步调用：
`agent ask`