如何安装ZeroClaw：轻量级OpenClaw替代品的初学者友好快速入门指南

为什么值得安装 ZeroClaw

如果你曾经安装过 AI 工具，看着二进制文件落在你的 “PATH” 中，但仍然没有证据证明它能够到达模型、理解其工作区或安全地回答问题，你已经理解了本指南要解决的问题。完成的安装只能证明文件被复制了。它不能证明代理运行时是可用的。

这就是 ZeroClaw 变得有趣的地方。它是一个轻量级 AI 代理运行时，围绕单个 Rust 二进制文件构建，从第一天起就支持托管模型提供商，而不是沉重的本地堆栈。实际上，这意味着它更接近”受控工具使用运行时”而不是”终端中的聊天机器人”。对于对”OpenClaw 替代品”角度感到好奇的读者，实际吸引力不是炒作或基准。它是更轻的安装故事、更低的依赖权重，以及在 Ubuntu VPS 上测试它感觉可管理而不是变成完整基础设施项目的事实。

本文紧紧聚焦于一个结果：安装 ZeroClaw，运行 “zeroclaw onboard”，验证安全的第一个 CLI 会话，并留下对下一步尝试的现实想法。这是初学者友好的 VPS 演练的正确第一个里程碑，因为”工作”应该意味着你可以检查的有根据的第一个响应，而不是冗长的功能导览。

📝 注意：本指南证明了第一个工作 CLI 使用。它不是生产部署指南，也不尝试涵盖 Docker、公共网关或后台服务

什么是 ZeroClaw — 用简单英语

ZeroClaw 更好地理解为代理运行时而不是”AI 聊天机器人”。模型只是系统的一部分。ZeroClaw 是连接提供商账户、模型选择、代理配置文件和有界工作区的层，使工具能够做的不仅仅是孤立地回答一个提示。

以下四个术语是本教程中最重要的：

工作区的想法比听起来更重要。在本文中，工作区是代理被允许工作的房间。这就是为什么安装 ZeroClaw 与配置 ZeroClaw 不同：二进制文件可以存在于磁盘上，而提供商、模型、别名和工作区仍然缺失或接线错误。

📝 注意：成功的安装只是故事的一半。有意义的里程碑是 ~/.zeroclaw 下的工作配置，可以到达提供商并在可见的工作区内运行。

这也是解释为什么有些人将 ZeroClaw 视为 OpenClaw 替代品而不强制进行完整比较的最干净方式。价值不是”用 Rust 重写的 OpenClaw”，本指南也不这样对待它。价值是更轻的自托管态势、提供商灵活性和易于在 VPS 上尝试的单二进制运行时。

同样有根据的好第一用例：总结安全的回购副本、解释配置文件、在低风险工作区内处理只读辅助任务，或将其用作想要在允许任何真实更改之前获得可见性的操作员的有界助手。

安装前：Ubuntu 基线、先决条件和安全

在运行安装程序之前，花一分钟时间确认 VPS 确实适合本文使用的路径。最低要求很简单：SSH 访问 Ubuntu VPS、curl、一个具有 API 密钥的托管提供商账户，以及用于第一个会话的低风险机器或工作区。

首先运行以下检查。在显示的验证运行中，它们返回了 Ubuntu 24.04.4 LTS（Noble Numbat）、x86_64 和 /usr/bin/curl。这足以确认指南的基线，而不假装每个服务器都会返回相同的输出。

cat /etc/os-release

uname -m
command -v curl

对于托管提供商示例，OpenRouter 是最干净的默认值，因为它使演练 VPS 友好，避免了服务器上的本地模型设置。如果你已经使用另一个支持的提供商，没关系，但在 zeroclaw onboard 开始提问之前准备好 API 密钥。这里的目标是第一次成功，而不是提供商购物，所以一个干净的托管路径比尝试在同一个会话中评估每个提供商更好。

ZeroClaw 支持预构建和源安装路径。将预构建路由视为现成的设备，将源路由视为自己构建的工具包。两者都是合法的，但它们服务于不同的读者。对于本快速入门，重要的是现在理解差异并在安装步骤中做出实际建议。

