# 使用与配置

派发、收结果和对话的示例见 [agent 使用说明](../src/guide.md)。所有命令支持全局选项 `--json`；各命令的参数见 `axiopera <命令> --help`。

## 任务与工作目录

子 agent 在调用方的工作目录中运行，可用 `--cwd` 另行指定。Axiopera 不为任务建立独立的工作副本：同时修改同一仓库的任务，由主 agent 各建一个 Git worktree，再用 `--cwd` 指定。

主 agent 负责检查子 agent 的改动、提交和合并分支。子 agent 的权限由 `--tier` 指定，默认 `work`。各档位在不同 backend 上的具体行为见[权限](backends.md#权限)。

空闲后用 `axiopera send <task> --tier full "继续执行"` 在原会话中改档续接。子 agent 只能修改自己直接派发的任务；降低父任务档位前，先降低超出新档位的子任务档位。

任务 ID 全局唯一，`--name` 指定的别名在同一个调用方下唯一。主 agent 为第 0 层，最多派发到第 2 层，只统计 Axiopera 任务。宿主内置子 agent 归属于所在的 Axiopera 任务，它再派发的任务继续受该任务树的深度和权限限制。子任务的档位不能高于父任务。内置子 agent 的收件隔离见[后端文档](backends.md#会话与消息)。

子 agent 用 `ask` 提问后可以继续工作。若这一轮结束时仍有未回答的问题，任务进入 `waiting`；回答送入所属任务的主会话，在执行中插入或在空闲时开启下一轮。原生子会话的提问也按所属任务路由，可用 `answers` 查询回答。兄弟任务通过 `tell` 留言，父节点收到抄送。接收方空闲时，留言等到下一轮开始才送入，不会单独开启一轮。

`spawn`、`send`、`reply` 接受位置参数、`-f FILE` 或单独的 `-`。后两种分别读取 UTF-8 文件和标准输入，保留原始换行。三种来源只能选一种，内容不能为空。

## 结果与接管

`wait` 阻塞到有新消息，列出后退出，不取走任何内容；`inbox` 取走消息，从不阻塞。`watch` 每有新消息就输出一行摘要，一直运行到被停止，同样不取走；子 agent 的 `watch` 在子任务都结束、消息都取走 1 分钟后自行退出。每轮结果经 `inbox`、`result` 或宿主推送交付后，再次 `result` 只返回文件路径。需要重新查看正文时用 `result <task> --turn N --force`。

`watch --status` 跟踪调用方正在执行和排队的任务，每 2 秒检查一次，输出有变化的状态和进度，包括监听期间新增的任务及已跟踪任务的结束状态。没有执行或排队的任务时以退出码 0 结束，未收取的消息不影响退出。停止监听不会取消任务。Codex 的后台显示见[宿主通知](backends.md#宿主通知)。

回复长度有上限。等你裁决的审批请求总是先给，其余消息按先后取，一次回复放不下的整条留到下一次 `inbox`，回复末尾注明还剩几条。单条结果超长时只保留末尾，并注明显示的字符数、总字符数和完整文件路径；过长的提问、留言和审批请求给开头和结尾，并注明全文路径。`status` 查看任务状态和所用模型、推理强度，运行中的任务附带进度：第几轮、本轮已用时间、工具调用次数，以及最近一次调用和距今时间；一轮结束后进程仍在等后台工作时，注明上一轮结束了多久；没有新消息时，`inbox` 和 `wait` 超时也列出这些进度。`inbox` 和推送交付的每轮结果、`log` 中的轮次结束行同样注明该轮结束时的模型和推理强度，`top` 在任务详情的标题中显示，窗口放不下任务状态时先省去。会话启动、子 agent 报告之前，显示的是请求值（`--model`、`--effort` 或配置），未指定则不显示。`log` 查看事件摘要，每个事件一行，包括子 agent 每段话的开头，换行显示为 `↵`，命令等自由文本截到 200 个字符并注明省略了多少。加上 `--json` 可以读取完整任务字段和事件字段，包括改动文件列表及后端上报的用量。

`detach <task>` 将任务交给人接管，并打印工作目录和原生 resume 命令。接管前要等任务执行及后台工作结束，或先 `cancel`。Axiopera 发现原生会话文件被其他进程修改时，也会将任务标为 detached。

`cancel` 停止任务及其子任务当前的执行，保留会话和未交付输入。`cancelled`、`failed` 和 `interrupted` 任务都可以用 `send` 继续，回答未解决的问题也会续接任务。继续父任务不会自动启动已取消的子任务，需要分别续接。脱管的任务通过原生 CLI 接管。

退出码见 [guide](../src/guide.md)。带消息的输出总以 0 退出：宿主对非零退出的输出截得更短，Windows 上的 Codex 还把所有非零退出码报成 1。

## 人工查看

在另一个终端运行 `axiopera top`，每秒刷新，每个任务固定一行，子任务缩进在上级下面。会话组按最近一次派发任务（含子任务）的时间从新到旧排列，组内顶层任务和同级子任务也从新到旧，子任务紧跟父任务；状态变化和新输出不触发重排。默认列表与 `--all` 使用相同顺序，停在首条任务时跟随新任务；向下选阅后保留当前选中项及其屏幕位置（列表边界处会调整），向上回到首条任务或按 Home 恢复跟随。任务按会话分组，单会话也显示组名，选到会话首条任务时带出组名。组名前列出这组任务所在的项目，即工作目录所在 Git 仓库的目录名，worktree 算作它的主仓库，不在仓库里的用工作目录名；终端派发的任务归在 `user` 下，识别不到会话的 agent 也会落在这里（见[指定调用方](#指定调用方)）。每行依次是名称、ID、状态和子 agent 最近说的一段话，没有名称的任务在名称处显示 ID；agent 调用命令时用的是 ID，可以据此对上任务。说的话合成一行显示，之后提出的未回答提问优先显示，事件里已没有它说的话时显示最近一轮结果的第一行。状态 `approval` 表示有待裁决的审批，`stalled` 表示运行中长时间没有动静。颜色只用于状态和话里的 markdown 格式，格式同详情。默认只列出未停止或 1 小时内有变化的任务，`--all` 列出全部。窗口放不下时显示连续的一段，随选择滚动，底部注明可见行的位置。

上下方向键或 `j`、`k` 选择任务，选中的行反色显示，到达窗口边缘时滚动。PageUp／PageDown 按一屏移动，Home／End 到首末任务；回车或右方向键在同一个终端打开它的详情，Esc、`q`、左方向键或退格返回列表。在列表中按 `q` 退出，Ctrl-C 随时退出。详情中，上下方向键或 `j`、`k` 按行滚动，PageUp／PageDown 按屏翻页，Home 到开头，End 到末尾。默认跟随最新输出；向上翻后停在阅读位置，底部显示 `paused`，回到末尾后恢复 `live` 跟随。审批和回答仍用命令完成，`top` 里不能操作。标准输入不是终端时，例如没有 ConPTY 的 mintty，`top` 不响应按键，只能用 Ctrl-C 退出；列表放不下时优先显示待处理、运行中、出错的任务，同级优先显示新任务，连同上级一起显示。

`axiopera top <task>` 直接打开一个任务的详情，`<task>` 是 ID，没有重名时也可以用名称，返回后是列表。详情第一行是名称、ID、agent、状态和本轮进展；下面列出等你处理的事，`needs` 待裁决的审批，`asks` 未回答的提问，停下的任务列出错误 `error` 或停止原因 `why`。再往下是对话，排版参照 Codex：派发时的任务文本以 `›` 开头，首轮开始前追加的消息并在其中，之后发给子 agent 的消息同样以 `›` 开头；子 agent 说的每段话以 `•` 开头，段与段之间空一行，最新的在最下面；从第二轮起，每轮开头有一行分隔，注明轮次和距今多久，下面是开启这一轮的消息。消息由 daemon 完整保存；0.2.2 及更早的 daemon 不保存消息，那时的轮次只有分隔行。每轮最后一段话就是这轮的结果，完整取自结果文件，结果为空时保留原话；没有发言记录的旧任务也显示最近一轮结果。其他段落是 daemon 记录的，每段只记前 500 个字符，超出的部分截去，末尾标 `…`。话里的 markdown 不显示标记，用格式表示：粗体、斜体、标题、列表、引用、代码块和行内代码；表格按列对齐，放不下时照原样折行。链接显示文字，网址和与文字不同的文件路径在后面括号注明。工具调用挂在前一段话下面，每次一行。daemon 每次只记前 400 个字符；一行按窗口宽度截断，两种截断末尾都标 `…`。常见工具名统一成动词，命令都显示为 `Run` 加命令，Codex 在外面包的 PowerShell 调用已去掉。链接和工具调用里，任务目录下的路径写成相对路径。子任务不在详情里，在列表中看。详情可翻阅当前保留的最近 300 条消息、工具调用和轮次记录，以及任务文本；标题和待处理事项固定，只有对话滚动；待处理事项超过半屏时，放不下的排在对话前面一起滚动，固定部分末尾注明还有几项。不能读取按键的终端保留最新几段，超屏时注明省略内容。输出不是终端时只打印一屏，其中任务文本完整，只取最近 20 段话和其间的工具调用。

`top` 只读取数据目录，不连接 daemon：不会启动 daemon，不取走消息，不标记结果已交付，也不写请求日志。daemon 异常退出后，任务停留在退出前的状态，下次启动时才改为 interrupted。

其他命令中，`status --all` 和 `log` 同样不改变交付状态。`result` 会把该轮标为已交付，主 agent 之后只拿到文件路径。`inbox` 取走调用方的消息：在 Claude Code、Codex、Grok 的命令工具或它们启动的 shell 中，调用方是该会话；在独立终端中是 `user`，即你本人。识别不到会话的 agent 要用 `--caller` 指明会话，见[指定调用方](#指定调用方)。

## 指定调用方

调用方身份决定任务名称的作用范围、`status` 列出的任务和 `inbox` 取走的消息。Axiopera 从 Claude Code、Codex、Grok 注入命令环境的会话变量识别调用方，经 ssh、`docker exec`、WSL 等调用另一处的 Axiopera 时，这些变量通常传不过去，agent 会被当成终端前的你（`user`）：与终端共用收件箱，审批时也像你一样不必先读全文。这时用全局选项 `--caller <名称>:<会话 ID>` 指明会话，每条命令带同一个值，变量在宿主一侧展开：

```sh
ssh 主机 axiopera --caller "claude:$CLAUDE_CODE_SESSION_ID" spawn codex --cwd /srv/app - < task.md
ssh 主机 axiopera --caller "claude:$CLAUDE_CODE_SESSION_ID" wait    # 后台运行
ssh 主机 axiopera --caller "claude:$CLAUDE_CODE_SESSION_ID" inbox
```

三家的会话 ID 分别在 `CLAUDE_CODE_SESSION_ID`、`CODEX_THREAD_ID`、`GROK_SESSION_ID` 中。`--caller claude:<ID>` 与在命令前设置 `CLAUDE_CODE_SESSION_ID=<ID>` 是同一个调用方，此前这样派发的任务可以接着操作。其他 agent 同样要用自己的名称和会话 ID 指明会话，没有会话 ID 时生成一个随机值并一直沿用。取值规则及子 agent 中的限制见[身份与 IPC](design.md#身份与-ipc)。

Axiopera 不负责连接、认证和文件同步。`--cwd`、`-f` 和结果中的路径都按运行 Axiopera 的一侧解释。Windows 的 Git Bash 会把传给 `wsl.exe` 等原生程序、以 `/` 开头的参数改写成 Windows 路径，这时设置 `MSYS_NO_PATHCONV=1`。子 agent 使用该侧调用命令的环境，非交互 ssh 的 PATH 可能找不到 agent CLI，这时在[配置](#配置)中指定 `path`。ssh 断开后 daemon 和任务继续运行，前提是系统不在登出时结束用户进程，例如 systemd-logind 未启用 `KillUserProcesses`。跨机器时各宿主怎样收到结果，见[宿主通知](backends.md#宿主通知)。

## 配置

数据目录默认为 `~/.axiopera/`，环境变量 `AXIOPERA_HOME` 可以覆盖它。配置文件是该目录下的 `config.toml`，所有字段均可省略。以下三项是默认值：

```toml
concurrency = 50
stall_minutes = 10
approval_timeout_minutes = 2
```

`concurrency` 是同时运行的顶层任务上限，所有会话共用，嵌套任务不计入。它用于防止失控派发：达到上限时新的 `spawn` 直接报错，不排队；已有任务经 `send` 或 `reply` 开始的新一轮不受限制。持续没有事件达到 `stall_minutes` 时，任务标为 stalled 并通知调用方；任务继续运行。`spawn --timeout` 在每次启动执行达到时限后中断任务及仍在执行的子任务，状态为 `interrupted`；用 `send` 在原生会话中续接，新一次执行重新计时。手动 `cancel` 后同样可以续接。

每个 backend 可以设置默认模型和可执行文件路径。例如：

```toml
[agents.claude]
model = "haiku"
# path = "/absolute/path/to/claude"
```

同样支持 `[agents.codex]`、`[agents.grok]`。`--model` 覆盖默认模型。`path` 必须指向真实可执行文件；Windows 上应使用 `.exe`。省略时按[后端的路径查找规则](backends.md#可执行文件与配置继承)定位。

`axiopera models <agent>` 查询模型 ID 和支持的推理强度。别名有解析结果时显示为 `别名 → 具体模型 ID`；重复名称省略，说明保留在 `--json`。首行写明不带 `--model` 派发时使用的模型：有 Axiopera 配置时是配置值，否则是原生 CLI 按用户自己的设置选出的模型和推理强度。列表中的 `account default` 是 Claude 的账户默认入口，`backend default` 是 Codex 目录的默认，二者不一定是派发所用的模型。Grok 的默认模型可能在查询之后变化，任务实际所用以 `status` 和每轮结果为准。`--cwd` 指定工作目录，默认当前目录。

查询沿用后端的目录发现和缓存，最多等待 20 秒。模型 ID 可直接用于 `spawn --model`，列表中的推理强度可用于 `--effort`。参数仍按原样传给后端。后端明确报告模型或推理强度无效时，错误后附查询结果；自动查询最多等待 5 秒，失败或返回空列表时附查询命令。认证、权限、额度和网络错误保持原报错。

daemon 启动时读取配置。修改后运行 `axiopera daemon stop`，下一次调用会重新启动。未知配置项会报错。

## Skill 与 Codex 插件

skill 让 agent 在派发任务前先运行 `axiopera guide --host <宿主>`，效果与在项目说明中写明这一点相同。`--host` 只输出该宿主取结果的方式，不带时输出全部宿主的。

运行 `axiopera skill install <宿主>`，将程序内置的 [`SKILL.md`](../plugins/axiopera/skills/axiopera/SKILL.md) 离线写入下表目录，新开会话即可使用：

| agent | 宿主参数 | 安装位置 |
|---|---|---|
| Claude Code | `claude` | `~/.claude/skills/axiopera/` |
| Codex | `codex` | `~/.agents/skills/axiopera/` |
| Grok | `grok` | `~/.grok/skills/axiopera/` |

`~` 取 Windows 的 `USERPROFILE`，其他平台取 `HOME`。命令使用表中的固定位置；自定义 skill 目录可手动复制文件。Grok 默认也读取 Claude Code 和 Codex 的上述位置，已有一份时可直接使用。

`axiopera skill install all` 依次安装到全部三个目录，逐项输出结果；某一项失败后继续处理其余项，最终返回非零退出码。

重复安装时，内容相同则跳过；内容不同则提示加 `--force` 确认覆盖，也适用于 `all`。命令只写 `SKILL.md`，输出文件路径。`--json` 在单宿主时输出对象，`all` 时输出数组；每项包含 `host`，成功时带 `path` 和 `changed`，失败时带 `error`。删除安装目录即卸载。

每个会话的上下文都会列出 skill 的名称和描述，约占一行。

Codex 插件包含同一个 skill，另带 hook，让宿主在一轮进行中也能得知子任务的消息。装了插件就不必再复制 skill。插件不包含 `axiopera` 程序。

- 安装：`codex plugin marketplace add Victor-Quqi/Axiopera`，再 `codex plugin add axiopera@axiopera`。
- 卸载：`codex plugin remove axiopera@axiopera`，再 `codex plugin marketplace remove axiopera`。

hook 信任后才运行。桌面端在插件页信任；TUI 启动时发现新的或改动过的 hook 会弹出确认，也可以在 `/hooks` 中信任。hook 定义改动后需重新信任；Codex 0.164 起，插件中任何文件改动都需重新信任，包括升级插件。工具调用之后，如果有新的结果、提问或审批请求，hook 列出每条的一行摘要，提醒宿主运行 `inbox`；一轮结束时仍未取走的，由门铃在本轮结束后提醒。

装了插件后，Codex 每个会话都会启动一个 `axiopera mcp --codex-hooks` 进程。hook 只查询已在运行的 daemon，不会启动它；没有相关任务时立即返回。实测进程启动不到 0.1 秒，每次 hook 调用不到 1 毫秒。删除 `axiopera` 程序前先卸载插件，否则 Codex 无法启动这个进程。卸载不会结束已打开会话中的这个进程，需要时手动结束。

Codex 卸载插件后会留下以下内容，运行 `axiopera plugin cleanup` 清除：

- `config.toml` 中 hook 的信任记录 `[hooks.state."axiopera@<来源>:codex/hooks.json:…"]`。如果保留，重装定义相同的插件时会直接沿用旧的信任。
- `.hook-trust/` 下插件内容的基线（Codex 0.164 起）。Codex 用它核对旧版本写下的信任记录。
- 空目录 `plugins/cache/axiopera`。

数据目录取 `CODEX_HOME`，未设置时为 `~/.codex`。插件仍装着时，清理命令不做任何处理。配置通过 Codex 自己的配置接口修改。

## daemon 与清理

CLI 按需启动 daemon。没有运行中的 agent 和客户端连接时，daemon 空闲 10 分钟后退出。主会话退出不会取消已派发的任务。

`axiopera daemon status` 查看 daemon，`daemon stop` 在没有运行任务时停止它。`daemon stop --force` 会中断正在运行的任务，之后可用 `send` 续接。升级二进制前先停止 daemon。

Axiopera 自动删除 30 天未活动且已停止的任务，以及请求日志 `daemon/requests.jsonl` 和 daemon 日志 `daemon/daemon.log` 中 30 天前的行。`axiopera gc` 立即删除所有已停止的任务和请求日志，`--days N` 保留最近 N 天有活动的。运行中或即将开始运行的任务，以及仍有子任务的父任务，都不会被删除；收到兄弟任务的留言也算一次活动。任务删除后不能再对它 `send`、`result` 或 `log`。

`daemon.log` 在启动及每 24 小时裁剪旧记录，并按 4 MiB 轮转；可选的 `protocol.log` 按 16 MiB 轮转，各保留一个 `.log.1` 备份。超过单文件上限的诊断行截断并注明。任务事件、输入和结果不按容量截断，随任务一起清理。

卸载前先停止 daemon。通过 Cargo 安装的执行 `cargo uninstall axiopera`；通过 Release 压缩包安装的删除可执行文件。数据目录按需删除，原生 agent 的会话仍由各自 CLI 管理。