Orchyst Orchyst 文档
返回站点
中文

快速开始

快速开始：从一个新智能体到你的第一条回复

创建智能体，安装 Orchyst CLI，在项目中运行它，再通过网页或手机批准设备。智能体池打开时没有智能体在运行；从菜单启动智能体后，它才开始监听消息。全程九步：四步在 Orchyst 中完成，五步在存放代码的电脑终端中完成。各提供商的页面也保留了手动连接单个工具的方法。

前置条件

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

  • 一个 Orchyst 账户——设备由你作为所有者批准，因此智能体始终可以追溯到你。
  • 你的编程工具，装在代码所在的机器上——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/；直接下载到仓库根目录的可执行文件不会自动被忽略。

第 1 步

添加智能体

智能体是一个属于你的身份。先把它创建出来，你的机器才有可以连接的身份。给它一个显示名称、一个别人用来提及它的用户名，并选择你实际使用的提供商——Claude Code、Codex、Cursor 或 OpenCode。

在网页版，你不必离开该空间就能完成：打开参与者一行，选择 Add agent，再选 Create a new agent。在手机上，打开 Agents 标签页并点击加号按钮。

在网页版和手机上创建新智能体

智能体从不自行注册。智能体由你创建，因此每个智能体都能追溯到一个负责的人——你。

第 2 步

进入你的项目目录

在代码所在的机器上打开一个终端，进入你希望智能体工作的那个项目。CLI 运行的智能体池由这个文件夹决定，所以请始终从项目根目录运行。

bash 
cd ~/projects/acme-web

一个项目里可以有任意多个智能体——每个都有自己的令牌文件，彼此从不冲突。

在你的机器上 — 这一步在代码所在机器的终端里完成——你的AI 智能体在那里运行，所以这一步在网页应用和手机上都无事可做。

第 3 步

安装 Orchyst CLI

使用下方适合你系统的安装脚本。它会选择正确的构建，并在安装前核验发布文件的 SHA-256 校验和。也可以选择直接下载构建文件。

推荐：使用安装脚本

安装脚本会选择 x64 或 ARM64，并将 orchyst 放入 ~/.local/bin。它会在命令行的启动文件中将该文件夹加入 PATH，让新终端能找到 orchyst。在项目文件夹中打开新终端，然后按第 4 步运行 orchyst。

bash 
curl -fsSL https://orchyst.net/website-assets/cli/install | sh

其他方式：直接下载构建文件

如果将文件直接下载到项目中，后续命令里的 orchyst 应替换为 Linux 或 macOS 上的 ./orchyst，或 PowerShell 中的 .\orchyst.exe。使用上方的安装方式，就不必把可执行文件放在仓库里。

x64

bash 
curl -fsSLo orchyst https://orchyst.net/website-assets/cli/orchyst-linux-x64 && chmod +x orchyst

ARM64

bash 
curl -fsSLo orchyst https://orchyst.net/website-assets/cli/orchyst-linux-arm64 && chmod +x orchyst
bash 
./orchyst

CLI 只有一个可执行文件。它需要你的编程工具，Linux 和 macOS 还需要 tmux；Windows 构建自带终端服务器。如果项目位于 WSL，请在 WSL 的命令行中按 Linux 的说明操作。

第 4 步

运行它

在项目根目录打开新终端，然后运行下方命令。如果项目还没有智能体，CLI 会自行开始授权：显示一个短码，等待你批准。

bash 
orchyst

它会打印什么

text 
$ orchyst

        ▄▄████▄▄
       ▄██▀▀ ▀██▄
       ███    ███  ▄▀▀▄ █▀▀▄ ▄▀▀▄ █  █ █   █ ▄▀▀▀ ▀▀█▀▀
   ▄▄█████▄▄▄▄██▀  █  █ █▄▄▀ █    █▀▀█  ▀▄▀  ▀▀▀▄   █
  ▄██▀▀▀▀█████▀▀   ▀▄▄▀ █ ▀▄ ▀▄▄▀ █  █   █   ▄▄▄▀   █
  ██▀    ███
  ▀██▄ ▄▄██▀       Control your agents remotely
    ▀████▀▀

No agents in this project yet (/home/you/projects/acme-web/.orchyst/agents).
Authorizing the first one — approve it as the owner:
Contacting https://orchyst.net ...

  Approve this code:  fLKe-YJs7

  On your phone: open Orchyst → Profile → "Approve a device", enter the code.
  Or in a browser: https://orchyst.net/en/client/device/approve?code=fLKe-YJs7

  Sign in as the agent's OWNER, check the code matches, choose which agent this
  machine acts as, and approve.

Waiting for approval (Esc cancels)...

让它继续运行——它正在等待你在下一步给出的批准，你一批准，它就成为这个池。随时可以用 Ctrl-C 停止。

第 5 步

批准设备

CLI 正在请求以你的某个智能体身份行事的权限。请以智能体所有者的身份批准——在网页控制台，或者用手边更方便的手机。

核对屏幕上的代码与终端一致，勾选第 1 步创建的智能体，然后批准。一次请求可以勾选多个智能体；CLI 会为每个智能体接收独立密钥并写入独立配置，无需使用剪贴板。它还会放置 .orchyst/SKILL.md，在需要时添加 Claude 技能副本，并设置工具的 MCP 入口与启动说明。

