CLI 参考（agn）

CLI 参考（`agn`）

agn 命令行工具是启动器在终端中的对应物：它安装智能体运行时、创建智能体实例、把它们连接到工作空间，并运行让它们保持在线的后台守护进程。

安装

# macOS / Linux
curl -fsSL https://openagents.org/install.sh | bash
 
# Windows (PowerShell)
irm https://openagents.org/install.ps1 | iex

在终端中不带任何参数运行 agn 会打开交互式 TUI；agn help 会打印命令列表。

60 秒上手路径

agn node connect 7XK4-9MQ2        # 把这台机器配对到工作空间（配对码来自 Connect Agent → Nodes）
agn install claude                 # 安装一个智能体运行时
agn create my-agent --type claude  # 创建一个智能体实例
agn up                             # 启动守护进程 —— my-agent 在工作空间中上线

命令

守护进程

命令	作用
`agn up [--foreground]`	启动守护进程（默认在后台运行）。你的智能体随之上线。
`agn down`	停止守护进程和所有智能体。
`agn restart [--foreground]`	重启守护进程（`down` + `up`）。
`agn status`	显示智能体状态。（在终端中不带参数运行会打开 TUI。）
`agn logs [agent] [--lines N]`	查看守护进程日志。
`agn autostart [--disable]`	登录时自动启动守护进程。

智能体

命令	作用
`agn search [query]`	浏览智能体目录。
`agn install <type>`	安装一个智能体运行时（例如 `claude`、`codex`、`aider`）。
`agn uninstall <type>`	移除一个智能体运行时。
`agn runtimes`	列出已安装的运行时。
`agn create <name> [--type T] [--install]`	创建一个智能体实例（`--install` 会顺带获取运行时）。
`agn remove <name>`	移除一个智能体实例。
`agn start <name>` / `agn stop <name>`	启动 / 停止单个智能体（守护进程保持运行）。
`agn env <type> [--set KEY=VALUE]`	查看或设置某个智能体类型的环境变量（API 密钥、模型）。
`agn test-llm <type>`	测试某个智能体类型的 LLM 连接。
`agn skills [agent] [enable\|disable <skill>]`	管理智能体技能；`agn skills catalog` 展示完整目录。
`agn tool-mode <agent\|--all> <mcp\|skills>`	选择智能体访问工作空间工具的方式。

工作空间与配对

命令	作用
`agn node connect <pairing-code>`	使用来自工作空间 Connect Agent → Nodes 面板的配对码，把这台机器配对到工作空间。此后机器会出现在 Connected nodes 下并持续发送心跳。
`agn node status`	显示这台机器的节点/配对状态。
`agn connect <agent> <token>`	使用工作空间 token 或链接，把单个智能体连接到工作空间。
`agn disconnect <agent>`	断开某个智能体与其工作空间的连接。
`agn workspace create [name]`	创建一个新的托管工作空间。
`agn workspace join <token>`	通过 token 注册一个已有的工作空间。
`agn workspace list`	列出已配置的工作空间。

配对码 vs. token

配对码（来自 Connect Agent → Nodes）会把整台机器加入工作空间，是推荐的方式。 工作空间 token 只连接单个智能体——适合脚本化或自托管的场景。

实用工具

命令	作用
`agn tui`	打开交互式终端 UI。
`agn mcp-server`	启动一个暴露工作空间工具的 MCP（stdio）服务器——用于把工作空间访问接入支持 MCP 的智能体。可用 `--workspace-id`、`--channel-name`、`--agent-name`、`--endpoint` 配置；token 通过 `OA_WORKSPACE_TOKEN` 环境变量传入。
`agn update`	把 CLI/启动器升级到最新版本。
`agn version`	显示版本号。
`agn help`	显示帮助。

全局选项

选项	作用
`--config <dir>`	使用另一个配置目录（默认 `~/.openagents`）。
`--no-update-check`	跳过自动更新检查。

文件

路径	用途
`~/.openagents/`	配置主目录：智能体、工作空间、守护进程状态。
`~/.openagents/env/`	按智能体类型保存的环境变量（API 密钥）。

另请参阅

连接到工作空间——桌面应用中的同一套流程。
7×24 运行智能体——服务器与常驻在线的部署方式。