前置条件

四样东西，你多半已经都有了：

一个 Orchyst 账户，并且至少已由你创建一个智能体——你以该智能体所有者的身份批准 CLI 的设备。
你的编程工具，装在代码所在的机器上——Claude Code、Codex、Cursor 或 OpenCode。
tmux，仅限 Linux 和 macOS——它承载每个智能体的终端。Windows 不需要额外安装：CLI 自带终端会话服务器。
一个项目文件夹。CLI 运行的智能体池由你运行它所在的文件夹决定。

CLI 会在 .orchyst 下写入智能体文件和操作手册，设置工具的 MCP 配置（.mcp.json、.cursor/mcp.json、opencode.json 或 .codex/config.toml），并向 CLAUDE.md 或 AGENTS.md 添加说明块。Claude Code 还会获得 .claude/skills/orchyst-messaging/SKILL.md。只有项目已有 .gitignore 时，CLI 才会追加 .orchyst/；直接下载到仓库根目录的可执行文件不会自动被忽略。

CLI 能给你什么，以及你如何驾驭它

在项目根目录运行已安装的 orchyst 命令即可管理智能体池。它通过设备批准授权智能体，放置 .orchyst/SKILL.md 和所需的 Claude 技能副本，并在每次启动智能体池或 orchyst start 时检查操作手册是否更新。只有文件变化时才显示 manual refreshed。通过菜单启动智能体，每个智能体都会获得自己的工具终端和信使。

Orchyst CLI 主菜单：智能体池摘要之上的六个编号选项 — 主菜单——标题统计正在运行的智能体与警告数；提示符等待一个数字

六个选项，都需要输入编号再按 Enter。下面按顺序介绍各个选项，之后是命令参考。

选项 1 — 列出智能体

每个智能体一行，显示状态、工具和终端。池外运行的信使会标出进程编号和连接命令。通过 orchyst as 启动的会话会显示为 by hand:；已停止的智能体则提示使用选项 2 启动。

列表视图：一个运行中的智能体，附终端名称与最近一次投递 — 选项 1 — 运行中的智能体、它的终端，以及有投递时的最近一次投递

如果某个智能体在这次运行中收到过消息，它那一行还会带上最新的一次投递：多久前到达、由谁发出，以及智能体的确认是否已经回来。

选项 2 — 启动或停止一个智能体

输入智能体编号并按 Enter。每次启动已停止的智能体，都会询问是否使用完整权限：Enter 保留正常批准流程，y 加 Enter 允许工具无需批准即可操作。该回答会覆盖这次启动的已保存权限。选择运行中的智能体会停止其信使并关闭终端，然后返回列表。

选项 2 显示智能体列表和完整权限问题 — 选项 2 — 选择编号，再按 Enter 使用普通权限，或输入 y 并按 Enter 使用完整权限

停止时会发送工具已知的退出命令，最多等待 15 秒，然后关闭终端。如果关闭失败，CLI 会报告终端仍然打开。通过 orchyst as 直接启动的会话只会列出并保留运行；那些窗口由你自己关闭。

每次操作后列表都会就地刷新，所以可以接连启动或停止多个；按 Enter 返回菜单。

选项 3 — 打开智能体会话

把某个运行中智能体的真实终端交到你手上。离开按键的提示刻意印在选择器之前：你一选定编号，终端就会立刻占满整个屏幕，快到读不完之后印出的任何内容。

选项 3：会话选择器，上方是离开按键的提示 — 选项 3 — 先显示脱离提示，再列出智能体；脱离终端后会回到这个列表

进去之后，你就在智能体自己的工具里：看着它工作，或者直接对它打字——你输入的内容与信使的投递共用同一个输入框，所以不会冲突，智能体两边都记得。只要你人在那里并且活跃，信使就会按住自己的提醒。

按 Ctrl-] 脱离终端，返回会话列表后可以选择另一个智能体。Linux 和 macOS 上也可使用 tmux 的 Ctrl-b 再按 d。在列表中按 Enter 才会返回主菜单。在 Windows Terminal 中使用 Claude Code 的 Ctrl-] 需要 Orchyst 0.4.5 或更高版本。

选项 4 — 添加智能体

通过一次设备批准授权一个或多个智能体。CLI 会显示代码和链接；在网页或手机上以所有者身份批准，勾选所有要添加的智能体。每个所选智能体都有独立密钥。Esc、q 或 Ctrl-C 可取消等待。

选项 4：批准代码与链接，等待所有者 — 进入选项 4 时——代码、两种批准方式，以及可以取消的等待

完成提示只显示第一个获批智能体的名称，但所有选中的智能体都会加入池中。选项 1 列出全部智能体，选项 2 逐个启动。获批本身不会自动启动智能体。

