Key Takeaways
- ClawHub Quickstart 的目标是先跑通最小可用流程，不是一次性配置所有功能。
- 安装前要确认 Windows、WSL2、Docker、网络访问和项目目录权限。
- 第一个 Agent 任务要从低风险测试开始，先看日志、状态和输出，再扩展 Skills。
ClawHub Quickstart 可以理解为“从零到第一个 Agent 任务”的最短路径。它适合已经准备好本地环境，想验证 ClawHub 是否能启动、是否能调用基础能力、是否能跑完一个简单任务的用户。
先验证好。
再继续。
别跳步。
先看日志。
再看结果。
最后复盘。
少猜测。
不要把 Quickstart 当成完整生产部署。它的作用是验证环境、流程和日志是否可用。等最小任务跑通后，再考虑 AgentSkills Skills、ClawHub Skills、自托管部署和团队级权限管理。
ClawHub Quickstart 开始前要准备什么
开始 ClawHub Quickstart 前，先做环境检查。Windows 用户重点看 WSL2 和 Docker。Linux 或 macOS 用户也要确认 Docker、网络和项目目录权限。微软官方 WSL 安装说明可参考 Install WSL，Docker Desktop Windows 安装说明可参考 Docker Desktop on Windows。
基础检查可以按这张表执行：
| 检查项 | 命令或动作 | 通过信号 |
|---|---|---|
| WSL2 | wsl --status |
能看到默认发行版和版本信息 |
| Docker | docker version |
Client 和 Server 都有输出 |
| Compose | docker compose version |
能看到版本号 |
| 目录权限 | 在项目目录新建文件 | 能正常读写 |
| 网络访问 | 访问 GitHub 和依赖源 | 不持续超时 |
如果其中一项不通过，不要继续执行 Quickstart。先修基础环境。否则后面的问题会混在一起，很难判断是 ClawHub 问题、Docker 问题，还是网络问题。
ClawHub Quickstart 的安装顺序
ClawHub Quickstart 建议按“系统环境 → 依赖工具 → 项目目录 → 配置文件 → 启动验证”的顺序走。顺序清楚，排查就简单。顺序混乱，最容易出现重复安装、路径错误和端口冲突。
可以用下面的步骤作为安装骨架：
- 确认 Windows、WSL2 或 Linux 环境可用。
- 安装并启动 Docker，确认 `docker compose` 可用。
- 把项目放到简单目录，例如 `D:\projects\clawhub`。
- 按文档准备配置文件和环境变量。
- 启动服务，观察终端日志。
- 打开本地访问地址，确认页面或接口可用。
这里最重要的是“先验证，再扩展”。如果本地服务还不能稳定启动，就不要急着加复杂模型配置、外部服务或自托管策略。ClawHub Quickstart 的第一目标是让最小路径跑通。
第一个 Agent 任务怎么选
第一个 Agent 任务要足够简单。不要一开始就让它登录账号、发布内容、操作复杂网页或调用多个外部系统。更合理的测试任务是：读取一段输入，生成一个计划，执行一个低风险动作，输出可检查结果。
可以选择这几类任务：
| 任务类型 | 为什么适合第一个任务 | 不建议一开始做 |
|---|---|---|
| 文本整理 | 输入输出清楚，容易验证 | 多平台发布 |
| 页面信息读取 | 风险低，便于看日志 | 登录后批量操作 |
| 简单工作流 | 能验证步骤顺序 | 高权限写入 |
| Skills 调用测试 | 能检查工具链 | 复杂自托管集成 |
如果你后续要把 Agent 任务接到业务执行层，可以参考 Jumei 的 工作方式 和 自动化运营。一个原则很重要：先让任务可解释，再让任务自动化。
ClawHub Quickstart 的最小任务示例
第一个任务可以设计成“读取一段运营需求，并输出三步执行计划”。这个任务不需要登录平台，不需要写入外部系统，也不需要操作真实账号。它能验证三件事：Agent 能否接收输入，能否完成推理，能否把结果写到可查看的位置。
示例输入可以这样写：
请把下面的社媒运营需求整理成 3 个执行步骤：
目标平台：TikTok
账号数量：3 个
任务目标：准备下周内容发布计划
限制：不要执行真实发布，只输出计划
示例验收标准要提前写好：
| 验收项 | 通过标准 |
|---|---|
| 输入接收 | 任务日志能看到完整需求 |
| 计划生成 | 输出包含平台、账号和步骤 |
| 风险控制 | 没有触发真实发布或登录动作 |
| 结果保存 | 页面、日志或文件里能复查结果 |
这个例子看起来很小，但它能把 Quickstart 的核心链路验证一遍。后续再加入 ClawHub Skills 或 AgentSkills Skills，就有了对照基线。
ClawHub Quickstart 运行时怎么看日志
日志是 Quickstart 阶段最重要的反馈。新手常见问题是只看页面有没有打开，不看终端输出。页面能打开不代表任务链路完整，任务失败也不一定会直接显示在页面上。
建议至少看三类日志：
| 日志类型 | 重点看什么 |
|---|---|
| 启动日志 | 服务是否正常启动，端口是否被占用 |
| 任务日志 | Agent 是否收到任务，步骤是否执行 |
| 错误日志 | 缺配置、缺权限、网络失败还是容器失败 |
遇到错误时，先复制完整错误信息。不要只截最后一行。很多关键原因会出现在前几行，例如配置文件缺失、依赖下载失败、端口已经被占用。
建议把每次 Quickstart 运行结果写成一条记录。字段可以包括：执行时间、启动命令、访问地址、任务名称、输出位置、错误摘要、下一步处理人。这样团队内交接时，不会只剩一句“我这里跑不起来”。
Quickstart 结果应该怎么记录
ClawHub Quickstart 跑通后，最好不要只在聊天里说“成功了”。团队应该留一份最小运行记录。它以后会变成排查、交接和复现的依据。
可以记录这些字段：
| 字段 | 填写示例 | 用途 |
|---|---|---|
| 机器环境 | Windows 11 / WSL2 / Docker Desktop | 判断环境差异 |
| 项目路径 | D:\projects\clawhub |
排查权限和挂载 |
| 启动端口 | 3000 或实际端口 |
排查端口冲突 |
| 第一个任务 | 运营计划整理测试 | 确认任务范围 |
| 成功输出 | 生成 3 步计划 | 确认结果可复查 |
| 失败处理 | 网络超时，已配置代理 | 方便下一次复现 |
这张表很简单，但能提升具体度。以后接入 ClawHub Skills 时，团队可以对比“基础任务成功”和“Skills 任务失败”的差异，避免把所有问题都归因到安装流程。
AgentSkills Quickstart 和 ClawHub Quickstart 的关系
AgentSkills Quickstart 更偏技能或工具能力的快速验证，ClawHub Quickstart 更偏运行环境和第一个 Agent 任务的完整路径。两者可以有关联，但不要混成一件事。
如果你只是验证某个 Skills 能否运行，重点看 Skills 输入、输出、权限和依赖。如果你要验证 ClawHub 整体是否可用，就要看项目启动、任务分发、日志、状态和结果。边界越清楚，排查越快。
对于团队来说，建议把 Quickstart 结果写成一张记录表：
| 字段 | 示例 |
|---|---|
| 运行环境 | Windows 11 + WSL2 + Docker |
| 启动命令 | 记录实际执行命令 |
| 任务名称 | 第一个 Agent 测试任务 |
| 成功信号 | 页面可访问、日志无连续报错、结果可复查 |
| 失败原因 | 网络、端口、配置、权限或依赖 |
常见失败点
第一个失败点是 Docker 没有真正启动。命令行能识别 docker，不代表 Docker Server 可用。一定要看 docker version 是否同时返回 Client 和 Server。
第二个失败点是目录权限。项目放在同步盘、系统目录或中文路径下，可能导致挂载、写入或依赖安装异常。Quickstart 阶段用简单路径更稳。
第三个失败点是网络。依赖源、镜像源、GitHub 或外部 API 访问不稳定，都会让安装看起来像程序错误。先排除网络，再排查代码。
第四个失败点是任务选得太复杂。第一个 Agent 任务应该用于验证链路，而不是验证业务上限。先用低风险任务建立信心，再接入更复杂的流程。
ClawHub Quickstart 后下一步做什么
ClawHub Quickstart 跑通后，不要马上扩大到生产场景。先做一次复盘：启动用了多久？失败在哪一步？日志是否清楚？任务结果是否可复查？这些问题决定后续能不能长期维护。
如果要继续深入，可以按三条路线走：
| 路线 | 适合目标 |
|---|---|
| Skills 路线 | 验证 ClawHub Skills 或 AgentSkills Skills |
| 自托管路线 | 评估 AgentSkills 自托管和运行维护 |
| 业务执行路线 | 结合账号、浏览器、云手机和工作流 |
涉及账号环境、浏览器执行或社媒矩阵任务时，可以结合 多账号管理、AI 指纹浏览器 和 云手机 继续评估。技术 Quickstart 跑通，只是业务落地的第一步。
真正进入团队使用前，还要补三件事。第一，固定一份环境安装记录，方便新成员复现。第二，定义哪些任务可以自动跑，哪些任务必须人工确认。第三，确定日志和结果由谁复盘。没有这三件事，Quickstart 成功也很难变成稳定流程。
常见问题
ClawHub Quickstart 是安装教程吗？
它不只是安装教程。它更像从环境准备到第一个 Agent 任务的最小验证流程，目标是确认链路能跑通。
第一个 Agent 任务应该选什么？
建议选低风险、可验证、输出清楚的任务。例如文本整理、简单页面读取或基础 Skills 调用测试。
Docker 报错时先查什么？
先查 Docker Desktop 是否 Running，再查 docker version 和 docker compose version。如果 Server 没输出，先修 Docker。
WSL2 必须安装吗？
Windows 用户通常建议安装 WSL2。它能减少很多 Linux 工具链和容器环境差异，但具体要求仍以 ClawHub 文档为准。
Quickstart 成功后能直接生产使用吗？
不建议。Quickstart 只证明最小链路可用。生产使用还要看权限、日志、数据目录、备份、网络和团队维护能力。
AgentSkills Skills 什么时候接入？
先让基础 Quickstart 跑通，再接入 Skills。否则一旦失败，很难判断是基础环境问题还是 Skills 配置问题。
怎么判断 Quickstart 真的成功？
至少满足三个信号：服务能启动，任务能执行，结果能复查。只有页面打开，不一定代表任务链路已经完整。
总结
ClawHub Quickstart 的重点是先跑通最小链路。环境检查、Docker 状态、项目目录、配置文件、任务日志，每一步都要可验证。不要一开始就追求完整部署。
更稳的路径是：先准备环境，再启动项目，然后运行第一个低风险 Agent 任务。等日志、状态和输出都清楚后，再考虑 Skills、自托管和业务执行场景。