⚠️ 警告：在继续之前使用此首次运行检查清单：

• 留在低风险工作区
• 保持默认监督行为
• 避免公开暴露和生产数据
• 有意在第一个任务上进行只读

使用官方脚本安装 ZeroClaw

飞行前检查完成后，使用官方安装程序作为主要路径。这是 Ubuntu VPS 快速入门的最短支持路由：

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

在此安装路径上，脚本以非交互方式运行并自动采用预构建发布路径。在本指南的验证运行中，它检测了 Linux 目标，下载了匹配的 GitHub 发布 tarball，验证了校验和，在 ~/.local/share/zeroclaw/web/dist 下安装了 web 仪表板资产，并将 zeroclaw 二进制文件放在 ~/.cargo/bin 中。因为屏幕截图是从 root 账户捕获的，所示的具体路径是 /root/.local/share/zeroclaw/web/dist、/root/.cargo/bin/zeroclaw 和 /root/.bashrc；在常规用户账户上，期望在你自己的主目录下有相同的布局。

那个快速路径不是快捷方式或不太官方的安装。它是本指南所写受众的正常快速入门路由：下载匹配的发布、验证它并将二进制文件放在 ~/.cargo/bin/zeroclaw 中。如果你有意想要源构建，使用下面的 repo-clone 路径而不是期望此安装程序流停止并提供单独的构建选择。

💡 提示：在 Linux 上，最常见的安装后问题是 PATH，而不是安装本身。按照安装程序的建议将 export PATH=”$HOME/.cargo/bin:$PATH” 添加到你的 shell 配置文件中，并使用 source ~/.bashrc 重新加载它（或重新打开 shell）。如果你只需要当前会话的临时修复，使用下面显示的单行导出。

二进制文件就位后，脚本以非交互式确认消息完成，而不是自动启动设置。在本指南的验证运行中，该关闭消息指向 zeroclaw quickstart，但安装的”v0.7.5″二进制文件在 zeroclaw –help 中将 onboard 作为实际设置子命令公开。它还指出 zeroclaw daemon 是始终开启的守护程序加 web 仪表板的路径，而 zeroclaw agent 是一次性 CLI 聊天路径。

对于本文，接下来继续使用 zeroclaw onboard。这使演练与文章的实际承诺保持一致：终端中的第一个工作代理会话，而不是仪表板配对或始终开启的运行时。

如果你是安全意识强的人，更喜欢在运行安装程序之前检查它，使用此替代方法：

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

在考虑提供商或提示之前，验证二进制文件在 shell 中是否可调用：

zeroclaw --version

如果有效，安装本身成功了。如果 shell 说 command not found，应用下面的临时 PATH 修复并再次测试：

export PATH="$HOME/.cargo/bin:$PATH"

将此步骤与配置分开很重要。工作的 zeroclaw –version 告诉你安装程序问题在开始调试提供商设置之前已解决。

运行 zeroclaw onboard 并检查它创建的内容

这是”已安装”需要变成”已配置”的点。在上面使用的非交互式安装路径上，脚本明确跳过设置提示。如果安装程序消息提到 zeroclaw quickstart 但二进制文件不识别它，信任 zeroclaw –help 并使用以下命令启动首次运行向导：

zeroclaw onboard

向导在工作区屏幕上打开。在捕获的运行中，默认工作区路径是 /root/.zeroclaw/workspace。除非你有强烈的理由移动它，否则接受默认值。在非 root 账户上，相同的布局将存在于你自己的主目录下。

对于此初学者 CLI 演练，保持多工作区配置文件禁用。打开它会为每个参与创建单独的内存、机密和审计目录，这稍后可能很有用，但它为首次烟雾测试增加了额外的心理开销。

在提供商屏幕上，选择 OpenRouter。列表比初学者指南需要的要大得多，这正是为什么帮助选择一个干净的托管路径并坚持第一次运行是有帮助的。

