分钟跑通OpenClaw：创建第一个工程并成功启动示例任务

在“OpenClaw教程：从入门到实战的分层学习路线”系列里，这一篇的目标只有一个：用最短时间把 OpenClaw 跑起来——从零创建第一个工程，到成功启动一个示例任务并看到可验证的运行结果（日志/状态/输出）。你不需要先理解所有概念，但需要把关键步骤做对，这样后续学习（调度、资源、任务编排、可观测性、扩展插件等）才有落脚点。

说明：不同团队对 OpenClaw 的安装方式、模板仓库、示例任务名称可能略有差异。本文用“通用做法 + 可替换占位符”的方式写成：你只要把文中 YOUR_*、<...> 替换为你实际环境中的值即可。

准备工作：3分钟确认环境

在开始创建工程之前，先把这些基础项核对一遍，避免一上来就卡在环境问题。

必备工具清单

• Git：用于拉取工程模板/示例
• OpenClaw CLI（命令行工具）：用于初始化工程、启动示例任务、查看状态
• 容器运行时（二选一）：Docker 或 Podman（建议 Docker）
• YAML/JSON 编辑器：VS Code 即可

快速自检命令

在终端执行：

1. 检查 Git：

   • git --version

2. 检查 Docker：

   • docker version
   • docker ps

3. 检查 OpenClaw CLI（示例）：

   • openclaw --version
   • openclaw --help

如果 openclaw 不在 PATH 中：

• 优先确认安装路径是否已加入环境变量
• 或使用绝对路径调用（不推荐长期这样做）

选择运行模式：本地快速跑通 vs 连接已有集群

为了“分钟跑通”，建议先用本地快速跑通模式（本地启动依赖组件/或使用内置轻量运行方式），等跑通后再切换到公司/团队的集群。

模式A：本地快速跑通（推荐）

适用：你想在自己的电脑上先把链路跑通。

你需要：Docker + OpenClaw CLI。

模式B：连接已有环境

适用：团队已经部署好了 OpenClaw 控制面/服务端，你只需要创建工程并提交任务。

你需要：服务端地址、鉴权信息（token/用户名密码/证书）、命名空间或项目空间权限。

本文后续主要按模式A描述，并在关键节点补充模式B需要替换的配置项。

创建第一个工程：用模板初始化（5分钟）

一个“可运行的 OpenClaw 工程”通常至少包含：

• 工程配置（指向运行环境、默认命名空间/项目）
• 任务定义（示例任务 YAML/JSON）
• 任务代码（或引用镜像/脚本）
• 本地调试脚本（可选，但强烈建议）

步骤1：创建目录并初始化

在你希望存放代码的位置：

• mkdir openclaw-demo && cd openclaw-demo

然后用 CLI 初始化工程（以下命令以“init”风格举例）：

• openclaw init

初始化过程中常见会让你选择：

• 工程类型（例如：任务工程 / 工作流工程 / 插件工程）
• 语言或运行方式（例如：Python/Node/容器镜像/脚本任务）
• 是否带示例（强烈建议选择“带示例任务”）

如果你的 OpenClaw 环境使用模板仓库：

• openclaw init --template <TEMPLATE_NAME_OR_GIT_URL>

建议选择一个最简单的模板，例如：

• “hello-world”/“quickstart”/“demo-task” 这类。

步骤2：理解初始化后的目录结构

不同模板略有差别，但你应该能看到类似的内容：

• openclaw.yaml 或 .openclaw/config.yaml：工程级配置
• tasks/：任务定义文件（YAML/JSON）
• src/：示例任务逻辑代码（或脚本）
• Dockerfile：如使用容器方式运行
• README.md：模板说明

你需要重点关注两类文件：
1) 工程配置文件：决定 CLI 默认连到哪里、用什么身份、默认使用哪个项目空间
2) 示例任务定义：决定“要跑的任务是什么”

配置 OpenClaw 连接信息：让 CLI 知道去哪里跑

这一段是最容易“看似小、实际卡死”的地方：工程创建好了，但你没有配置好运行环境或凭证，任务提交会失败。

本地模式的典型配置

如果模板支持本地运行，通常你只需要确认：

• 运行模式：local
• 本地依赖组件：是否用 docker-compose 启动

示例（仅示意，字段以你的模板为准）：

• mode: local
• backend: docker
• project: demo

如果模板提供 compose.yaml/docker-compose.yml：

• 你需要先 docker compose up -d 启动依赖（例如元数据存储、消息队列、API 服务等）

连接已有环境的典型配置

如果你要连远端，通常需要：

• endpoint: https://YOUR_OPENCLAW_ENDPOINT
• token: YOUR_TOKEN 或 username/password
• namespace/project: YOUR_PROJECT

建议把敏感信息放在：

• 环境变量（如 OPENCLAW_TOKEN）
• 本地不提交的配置文件（加入 .gitignore）

启动 OpenClaw 本地依赖（如有）：把“控制面”跑起来

如果你的 quickstart 采用本地依赖组件方式，通常分两步：

步骤1：启动依赖

在工程根目录执行：

• docker compose up -d

然后检查容器状态：

• docker ps

你要看到：所有相关容器都处于 Up 状态，且没有频繁重启。

步骤2：检查服务健康

常用的验证方式：

