快速开始

Quickstart 是引导式安装流程，可一次性将你从全新安装带到可用的智能体。它运行于三种环境：CLI、zerocode 终端界面以及 web gateway。这三者驱动相同的底层流程，因此生成的配置完全一致。可根据你所处的环境选用任意一种。

安装

Unix 快速路径

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | sh

此路由为非交互式，不会打开选择器。

它会优先使用匹配的预构建二进制文件，并在需要时回退到源代码构建。

预构建归档可能包含 zerocode；非交互式源代码回退会安装默认应用，而不打开选择器。

该命令使用固定的特征集。

如果需要从源代码构建，且系统中缺少 Rust，安装程序可以自动安装 Rust。

在 Unix 上，安装程序会在允许的情况下更新 shell 配置文件；在依赖新的 PATH 之前，请重新加载父 shell。

安装程序会跳过设置，并打印 zeroclaw quickstart 作为下一步。

Unix 指导路径

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./install.sh

此路由带有引导功能，可能会提供受支持的选项。

在受支持的目标平台上，它提供预构建安装或从源代码安装。

预构建归档可能包含 zerocode；源选择默认会选中它，并允许应用选择。

源路径还允许你选择可选的 Cargo 特性。

如果需要从源代码构建，且系统中缺少 Rust，安装程序可以自动安装 Rust。

在 Unix 上，安装程序会在允许的情况下更新 shell 配置文件；在依赖新的 PATH 之前，请重新加载父 shell。

对于未配置的安装，它提供 zeroclaw quickstart 或基于浏览器的快速入门。

Windows 预构建路径

使用 Windows 安装指南 中的 PowerShell 代码块。安装和 PATH 设置是幂等的；Quickstart 仍可运行。

此路由为非交互式，不会打开选择器。

此路由会安装预构建的发行版存档。

归档文件中也可能包含 zerocode；是否提供取决于发布资源。

该命令使用固定的特征集。

此预构建方案无需 Rust 工具链。

在 Windows 上，PowerShell 路径会更新当前进程和持久化的用户 PATH。

PowerShell 代码块最后会自动运行 zeroclaw quickstart。

高级源路径

Unix

./install.sh --source

此路由带有引导功能，可能会提供受支持的选项。

此方式始终从源代码构建。

从源代码安装时默认选择 zerocode，并允许您更改应用选择。

源路径还允许你选择可选的 Cargo 特性。

如果需要从源代码构建，且系统中缺少 Rust，安装程序可以自动安装 Rust。

在 Unix 上，安装程序会在允许的情况下更新 shell 配置文件；在依赖新的 PATH 之前，请重新加载父 shell。

对于未配置的安装，它提供 zeroclaw quickstart 或基于浏览器的快速入门。

Windows

cargo install --locked --path .

此路由为非交互式，不会打开选择器。

此方式始终从源代码构建。

此命令会安装核心 zeroclaw 二进制文件；不会安装可选应用。

该命令使用固定的特征集。

使用此命令前需要安装 Rust 工具链。

此 Cargo 命令不会修改 PATH；请确保 Cargo 的 bin 目录已在 shell 中可用。

安装后，运行 zeroclaw quickstart。

步骤

**重要提示：**如果您对以下任何术语感到陌生，请先阅读 Getting Started → Concepts。该文档在同一位置定义了模型提供商、风险配置文件、别名等概念。

每个界面都遵循相同的检查清单并写入相同的配置；目前只有可选的“插件”步骤仅限 CLI 使用。必填步骤必须全部完成后才能创建智能体；可选步骤可以跳过。

运行时配置文件会自动设置。Quickstart 会为新代理安装 unbounded 预设。之后可通过编辑 [runtime_profiles.<alias>] 来调整预算和超时设置（参见 Reference → Config）。

命令行界面

在无头机器上或通过 SSH 操作时最快的路径：

zeroclaw quickstart

你可以在终端中每步回答一个提示。内置的 cli 通道可立即使用，因此可以跳过 Channels 和 Peer groups。如需全部使用默认值、无需审批的配置，请参阅 YOLO mode。

OpenAI Codex 订阅认证

Quickstart 可以在无需 API key 的情况下配置 OpenAI Codex 订阅路径。先进行一次身份验证，然后在提示时选择 OpenAI 作为提供方，并将 Authentication 设置为 codex：

# 如果你已经使用 Codex CLI 登录：
zeroclaw auth login --model-provider openai-codex --import ~/.codex/auth.json