出现提示时粘贴你的 OpenRouter API 密钥。输入是隐藏的，提示明确指出 ZeroClaw 在可能的情况下通过 OS 密钥环存储机密，而不是要求你将其硬编码到 config.toml 中。

OpenRouter 模型列表很长。在捕获的运行中，选择了 deepseek/deepseek-v4-pro。如果你愿意，可以选择另一个当前的 OpenRouter 模型，但本演练的其余部分遵循该确切选择。

当向导询问高级设置时，为本指南关闭它们。打开它们用于有针对性的覆盖，例如温度、超时、基础 URL 或线路协议。

在”频道”屏幕上，选择 完成，不添加 Discord、Telegram、Slack 或任何其他外部表面。这使第一个验证仅限 CLI。一旦本地代理路径有效，你可以稍后添加频道。

对于内存，选择 SQLite with Vector Search (recommended)。这是这里最强的默认值，因为它在保持一切本地的同时仍然为你提供混合搜索和嵌入支持。

将 自动保存 设置为 是，以便你自己的提示被记录为对话历史。如果你稍后想要更严格的手动控制，你可以关闭它并仅显式保存内存。

保持硬件控制禁用。此 VPS 设置不需要 GPIO、USB 系绳板或调试探针。

对于公共隧道提供商，将其保持为 无。这与本文的安全态势相匹配：在首次烟雾测试期间不公开暴露。

当”个性”步骤说它已配置时，将 重新配置？ 保持为 否。默认个性足以进行首次运行验证。

这里重要的不是记住每个向导面板。重要的是屏幕截图证明的路径：单个工作区、OpenRouter 提供商、隐藏的 API 密钥输入、具体的模型选择、无高级覆盖、无额外频道、本地 SQLite 内存、自动保存开启、硬件关闭、无公共隧道和无个性重写。这足以在 ~/.zeroclaw 下生成可用的第一个 CLI 配置。

入职完成后，确认主配置目录和工作区存在：

如果入职运行顺利完成，你应该使用类似于下面的配置加载消息返回到 shell：

ls ~/.zeroclaw
ls ~/.zeroclaw/workspace

在捕获的运行中，~/.zeroclaw 包含 config.toml 和 workspace/，工作区本身显示 IDENTITY.md 和 SOUL.md。

这已经足以证明 ZeroClaw 现在有一个操作室，而不仅仅是一个已安装的二进制文件。这也是为什么工作区类比很有用：你正在检查房间是否存在，代理是否在其中有上下文，以及设置是否超越了”安装程序完成”。IDENTITY.md 和 SOUL.md 等文件不是装饰性的。它们是 ZeroClaw 用来理解它在该工作区内应该如何表现的上下文的一部分。

在第一个实时提示之前，运行紧凑的健康检查：

zeroclaw status

zeroclaw doctor

对于此首次仅 CLI 烟雾测试，如果 zeroclaw doctor 不完全干净，不要惊慌。在捕获的运行中，重要的检查通过了：找到了配置文件、openrouter 提供商有效、API 密钥已配置、设置了默认模型、工作区存在且可写。

其余的警告和错误对于终端聊天并不关键：”未配置频道”是预期的，因为演练有意跳过了 Discord、Telegram 和其他外部频道；未找到 AGENTS.md（可选） 明确是非阻塞的；未找到 daemon_state.json 仅意味着始终开启的守护程序尚未运行；OpenRouter 实时模型列表投诉最好理解为探针限制而不是提供商设置失败的证明，特别是因为输出仍然报告 openrouter: 344 models。

grep -E 'default_provider|default_model|[agents.|[risk_profiles.' ~/.zeroclaw/config.toml

这里的成功信号是操作性的，而不是装饰性的。zeroclaw status 是活跃运行时摘要的最清晰的真实来源，zeroclaw doctor 告诉你是否有任何重要的东西坏了，grep 输出最好被视为对提供商/模型相关配置条目的粗略查看，而不是完美的。期望措辞和确切匹配因版本而异。你不是在寻找完美的绿色文本墙。你在寻找首次运行阻塞程序的缺失和真实配置数据的存在。