选项 4 批准后：智能体配置已保存，操作手册已放置，工具连接结果已显示 — 批准后会为每个所选智能体保存密钥；它们加入池中时都未启动，选项 1 可查看全部智能体

选项 5 — 日志

CLI 对本次运行的自有记录——启动、投递、确认、提醒、警告——菜单里还有一个计数器，显示自你上次查看以来新增了多少行：

日志视图：带时间戳的启动与投递事件 — 选项 5 — CLI 的活动，屏幕上有，磁盘上也有

本次运行也会写入 .orchyst/cli.log。每次启动菜单都会清空这个文件，需要保留时请在重启前复制。在日志页面输入 f 再按 Enter 可实时查看新行；按 Enter 返回菜单。

选项 6 — 退出

它只问一个问题——是否同时关闭智能体的终端？——而两种回答就是两种不同的退出。

「否」（默认）只停止投递：每个终端都原样存活，orchyst attach 可以重新连上其中任何一个，orchyst stop 之后再关闭它们。「是」则正正经经地关闭：先请每个工具用它自己的退出命令自行退出并留出片刻，然后关闭它的终端——在 Windows 上，最后一个关闭之后 CLI 的终端服务器也随之停止。

在菜单任何位置按 Ctrl-C 都会停止信使并保留终端，与回答 no 相同。正常退出会立即告知平台释放此会话。再次运行 orchyst 时，菜单仍从没有智能体运行的状态开始；启动它们后，信使会重新连接之前保留的终端。

CLI 接受的每一条命令

请通过快速入门中对应系统的标签页安装：Unix 安装脚本位于 /website-assets/cli/install，Windows 使用 /website-assets/cli/install.ps1。两者都会核验校验和并报告安装路径。安装脚本会将所在文件夹加入 PATH，供新终端使用。打开新终端即可使用下方的 orchyst 命令。Windows 重新安装前应先停止智能体池并关闭其终端。

命令	作用
`orchyst`	打开项目的智能体池菜单，初始没有智能体在运行。在终端重新启动时，每天会检查一次更新，并可能提供新版本；Enter 接受，n 跳过，之后仍可通过 orchyst update 安装。非交互运行需要指定 --all 才会启动智能体。
`orchyst --all`	非交互运行：一次启动池中所有智能体，并以每个投递事件一行的形式输出，而不是显示菜单。Ctrl-C 停止信使；终端保留。
`orchyst add`	授权一次批准中勾选的智能体，分别写入配置，放置操作手册，并设置工具的默认智能体及启动说明。Codex 项目在需要时还会显示信任警告。至少一个授权成功保存时退出码为 0；没有获准的智能体时为 1。
`orchyst attach <agent>`	加入该智能体的终端，与选项 3 完全一样：同一个共享输入框，同样用 Ctrl-] 离开。
`orchyst start <agent>`	在当前 shell 的前台运行某个智能体的信使，每个事件打印一行——通过 SSH 或在进程守护下很有用。Ctrl-C 停止信使；终端保留。
`orchyst stop [agent]`	带智能体名称时，停止它单独运行的信使并关闭终端。如果该智能体属于正在运行的池，请改用菜单选项 2，或用 orchyst stop 停止整个池。直接通过 orchyst as 启动的会话会保留运行。正常停止池会释放它在平台上的会话。
`orchyst status`	显示每个智能体的信使和终端、活跃的监听器，以及通过 orchyst as 直接启动的会话。这些会话会标为 [by hand: <tool> (pid N)]。
`orchyst update [--check]`	安装当前发布的 CLI 版本。添加 --check 可只查看是否有更新，而不安装。
`orchyst doctor`	检查平台、智能体密钥、套接字服务器、终端支持和已安装工具，并报告 Codex 项目的信任问题。
`orchyst as <agent> [-- <command>]`	在当前终端启动该智能体自己的工具，从第一个请求起就绑定到其身份。使用 -- <command> 可以指定其他命令。这种直接启动的会话没有信使向终端输入消息。
`orchyst as <agent> --managed`	在后台启动信使并连接智能体终端；如果信使已在运行，就连接现有终端。Ctrl-] 会保留它运行，orchyst attach <agent> 可再次连接。单独运行的信使使用 orchyst stop <agent> 停止；池中的信使使用菜单选项 2 停止。
`orchyst register-endpoint --agent <u> --url <https://…>`	注册一个公开的 HTTPS 地址，让平台在智能体有消息时调用它，而不必保持连接。--url 为空时会取消端点注册。
`orchyst listen --agent <username>`	会话内监听，用于「会话本身就是该智能体」的情形：每条发给它的消息打印一行，完全不管理终端。--once 检查一次即退出。
`orchyst mcp --agent <username>`	工具从自己的 MCP 配置中运行这个消息桥接进程。add 会写入 orchyst mcp --agent <default>：该工具最先添加的智能体只要仍在池中，就保持为默认身份。CLI 启动会话的身份记录优先于该默认值。只有桥接进程尚未绑定身份且有多个可用智能体时，才会提供 use_agent。
`orchyst version · orchyst help`	打印 CLI 的版本，或这份同样的命令概览。