# 或启动 ZeroClaw 自己的 OpenAI Codex 登录流程：
zeroclaw auth login --model-provider openai-codex

对于脚本化设置，openai-codex 被接受为快速入门输入别名，并会写入规范的 [providers.models.openai.<alias>] 条目：

zeroclaw quickstart --model-provider openai-codex --model gpt-5.4 --agent assistant

Claude 订阅设置令牌认证

Quickstart 也可以使用普通的 Console API key 或 Claude Max 生成的 token 来配置 Claude/Anthropic：

claude setup-token
zeroclaw quickstart --model-provider anthropic --model claude-sonnet-4-5 --agent assistant

选择 Anthropic，将 Authentication 设置为 setup_token，然后把 claude setup-token 中的令牌粘贴到 API key/token 提示中。脚本化输入可以使用 --model-provider claude 作为别名。Quickstart 仍会写入规范的 [providers.models.anthropic.<alias>] 条目；该令牌通过与 api_key 相同的凭据路径存储。

插件

为启用 WASM 插件支持的构建，在 CLI 清单中于 对等组之后添加一个可选的 插件 行。只有当二进制文件使用 plugins-wasm 特性构建时，该行才会出现。当前发布的归档包未包含此特性，因此其清单中没有插件行；使用 --preset full 的源码构建以及 all-features 容器镜像都会包含该行。目前只有 CLI 快速入门提供该行，zerocode 和 Web 网关快速入门暂未列出插件。未访问该行不会产生任何影响。

打开此行会获取插件注册表索引，即 zeroclaw plugin search 所使用的同一份索引（设置 ZEROCLAW_PLUGIN_REGISTRY_URL 可使用其他注册表），并列出注册表提供的或本机已有的所有工具插件，同时标记已安装的插件。如果无法获取注册表索引，您可以重试，或在没有插件的情况下继续。选择插件不会下载任何软件包，也不会更改任何配置。打开此行仅会像 zeroclaw plugin search 一样，将注册表索引缓存写入数据目录；如果插件目录不存在，则会创建该目录。

如果 Quickstart 无法读取配置文件中的 [plugins] 部分（因为该部分或整个文件格式错误），该行会显示这一信息，而不是去获取注册表。它不提供任何可选项，Create 也不会安装任何插件。请修复该文件，然后重新运行 Quickstart 以安装插件。

如果配置文件由较早版本的 ZeroClaw 写入，Create 会在安装任何插件或创建智能体之前停止，并打印用于更新该文件的 zeroclaw config migrate 命令，zeroclaw plugin bind 也是如此。运行该命令，然后再次运行 Quickstart。将插件设置保存到旧文件中会将其标记为当前版本，却不会迁移其中较旧的设置，之后的运行便会停止读取这些设置。

当你选择 Create 时，Quickstart 会在创建智能体之前安装所选插件。它首先会按照智能体步骤的方式，检查你的其余选择以及这些选择将写入的配置，包括智能体步骤在写入任何内容之前运行的授权检查。如果智能体步骤会拒绝这些选择（例如某个权限配置文件指向了已不存在的智能体），Quickstart 会报告问题，并在下载或写入任何插件之前停止。然后，它会通过 zeroclaw plugin install 所使用的流水线逐个安装插件：