📝 注意：config.toml 可能不会以纯文本显示你的 API 密钥。这可能是正常的。在捕获的入职运行中，API 密钥提示明确说机密将在可能的情况下通过 OS 密钥环存储，所以”TOML 文件中没有可见密钥”与”设置失败”不是同一回事。

开始第一个安全的 CLI 聊天

配置和工作区就位后，以交互模式启动代理：

zeroclaw agent

在捕获的运行中，ZeroClaw 加载了配置、初始化了 SQLite 支持的内存、打印了交互模式横幅，并下降到 > 提示。目标不是启动闪亮的演示。目标是在一个低风险步骤中证明端到端连接、有效配置和有根据的工作区意识。只读测试在此阶段给你远比可写”看看它能做什么”提示更有用的信号。

对于第一个提示，使用此确切的只读检查：

tell me your current workspace path, list the top-level files you can see there, and briefly explain what each one is for. Do not create, edit, or delete anything.

因为运行时处于监督模式，第一个有用的回复可能需要工具批准。在捕获的运行中，ZeroClaw 要求执行只读 shell 命令：“pwd && echo “—-” && ls -la”

这正是你想要的这个烟雾测试的命令类型：它打印工作区路径并列出顶级内容，而不改变任何东西。用 Y 批准一次性是。你也可以用 N 拒绝它，但那样代理会失去从真实文件系统状态而不是猜测回答问题的最简单方式。

📝 注意：你也可能在批准提示之前看到所选 OpenRouter 模型的成本跟踪警告。在捕获的运行中，ZeroClaw 警告说没有为 openrouter/deepseek/deepseek-v4-pro 定义定价条目。这不会阻止聊天本身。它只意味着令牌使用可能会以零成本记录，直到你明确定义模型定价。

这个提示很强，因为它同时测试三件事。首先，ZeroClaw 必须到达提供商并获得响应。其次，代理必须理解配置的工作区。第三，答案必须具体到足以与磁盘上的实际情况进行比较。换句话说，这证明了代理停留在给定的房间内。

一个好的第一个回复应该满足四个条件：

• 没有身份验证或提供商错误
• 没有”未找到配置”或缺失模型故障
• 正确的工作区路径出现在答案中
• 真实的顶级文件被命名，没有声称任何东西被改变

如果你想要一种不同的方式来调用代理，你可以将相同的提示作为一次性命令发送，而不是停留在交互式会话中。将此视为可选的，而不是主要演练。交互路径仍然是更好的首次体验，因为它使运行时感觉可观察而不是神奇。

zeroclaw agent -m "tell me your current workspace path, list the top-level files you can see there, and briefly explain what each one is for. Do not create, edit, or delete anything."

ZeroClaw 工作后该做什么

正确的下一步不是打开你能找到的每个功能。它是一次添加一个受控层，所以你总是知道哪个更改引入了新风险或新摩擦。

💡 提示：一旦第一个安全聊天有效，为下一个阶段保持相同的纪律。首先移到安全的回购副本或笔记目录，尽可能保持任务只读，并仅在基本工作流感觉可预测后扩展权限。

好的后续任务有意很无聊：总结 README、解释配置文件或列出清理想法而不改变任何东西。这种工作是高信号，因为它使用你刚刚验证的相同运行时，但在你信任该工具之前不会强制你进入写访问。如果你想要更好的第一个真实工作区，使用安全的回购副本、暂存笔记目录或小型内部文档文件夹，而不是任何面向生产的东西。

好的下一步，按顺序，看起来像这样：

• 将 ZeroClaw 指向安全的回购副本或笔记目录
• 尝试一个只读辅助任务
• 仅在基本工作流感觉稳定后比较提供商
• 稍后将服务、频道或 Docker 视为单独的项目

如果你想稍后比较提供商，请在基本工作流稳定后进行。如果你想要 CLI 成功后的下一个基础设施步骤，这些是值得了解的命令：

zeroclaw service install
zeroclaw service start
zeroclaw service status

这是本文应该停止的地方，下一个主题应该开始的地方。服务管理、Docker 部署、公共网关、消息频道和更深层的安全加固应该有自