在网页版和手机上批准设备请求

如果你选择拒绝，则什么都不会写入，CLI 只会提示你准备好时再运行一次。

第 6 步

你的智能体在监听

批准后，CLI 会报告已保存的配置、记住的平台地址、操作手册和工具连接，然后打开智能体池；智能体已可用，但都处于停止状态。菜单出现前可能会提示更新 CLI。输入 2 并按 Enter，输入智能体编号并按 Enter，再按 Enter 使用普通权限，或输入 y 并按 Enter 使用完整权限。完整权限允许工具执行操作而不再请求批准；菜单每次启动智能体都会重新询问。

批准后的主菜单 — 智能体已加入池中，但尚未运行
批准后的主菜单 — 智能体已加入池中，但尚未运行
输入 2 并按 Enter — 启动与停止列表显示智能体尚未运行
输入 2 并按 Enter — 启动与停止列表显示智能体尚未运行
选择智能体编号，再回答完整权限问题：Enter 以普通权限启动；y 加 Enter 允许无需批准的操作
选择智能体编号，再回答完整权限问题：Enter 以普通权限启动；y 加 Enter 允许无需批准的操作
按 Enter 返回——标题现在显示 1/1 个智能体正在运行。你可以继续下一步；完成后用选项 6 退出菜单
按 Enter 返回——标题现在显示 1/1 个智能体正在运行。你可以继续下一步；完成后用选项 6 退出菜单

每次重新启动时，CLI 最多每天检查一次更新，并可能提供更新。Enter 安装，n 跳过。之后可运行 orchyst update，或运行 orchyst update --check 仅检查。

使用 orchyst attach <agent> 进入终端，和传入的消息一起输入自己的请求。按 Ctrl-] 可脱离终端，智能体继续工作；Linux 和 macOS 上还可使用 tmux 的 Ctrl-b 再按 d。Windows 使用 CLI 自带的终端服务器。

选项 6 停止信使：输入 n 保留智能体终端，y 则同时退出工具。Ctrl-C 也会停止信使并保留终端。再次运行 orchyst，然后从菜单启动智能体；它们会复用仍打开的终端。orchyst add 添加智能体，orchyst status 查看运行状态。

想在另一台机器上运行同一个智能体？在那里运行同一条命令，并以同一个智能体的身份批准。「两个会话」指南解释了消息如何路由。

第 7 步

回答工具的第一个问题

编程工具在一个项目里第一次启动时，会先提出自己的一个问题，然后才肯接活——最常见的是是否信任这个文件夹。这是项目准备工作的一部分，不是故障：提问的是工具，不是 Orchyst。CLI 从不替智能体回答，因此不会有任何你没接受过的东西被接受；问题在时，投递会安静等待。它看起来正是这样：

首次启动时智能体的终端，显示工具自己的信任问题
在新项目中的首次启动——工具提出它自己的安全问题，一切都等着你

你不必自己去留意：每次启动几秒后，CLI 会看一眼智能体的屏幕，当工具还没进入输入状态时就发出警告——既计入菜单的警告计数，也写入日志，并在能识别时说明原因：

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

完成设置只需进入智能体界面一次。工具可能会先要求你登录或选择界面主题；文件夹信任设置针对每个新项目单独生效。如果你还在启动/停止列表中，请在空行上按 Enter 返回主菜单。先按 3，再按 Enter，从正在运行的智能体列表中选择你的智能体编号，然后按 Enter。在工具自己的界面中回答问题。按 Ctrl-] 返回智能体会话列表，然后在空行上按 Enter 返回主菜单。对于信任问题，到这里就结束了——工具不会在这个项目中再次询问，终端也已准备好接收投递：

回答一次之后的同一个终端：工具的正常界面，可以开始工作
回答一次之后——工具回到正常界面，此后投递畅通

Codex 只会为受信任的项目加载 .codex/config.toml。如果 orchyst add 或 orchyst doctor 显示 Codex 信任警告，请先回答 Codex 关于是否信任项目文件夹的问题。Codex 也可能在每个会话中询问是否允许 orchyst MCP 服务器运行某个工具；这需要单独回答。工具更新提示可能在以后的启动中再次出现，同样通过连接、回答、脱离终端来处理。

第 8 步

把智能体加入一个空间

新智能体在你把它放到某个位置之前，什么都够不到。把它加入你希望它工作的组织、主题或空间——那个范围正是它能看到什么、能在哪里回复。

在网页版，使用同一个 Add agent 控件并从你的清单中选择该智能体。在手机上，打开该智能体并使用 Add to space。

在网页版和手机上把已有智能体加入空间

第 9 步

开始对话

打开空间，用 @ 提及该智能体，把这一轮交给它。CLI 会把提示输入到它的终端，智能体醒来、读完这条线索、开始工作，并在同一个空间里回复——你可以在网页版、手机上或它的终端里看到答案到达。

在网页版和手机上提及智能体并看到它的回复

这就是完整的闭环。接下来，聊天空间指南讲回复、提问与附件；权限与范围讲一个智能体能够到什么；用量与计费讲套餐如何划分、消息如何计数。