1. 它会从注册表解析软件包，并在请求压缩包之前，拒绝其压缩包没有 sha256 摘要的注册表条目。zeroclaw plugin install 仅在注册表列出摘要时才校验摘要；快速入门要求必须提供摘要。
2. 它会下载并校验归档文件，确认 manifest 提供了工具，准入该软件包，检查其配置条目是否可以预置，并运行安装时加载检查。上述任一步骤失败时，Quickstart 会报告失败原因，不为该插件写入任何内容，然后继续处理下一个插件。例如，若配置中仍保留该插件的 pre-1.0 条目（仅以软件包名称命名），而 zeroclaw plugin remove 会保留该条目，则配置条目检查会失败：zeroclaw plugin install 拒绝在其旁边创建条目，Quickstart 会在询问该插件的任何问题之前报告相同的原因。Quickstart 没有 --no-verify：对于未通过加载检查的插件，它会打印 zeroclaw plugin install <name> --no-verify 命令，该命令会安装一个守护进程在启动时跳过的插件。该命令属于插件 CLI，而非 Quickstart：它不会询问签名问题或网络访问问题。由它创建的配置条目会以 manifest 为 http_client、websocket_client 或 socket_client 声明的目标地址进行预置。
3. 它会打印该插件的基本信息及其请求的内容：名称、版本、作者、描述、功能（capabilities）、权限（permissions），以及其清单文件中声明的网络目标地址。发布者提供的文本会先去除终端控制序列。
4. 它会将清单签名与 plugins.security.trusted_publisher_keys 进行比对，无论 plugins.security.signature_mode 的取值如何，并在摘要中添加一行：已验证（附受信任密钥的前 16 个字符）；未签名；使用不受信任的密钥签名；或无效。除非签名已验证，否则作者一行会标注为发布者自述，并且 Quickstart 会在询问该插件的其他问题之前，先询问是否仍要安装。默认答案为否，此时将跳过该插件且不写入任何内容。signature_mode 仍决定准入机制拒绝什么：在 strict 模式下，此类插件会改为在第 2 步被拒绝。当 Quickstart 能够读取插件目录时，已选插件若已安装，则会显示同样的一行，且不再询问。
5. 对于请求网络传输（http_client、websocket_client 或 socket_client）并声明了目标地址的插件，你可以选择授予所声明的目标地址、在无网络访问的情况下安装，或跳过该插件。选择从“在无网络访问的情况下安装“开始，因此直接接受该默认选项不会授予任何权限。在无网络访问的情况下安装会创建插件的配置条目，其中 egress_hosts 为空，因此插件无法访问任何目标；同时会打印稍后授予所声明目标地址所用的精确 zeroclaw config set 命令。这与 zeroclaw plugin bind --egress none 为通道实例记录的决定相同，并会打印相同的命令。对于请求网络访问但未声明任何目标地址的插件，不会出现提问；安装后，Quickstart 会为该条目的 egress_hosts 打印一条不带值的 zeroclaw config set --no-interactive 命令。请将部署所使用的主机以逗号分隔的一个值追加到该命令后面。若按原样运行该命令，会因缺少值而被拒绝，且不会写入任何内容。
6. 对于清单中包含 config_schema 的插件，快速入门会提示输入其描述的设置项：先提示必填属性，可选属性仅在您选择时才提示。标记为 x-secret 的属性在输入时会被掩码显示，并且与 zeroclaw config set 一样，会去除敏感值前后的空格或换行符。从列表中选择的值会按 schema 中列出的内容原样存储，包括空字符串；而手动输入的空答案会使可选设置保持未设置状态。在写入任何内容之前，系统会根据 schema 校验这些值；校验失败后可再尝试一次，之后快速入门会询问是否在不配置这些设置的情况下安装该插件。在必填的敏感设置或列表选择设置处按 Esc 键，将跳过该插件。快速入门仅针对名称符合可移植键语法（最多 128 个 ASCII 字母、数字、.、- 和 _）的属性进行提示。对于其他属性，它会列出名称，以便您稍后使用 zeroclaw config set 进行设置。如果必填属性属于上述情况，或者是 schema 要求但未声明的名称，则没有任何答案能通过校验，因此快速入门不会询问任何设置项，而是直接询问是否在不配置这些设置的情况下安装该插件。当 schema 要求了一个它未声明的名称时，无论 zeroclaw config set 写入什么，都无法满足该要求，因此该问题会说明该插件的工具将无法使用，并询问是否仍要安装。
7. 它会在与 zeroclaw plugin install 相同的事务中发布软件包并写入其配置条目，然后以 zeroclaw config set 的方式保存设置。如果写入配置条目失败，事务会再次移除该软件包。如果移除也失败，Quickstart 会提示该插件仍已安装，并打印针对它的 zeroclaw plugin remove 命令。如果保存设置失败，插件保持安装状态，Quickstart 会为每个设置打印一条 zeroclaw config set 命令，用于询问对应的值。对于同时提供通道的插件，会输出 zeroclaw plugin install 为其打印的内容：用于绑定实例的 zeroclaw plugin bind 命令，或已绑定该软件包的别名的就绪状态。Quickstart 自身不绑定任何通道实例。

对于未标记 x-secret 的设置，你输入的值会在提示处回显，schema 中的默认值也会预先填入该处。设置值绝不会写入日志，也不会写入 Quickstart 打印的状态行；这些状态行只列出设置的名称。