• 浏览器打开控制台地址（如果模板提供）

• 或用 CLI 执行健康检查命令（示例）：

  • openclaw doctor
  • openclaw status

如果这里失败，不要急着改任务定义，先把“服务可用”解决掉。

运行示例任务：提交、观察、验证输出

“成功启动示例任务”的标准是：
1) 任务被提交成功（返回 taskId/jobId/runId）
2) 任务状态从 Pending/Queued 进入 Running，最终到 Succeeded/Completed
3) 你能看到可核验的输出：日志里打印了预期内容，或产物落到指定目录/存储

步骤1：找到示例任务文件

通常在 tasks/ 下会有一个示例，如：

• tasks/hello.yaml
• tasks/demo_task.yaml
• tasks/quickstart.yml

打开它，确认至少包含：

• 名称（name）
• 入口（command / image / script / module）
• 资源或运行参数（可选）

步骤2：提交任务

提交命令在不同版本可能是 run/submit/apply，你可以：

• openclaw run tasks/hello.yaml

或：

• openclaw submit -f tasks/hello.yaml

提交成功后，CLI 一般会输出一个 ID，例如：

• runId: r-xxxxx

把它复制下来，后续全靠它查状态和日志。

步骤3：查看运行状态

常用命令（择一）：

• openclaw ps（查看最近任务/运行实例列表）
• openclaw get run <RUN_ID>
• openclaw describe run <RUN_ID>

你要关注的字段：

• status：是否从 queued -> running
• startTime/endTime
• exitCode（如有）
• reason/message（失败时最关键）

步骤4：查看日志并验证“真的跑了”

日志命令示例：

• openclaw logs <RUN_ID>
• openclaw logs <RUN_ID> --follow

验证点建议做到“可复现”：

• 示例任务输出了固定文本（如 Hello OpenClaw）
• 或打印了环境信息（如当前时间、hostname、版本号）

如果示例任务是生成文件型产物，检查输出目录/挂载卷，例如：

• outputs/hello.txt
• 或对象存储路径（如 s3://...）

做一次小改动：改参数/改输出，确认你能控制任务

仅仅跑通模板并不够。为了确认你掌握了最基本的闭环，建议立刻做一个小改动，然后重新运行。

改动示例1：修改任务参数

如果任务定义里有参数段（示意）：

• args: ["--name", "world"]

把 world 改成 openclaw，重新提交：

• openclaw run tasks/hello.yaml

然后看日志是否从 Hello world 变成 Hello openclaw。

改动示例2：修改资源配额（如果支持）

有些环境会要求你显式声明资源（示意）：

• `resources:
  cpu: "0.5"
  memory: "512Mi"`

把它改小或改大，重新提交，观察调度是否变化（队列等待时间、是否被拒绝等）。

注意：如果你在共享集群里测试，别把资源改得太夸张，避免占用过多资源。

常见失败点与排查清单（按出现频率排序）

1) CLI 连不上服务端/本地控制面

表现：

• 提交时报 connection refused、timeout、unauthorized

处理：

• 本地模式：先确认 docker ps 里控制面容器都 Up
• 远端模式：确认 endpoint 是否正确（https/http、端口）
• 鉴权失败：检查 token 是否过期、环境变量是否生效

2) 任务一直排队（Queued/Pending）

表现：

• 状态不进入 Running

处理：

• 资源声明过大导致无可用节点：调小 cpu/memory
• 队列/命名空间配额不足：换到有权限的 project 或找管理员增加配额
• 依赖镜像拉取慢：确保镜像可访问（公司镜像仓库/VPN/代理）

3) 任务 Running 但很快失败（Failed）

处理顺序：

1. openclaw describe run <RUN_ID> 看失败原因
2. openclaw logs <RUN_ID> 定位具体报错

3. 常见问题：

   • 入口命令写错（command/args 不匹配）
   • 镜像不存在或无权限
   • 依赖文件路径不对（相对路径在容器内不存在）

4) 看不到日志/日志为空

处理：

• 确认任务里确实有 stdout/stderr 输出
• 如果是短任务，日志可能一闪而过：用 --since 或直接拉取完整日志
• 检查是否需要指定组件（如 --container main）

把“分钟跑通”固化成你的日常脚本

当你首次跑通后，建议把常用命令固化到工程里，降低重复成本。

建议添加的脚本（示例思路）

• scripts/up.sh：启动本地依赖（docker compose up -d）
• scripts/run_demo.sh：提交示例任务
• scripts/logs.sh <id>：跟随日志
• scripts/down.sh：停止并清理环境

这样你下次换电脑、换分支、或者带同事入门时，执行顺序就非常明确：
1) up
2) run_demo
3) logs
4) down

本篇小结：你现在应该达成的3个结果

完成本文后，你应当能够：

1. 创建一个可工作的 OpenClaw 工程（包含基本配置与示例任务）
2. 成功提交并运行一个示例任务（状态可查、日志可看、结果可验）
3. 做一次小改动并重新运行（证明你能控制参数与执行结果）

下一篇在系列路线中通常会进入“任务定义详解/工作流编排/资源与队列/调试与可观测性”的更细分主题；但在那之前，强烈建议你保留这个 openclaw-demo 作为后续所有实验的基线工程，遇到问题时也能快速对照排查。