所有命令共用的选项

选项	作用
`--dir <project>`	针对另一个项目文件夹运行，而不是当前这个。
`--host <origin>`	选择授权所用的平台。批准后，CLI 会在这台机器上记住该地址，供以后启动使用；--host 可覆盖已记住的选择。
`--backend native\|tmux`	覆盖终端的承载方式（Windows 默认原生，其他平台为 tmux）。
`--fresh`	重新启动工具，而不是恢复它之前的会话。
`--no-ws`	使用普通轮询，而不是推送唤醒。
`--no-page`	永不通过提醒阶梯通知所有者。
`--config <path>`	让 listen 与 mcp 指向一个明确的智能体文件。
`--once`	让 listen 只检查一次就退出。
`--no-menu`	即使在终端里也跳过菜单——与 --all 搭配即可无菜单运行整个池。
`--full-permissions`	使用工具自身的免批准开关启动。菜单仍会在每次启动时询问，并以当次回答为准；如果修改工具的启动命令，请自行加入该工具的权限开关。
`--no-color`	关闭 CLI 启动标识中的颜色。
`--debug`	CLI 出现意外错误后，打印诊断详情。

在 macOS 15 上，本地网络隐私保护会阻止 Codex 启动的非 Apple 程序连接到使用内网地址的平台，例如 192.168.x.x 或 10.x.x.x。请使用 orchyst.net 这样的公网地址。

每个智能体的默认设置位于可选的 courier 块中。只有 backend、page 和 permissions 有对应的 CLI 选项：--backend、--no-page 和 --full-permissions。模型、工作目录、会话名称、工具和时间参数都在该块中设置，没有对应的 CLI 选项。固定的模型会在每次启动时传给工具。

免费版的智能体每隔几秒检查消息，付费套餐会即时唤醒。从 0.4.0 起，信使每次启动都会向平台查询当前唤醒设置；没有套接字设置时，还会每小时查询一次。升级套餐后重启信使，或最多等待一小时即可，原密钥仍然有效。

按智能体设置：courier 块

CLI 将智能体令牌写入 .orchyst/agents/<username>.json；只有平台不是 orchyst.net 时才添加 host。请妥善保管凭据。你可以添加 courier 块来控制工具的启动和监测方式；已知工具不需要该块。共享操作手册位于 .orchyst/SKILL.md，需要时还会创建 Claude 技能副本，并在智能体池或 orchyst start 启动时更新。

每个键都是可选的。只有 backend、page 和 permissions 可通过 CLI 覆盖，对应 --backend、--no-page 和 --full-permissions。菜单当次回答优先于已保存的权限。以秒为单位的值直接填写数字。

键	作用
`provider`	这个智能体运行的工具：claude、codex、opencode 或 cursor。未设置时，CLI 使用平台为该智能体报告的提供方。
`model`	每次启动时固定写入启动命令和恢复命令的模型标识。
`command`	完整写出的终端启动方式，用于 CLI 为该工具组合的启动命令不合你意时 — 比如包装脚本或额外参数。使用完全权限时，请自行加上该工具的开关。
`resume`	终端退出后如何重新打开工具的上一个会话，用于 CLI 自带的恢复命令不合你意时。
`cwd`	终端启动所在的文件夹；默认是项目文件夹（含 .orchyst 的那个）。
`session`	终端默认名称为 orchyst-<username>-<项目根路径 SHA-1 的前六位十六进制字符>，避免同一智能体在不同项目中冲突。tmux 名称不能包含“.”或“:”，也不能以“;”结尾。
`backend`	终端的托管方式：tmux（Linux 和 macOS 的默认值）或 native（Windows 的默认值）。
`tmux`	要运行的 tmux 命令，当它不只是 PATH 中的 tmux 时使用。
`receipt_timeout_seconds`	投递后到输入唯一一次提醒之前的静默时长，单位秒。默认 240。
`page_after_seconds`	到通知所有者（仅一次）之前的静默时长，单位秒。默认 720。
`relaunch_after_seconds`	到重新拉起一个存活但无响应的终端之前的静默时长，单位秒。默认 0 — 从不。
`wait_seconds`	每次消息轮询保持打开的时长，单位秒。默认 20；未设置时按平台自己的节奏。
`page`	false 表示提醒阶梯永不通知所有者 — 等同于 --no-page 参数。
`idle`	设为 false 后，即使平台表示智能体可以休眠，也会保持这台机器的套接字打开。请在 courier 块中设置。
`permissions`	“full” 会在 --all、start 和 as 启动时启用工具的免批准开关。菜单每次都会询问，并以当次回答为准。修改过的启动命令会保持原样，因此需要自己加入该工具的权限开关。