已安装的插件不会被重新下载、升级，也不会再次提示配置设置。Quickstart 仅在配置条目缺失时才创建该条目。新建条目即意味着一次新的授权，因此对于请求网络传输并声明了目标地址的插件，你需要先查看插件信息，然后做出与全新安装相同的选择：授权声明的目标地址、创建不带网络访问权限的条目，或跳过。跳过会使条目保持不存在，并打印稍后用于创建该条目的命令。该命令创建的条目不带网络访问权限。用于授权声明目标地址的命令会单独占一行打印，需在其之后运行，因此运行打印出的命令绝不会授予你已拒绝的权限。其他缺失的条目按 zeroclaw plugin install 的方式进行初始化。已有的条目永远不会被更改，无论它属于已安装的插件，还是由之前的安装遗留下来的，因此其出站访问授权和设置都保持原样。因此，使用相同选择再次运行 Quickstart 不会下载任何内容，也不会改动这些条目。如果 Quickstart 无法完成对已安装插件的设置，例如配置中仍保存着仅以软件包名称命名的 1.0 之前版本条目，或保存新条目失败，则不会为该插件写入任何内容，并说明该插件仍保持安装状态及原因。

在最后一个插件之后，如果至少有一个所选插件已安装，并且 plugins.enabled 或 plugins.auto_discover 处于关闭状态，快速开始会询问一次是否开启插件激活。它会先列出哪些设置将被更改，以及由此会激活的所有内容：每个已安装的工具和技能插件，包括本次运行之前已安装的插件；当 plugins.enabled 处于关闭状态时，还包括每个已启用的 [channels.plugin.<alias>] 渠道。该列表读取自插件目录，即守护进程在下次启动时加载它的方式，因此它也会列出安装失败且无法撤销的插件。每个签名未经验证的已列出插件，后面都会跟随第 4 步中的签名行，包括本次运行未选择的插件。如果列出的插件与本次运行安装或保留的插件一致，则默认回答为是；如果它会激活其他任何内容，则默认回答为否，其中包括你选择跳过缺失配置项的已安装插件，或快速开始无法完成设置的插件。如果无法读取插件目录，快速开始会提示列表可能不完整，默认回答为否。拒绝后，两项设置保持不变，并会打印 zeroclaw config set 命令，供你稍后手动开启这些设置。如果两项设置均已开启，则不会进行询问。

安装代理后，Quickstart 会打印每个已选插件（且已安装）的状态：是否已作为工具被接纳，以及对应的配置条目键；若未被接纳，则给出原因，例如 plugins.enabled 或 plugins.auto_discover 处于关闭状态，或已达到 plugins.max_active_instances 上限。只有当插件的配置条目通过运行时在每次调用时执行的设置检查，才会被报告为已接纳。已接纳并不等于已注册：工具注册表会在下次构建时注册该插件；若插件包的名称与已注册的工具（例如内置工具）冲突，或注册表无法读取其工具描述，注册表仍会拒绝该插件包。运行时日志会记录这些拒绝情况。

如果设置检查失败，例如安装插件时未提供其所需的设置，则状态会显示检查给出的原因，列出缺失的必需设置名称，并打印用于逐个填写这些值的 zeroclaw config set 命令。Quickstart 只会为符合可移植键语法的设置名称打印命令，这些名称可以安全地显示并粘贴到 shell 中。名称不符合该语法的必需设置只会被列出，不附带命令：请在配置文件中设置，或者自行加引号后使用 zeroclaw config set 命令。插件的 schema 未声明的必需名称也会被列出，因为在插件发布者修正 schema 之前，任何配置条目都无法满足该 schema。

如果插件的配置条目缺失（例如你跳过了创建该条目），其状态也不会报告为已激活。zeroclaw config set 只会修改已存在的条目，因此状态会改为打印用于创建该条目的命令。该命令不授予任何网络访问权限；对于请求网络传输并声明了目标地址的插件，会另起一行给出条目存在后用于授予这些目标地址的命令。

如果配置中仍保留该插件的 1.0 之前版本条目（仅以包名命名），其状态既不会打印上述命令，因为在旧条目旁边新建条目会导致旧条目的设置和网络授权被遗留。状态会改为指明应将旧条目重命名为的实例键。当 zeroclaw plugin list 为该条目打印更新步骤时（对于带有网络传输的插件，除非部署拒绝所有插件的网络授权，通常都会打印），状态还会给出该命令：其步骤包括重命名后的条目仍需要的任何网络授权。没有可配置项且不需要网络访问的插件无需配置条目。

已选择的插件如果之前就已安装，可能从未通过加载检查，例如使用 zeroclaw plugin install --no-verify 安装时。因此，Quickstart 会在报告插件状态之前运行 zeroclaw plugin info 所执行的检查。如果插件无法在当前主机上加载，ZeroClaw 会在启动时跳过它，其状态会显示为已跳过而非“已激活“，并给出用于查看原因的 zeroclaw plugin info 命令。

