从安装到第一个
多 Agent 任务

00 / PREPARE

准备

你需要：

• macOS 或 Linux 终端
• Homebrew（macOS / Linux 均可）
• 一个 coding agent：Claude Code、Codex CLI 或 AGY
• 一个 Markdown / Obsidian 笔记库（可选，用于记忆同意）

Aegis OS 目前不支持 Windows。不要把真实生产密钥放进示例目录；教程使用本地临时项目。

01 / INSTALL

安装 Aegis OS

# 添加 Heurion tap 并安装
brew tap heurion-org/aegis-os https://github.com/heurion-org/aegis-os.git
brew trust heurion-org/aegis-os
brew install aegis-os

# 接入 AGY / Claude Code / Codex（运行一次）
aegis-os install

# 验证
aegis-os --version
aegis-os doctor

Homebrew 安装二进制后，运行一次 aegis-os install，把 Aegis OS 接入 agy、claude 与 codex；随后 doctor 应全部通过。

如果不用 Homebrew：从 GitHub Releases 下载对应平台二进制，或从源码 cargo install --path crates/aos-cli。安装后同样运行 aegis-os install。

02 / FIRST RUN

接入 Agent

进入一个项目目录，直接启动你常用的 Agent：

# 任选其一
claude
codex
agy

Aegis OS 的 hook 会自动附加运行时。默认直接进入免费的 Local CoW 沙箱模式，你也可随时切换到 Cloud 模式：

也可以在对话里直接说“切换到 Local 模式”或“切换到 Cloud 模式”。

验证隔离与边界审批

让 Agent 修改一个文件，然后运行：

aegis-os workspace status
aegis-os workspace diff

你会看到修改先落在 CoW 影子工作区，尚未写回宿主目录。当 Agent 调用 workspace_commit 合并回宿主机时，桌面环境会自动打开网页审批台（/approve，点击批准后自动续跑），纯终端/SSH 下也可运行 aegis-os approve（或简写 aos approve）一键放行。

03 / MEMORY CONSENT

记忆同意：只读批准的范围

UOMP 是 Aegis OS 执行的记忆同意协议。先给客户端写入 bridge profile，并导入笔记：

aegis-os memory setup claude --vault ~/Notes

这条命令会：

• 导入 Markdown 笔记（默认 tag notes，可用 --tag 修改）
• 在后台启动本地 memory server（默认 127.0.0.1:9374）
• 写入 Claude Desktop / Cursor / OpenCode 的 MCP 配置
• 不签发 Token，不授权任何访问

重启客户端，然后让 Agent 读取笔记：

# 在 Claude / Cursor / OpenCode 里
列出 notes/projects 下的笔记

第一次 tool call 会创建 consent request。Aegis OS 会自动打开本地同意页（127.0.0.1:9375）；在页面上勾选要授予的 tag / key，然后点 Allow selected。不需要另开终端。

# 如果浏览器没有自动打开，手动启动同意页
aegis-os memory ui

# 终端 fallback
aegis-os memory pending
aegis-os memory approve <request-id>

同意页会显示 request id、Agent、task id（如果有）、session id 和过期时间。批准后当前调用继续；拒绝则返回错误。

高敏数据不会因为 tag scope 被批量放开。同意页会把具体 key 单独列出，你必须逐 key 勾选；Agent 不能批准自己的请求。

验证

aegis-os memory sessions
aegis-os memory audit --limit 20

你应该看到 session 的 scope、过期时间，以及 allow / deny 审计事件。

04 / MULTI-AGENT

多 Agent / A2A

Aegis OS 用 Google A2A 作为 Agent 之间的协作总线。创建一个 stateful task：

aegis-os ipc request \
  --to worker \
  --subject "Review auth module" \
  --message "Read the auth module and report risks"

查看任务：

aegis-os a2a board
aegis-os a2a show <task-id>

board 会显示 task、state、from → to、age、flags、subject。input-required 会置顶并标记 BLOCKED；失去 assignee 的任务会标记 STALE。

任务级租约

如果某个任务需要一段时间的自动提交权限，可以把 lease 绑定到 task：

aegis-os policy lease \
  --action-pattern workspace_commit \
  --ttl-secs 3600 \
  --task-id <task-id>

输出会包含 "kind": "task_scoped" 和 task_id。任务进入终态后，绑定 lease 会被撤销；同一个 Agent 不能把 task A 的 lease 用到 task B。

如果使用自定义 --runtime-dir，所有 a2a / policy / memory revoke 命令都要传同一个 runtime 目录。

05 / REVOKE & AUDIT

撤销与审计

查看并撤销一个 memory session：

aegis-os memory sessions
aegis-os memory revoke <session-id>

撤销后：

• 下一个 memory 请求返回 401 SESSION_NOT_ACTIVE
• 如果 session 绑定了 A2A task，task 会转为 input-required（标记 BLOCKED）
• 审计会记录 revoke 事件和 task id

aegis-os memory audit --limit 20
aegis-os a2a board

如果任务通过 gateway 进入终态（例如 tasks/cancel），Aegis OS 会调用 memory server 的 revoke-by-task，自动撤销该任务的 memory sessions。

06 / TROUBLESHOOT

故障排查