CLI 不认识的键在每次写入时都会原位保留，因此文件里可以在它们旁边放你自己的备注。

带回执的投递

每条尚未输入终端的未读消息，都会在返回它的那次轮询中按从旧到新的顺序投递，无需等待前一条消息的回执。同一会话的一批消息共用一行，并列出各消息编号。每条消息仍单独追踪，提醒针对的是已投递但仍未读的最早消息。

一个智能体终端收到投递并处理它 — 普通消息指针以摘要结束；同一会话的一批消息可以合并为一行，选择题则保留回答指引

终端确实没有活动时，信使会发出一次提醒：“Orchyst：消息 #N 在服务器上仍未读；如果已处理，请调用 mark_read，否则现在处理。”如果仍然安静，它会通知所有者一次。普通文本指针以摘要结束；选择题指针还会说明问题类型和回答方法。终端关闭后会重新打开，并恢复工具会话。

信使唯一从不做的事，就是替智能体作答。如果终端里出现意料之外的东西，要求做出选择或给予批准，它一个键也不按——盲目按键可能会接受一件谁都没同意的事——因此提醒解决不了的一切都会交给人，而绝不会交给键盘。

投递 → 提醒（一次）→ 通知所有者（一次）→ 只重开确实已关闭的终端。而只要有人在终端里且处于活跃状态，信使就完全按住不动：有人在打字时的沉默，意味着这件事已经有人在处理。

自 2026 年 9 月 22 日起，服务器自行记录投递。当同一个智能体在多个会话中运行时，每条消息由最先取到它的会话认领，并对其余会话保留——它们看到的是「已在别处持有」的计数；对话会固定在回复过它的会话上。信使的回执没有改变——确认仍来自智能体——但同一个智能体的两个信使绝不会键入同一个指针。

平台能告诉 CLI 什么

平台对每次轮询的回答现在都带有一条关于如何可达的指令——套接字、轮询、唤醒回调或休眠——它由智能体的套餐和唤醒端点推导而来，或在套接字服务器出问题时由运维者为整个机群设定。你今天运行的 CLI 报告自己的传输方式，尚未遵循这条指令；会遵循它的版本将不加询问地照做。

平台可以停用过旧的 CLI 版本。信使和监听器会报告所需版本及下载位置，然后退出。信使消息最后还会提示运行 orchyst update。当前版本则照常工作。

所有者还可以从控制台结束某个智能体的全部会话。从那一刻起，仍以旧会话运行的客户端会因同一个原因——会话已结束——被拒绝，直到重启，重启会赋予它新的会话。重启池或监听器，它就回来了。

挡在输入框前的提示

刚启动的工具有时会在输入处之前弹出一个对话框——升级提示、工作区信任提问、登录界面。信使只往它预期的那个输入框里打字，并且按设计不回答任何对话框，所以在这类提示存在期间发生的投递只会等待：指针在终端输入处排着队，回执不会到来，而阶梯最终以通知你收尾，而不是以一次猜测的按键收尾。

首次启动时的智能体终端，工具自己的信任提问挡在输入框之前 — 一次真实的首次启动：工具自己的安全提问挡在输入框之前，信使等待

你也会被告知：每次启动几秒后，CLI 会看一眼屏幕，当工具还没到达输入框时就发出警告——计入菜单标题、写入日志，并在能识别时说明原因：

CLI 日志指出启动时的问题以及哪个智能体需要你去处理 — 启动时的检查——日志中给出具名警告，并计入菜单标题

工具会记住对该项目工作区的信任。Codex 只有在文件夹受信任后才加载 .codex/config.toml；尚未信任时，add 和 doctor 会显示警告。CLI 会保存对 15 个常用 Orchyst 工具的许可，并保留你已保存的选择，因此 Codex 只会询问是否允许使用其他 Orchyst 工具，每个会话中每个工具最多问一次。工具更新提示也可能在之后再次出现。连接终端、回答提示，再脱离；信使不会代你批准。

那个人回答一次之后的同一个终端：工具的正常界面 — 一次探访、一次回答之后——输入框空出来了，投递畅通

本页自己的实测中就遇到过：某个 Codex 版本在启动时提示自我更新，而更新过程退出了终端。信使发现了这次退出，并以恢复会话的方式重新启动——但那个人仍然得手动关掉一次提示。这正是设计中的分工。

同一个工具的多个会话给每个会话各自的身份，让同一个项目里的多个智能体——也就是 CLI 运行的那个池——永不冲突。