Quickstart 会写入配置文件，但不会通知正在运行的守护进程。已运行的守护进程保留其加载时的配置，因此 Quickstart 运行写入的配置条目、设置、网络授权和插件激活变更，只有在守护进程重启或重新加载配置后才会生效。如果守护进程加载的配置中插件激活已开启，它会在下次构建工具注册表时（例如为新会话构建），加载新安装的插件。此时，它使用加载时已有的该插件配置条目来运行插件，而不是本次运行写入的条目。若没有该条目，插件将没有设置和网络授权；而较早的条目（例如 zeroclaw plugin remove 从早前安装中保留下来的条目）则会以其设置和网络授权生效。状态信息末尾会给出面向同一配置目录的 zeroclaw service restart 命令，用于重启以已安装服务方式运行的守护进程。zeroclaw agent 及其他一次性命令会在下次启动时获取这些变更。

Ctrl+C 在插件步骤中的行为并不统一。在密钥设置项中，它的作用与 Esc 相同；在必填设置项中，它会取消该插件的设置，从而跳过该插件，然后快速入门继续进行；在可选设置项中，它会让该设置保持未设置状态。步骤中的其他任何位置，Ctrl+C 都会立即结束快速入门，且不会给出已完成操作的摘要。已完成安装的插件会保持已安装并已配置的状态，zeroclaw plugin list 会显示该插件。如果插件在安装完成后、配置条目写入前被中断，它会保持已安装状态但没有该配置条目；使用相同选择再次运行快速入门时会创建该条目，并且在需要授予网络目标权限时会先询问。

如果在插件步骤已经做出更改后，Agent 步骤仍然失败，快速开始不会声称没有任何更改。它会列出仍保持已安装、已配置或已激活状态的插件，并为本次运行中安装的每个插件打印 zeroclaw plugin remove 命令，包括安装失败且无法撤销、因此仍保留在插件目录中的插件。再次运行快速开始不会重新安装这些插件。

架构路线图（FND-001、RFC #5574、交付物 D4）要求 zeroclaw onboard 支持安装插件。zeroclaw quickstart 是 zeroclaw onboard 现在指向的维护命令，在支持插件的构建版本中，它已为工具插件实现了这一功能。在引导过程中安装通道插件，以及发布支持插件的发行产物，是各自独立的交付物。

zerocode

在 zerocode 终端界面中，Quickstart 窗格是其中一个选项卡。使用键盘来操作它：

切换到 Quickstart 窗格：

您也可以在智能体侧边栏中选择**» Quickstart**。按下 Esc 可返回打开 Quickstart 的窗格，无论您是从键盘模式栏、点击模式栏还是侧边栏启动器进入的。

窗格内：

鼠标同样可用：单击模式栏中的标签页可切换窗格，单击某个步骤可选中并打开它，滚动则可在列表中移动浏览。

每个步骤都会打开一个与上述清单相对应的模态框，其中包含一个“使用现有”选项，该选项会列出配置中已匹配的别名。

Web 网关

在守护进程运行的情况下，在浏览器中打开仪表板：

zeroclaw daemon

zeroclaw daemon 运行完整的运行时：网关、你配置的通道、调度器以及心跳监视器。（如果你只需要 HTTP 网关，可使用 zeroclaw gateway 仅启动它。）

然后访问 http://127.0.0.1:42617/quickstart。全新安装且未配置任何 agent 时会自动重定向到该页面；之后你随时可以从仪表板导航中访问它。

Web 表单以卡片形式呈现相同的步骤。提交时，它会通过守护进程应用你的提交内容（POST /api/quickstart/apply），如果有任何无效内容，将返回结构化的错误列表，然后就地重新加载守护进程，使新代理无需重启即可生效。另有一个独立的 POST /api/quickstart/validate 端点，可在不应用的情况下运行相同的检查，供希望先验证的客户端使用。

快速入门后

• 通过 zerocode 操作： 终端界面是聊天、查看实时日志、管理配置和监控守护进程的最佳方式，所有功能集于一处。只需运行 zerocode。
• 从 shell 快速执行一次性操作： zeroclaw agent -a <alias> -m "your message"。
• 始终运行： zeroclaw service install && zeroclaw service start。
• 稍后添加渠道： 渠道 → 概述。
• 调整自主性和预算： 参考 → 配置。