15 分钟构建你的第一个 EmperorClaw 智能体

前提条件

已安装 Docker（获取 Docker）
终端中可以使用 curl
一个支持复制粘贴的文本编辑器或终端

完整的检查清单请参阅快速上手指南。

第 1 步：部署控制面

EmperorClaw 以自托管的 Docker 服务栈形式运行。打开终端并运行：

curl -fsSL https://raw.githubusercontent.com/emperorclaw/emperorclaw/main/install.sh | bash

它会下载部署包、生成密钥、写入 .env，并执行 docker compose up -d。完成后，控制面会运行在 http://localhost:3000。

已经部署过了？直接跳到第 3 步。

验证

curl -s -o /dev/null -w "%{http_code}" http://localhost:3000
# Expected: 200

第 2 步：创建工作区

在浏览器中打开 http://localhost:3000。
点击 Create Account（创建账号），填写邮箱、姓名和密码。
注册后，系统会提示你创建一个 Company Workspace（公司工作区）——这是你团队的顶层容器。用你的公司或项目名称为它命名（例如 “My Agency”）。
你会进入仪表盘。花 30 秒四处看看：
- Projects（项目）——目标和任务所在的地方
- Agents（智能体）——注册运行时的地方
- Storage（存储）——交付物存放的地方
- Knowledge（知识）——共享的规则和上下文

你刚刚做了什么

每个公司工作区都是一套自成一体的记录系统：拥有自己的项目、智能体、存储和知识。智能体完全在这个边界内进行认证和运行。

第 3 步：生成 API 令牌

你的智能体需要一个令牌，才能通过 MCP bridge 进行认证。

进入 Settings > API Tokens（设置 > API 令牌，侧边栏中的齿轮图标）。
点击 Generate New Token（生成新令牌）。
给它起一个标签，例如 my-first-agent。
复制该令牌。它不会再次显示。

请妥善保管此令牌。任何持有它的人都能在你的工作区中执行操作。在生产环境中，请为每个智能体生成专用令牌，并定期轮换。

第 4 步：注册智能体

现在来配置你的第一个智能体运行时。打开终端，设置你的令牌和服务器 URL：

EC_TOKEN="ec_<your-token-here>"
EC_URL="http://localhost:3000"

注册智能体：

curl -X POST "$EC_URL/api/mcp/agents" \
  -H "Authorization: Bearer $EC_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen 2>/dev/null || python3 -c 'import uuid; print(uuid.uuid4())')" \
  -d '{
    "name": "my-first-worker",
    "role": "worker",
    "skillsJson": ["general"]
  }'

预期响应：

{
  "message": "Agent registered",
  "agent": {
    "id": "...",
    "name": "my-first-worker",
    "role": "worker",
    ...
  }
}

保存返回的智能体 id：

EC_AGENT_ID="<returned-agent-id>"

这里发生了什么？这条智能体记录会成为你的运行时的持久身份——它的租约、活动日志和角色都记录在控制面中，而不是本地配置文件里。运行时 bridge 如何使用这个身份，请参阅开发者指南。

第 5 步：检查运行时健康状态

确认 API 运行正常，并查看可用的版本和功能：

curl -s "$EC_URL/api/mcp/runtime/health" \
  -H "Authorization: Bearer $EC_TOKEN" | jq .

预期的响应结构：

{
  "ok": true,
  "companyId": "...",
  "serverTime": "2026-10-15T...Z",
  "apiBaseUrl": "http://localhost:3000",
  "wsUrl": "ws://localhost:3000/api/mcp/ws",
  "emperorVersion": "0.8.101",
  "docsUrl": "http://localhost:3000/docs",
  "capabilities": { ... }
}

第 6 步：创建项目和任务

EmperorClaw 中的工作按项目（长期目标）和任务（单个工作单元）来组织。这是你在工作项层面的记录系统。

创建一个项目：

curl -X POST "$EC_URL/api/mcp/projects" \
  -H "Authorization: Bearer $EC_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen 2>/dev/null || python3 -c 'import uuid; print(uuid.uuid4())')" \
  -d '{
    "goal": "Demonstrate a complete task cycle from agent registration to artifact delivery",
    "maxActiveAgents": 3
  }'

保存项目 id：

EC_PROJECT_ID="<returned-project-id>"

接着在该项目中创建一个任务：

curl -X POST "$EC_URL/api/mcp/tasks" \
  -H "Authorization: Bearer $EC_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen 2>/dev/null || python3 -c 'import uuid; print(uuid.uuid4())')" \
  -d '{
    "projectId": "'"$EC_PROJECT_ID"'",
    "taskType": "generic",
    "title": "Generate a welcome report",
    "description": "Write a short markdown report saying hello and listing today'\''s date.",
    "allowUnderspecified": true
  }'

为什么要用 allowUnderspecified: true？生产环境中的任务通常需要 taskType、title、description、acceptanceCriteria 和 deliverables。为了让快速演示保持简单，这里省略了它们。你真正的智能体应当始终填写这些字段。

保存任务 id：

EC_TASK_ID="<returned-task-id>"

第 7 步：领取并完成任务（智能体循环）

这是你的智能体将要运行的核心工作流。每一步都是对控制面的一次原子 API 调用——没有共享文件系统，也没有分布式锁。

7a. 领取下一个可用任务

curl -X POST "$EC_URL/api/mcp/tasks/claim" \
  -H "Authorization: Bearer $EC_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen 2>/dev/null || python3 -c 'import uuid; print(uuid.uuid4())')" \
  -d '{
    "agentId": "'"$EC_AGENT_ID"'"
  }'

领取后，任务会从 inbox 变为 in_progress。如果没有可用任务，API 会返回 200 和 {"message": "No tasks available", "task": null}——请先再创建一个任务。

不支持按任务领取。API 只会为智能体返回下一个可用任务。你的智能体循环应当在准备好接活时调用 /claim，而不是用它去抢某个特定任务。

7b. 用心跳保持租约有效

工作期间，每 60 秒发送一次心跳以续期领取：

curl -X POST "$EC_URL/api/mcp/agents/heartbeat" \
  -H "Authorization: Bearer $EC_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen 2>/dev/null || python3 -c 'import uuid; print(uuid.uuid4())')" \
  -d '{
    "agentId": "'"$EC_AGENT_ID"'",
    "currentLoad": 1
  }'

预期响应：

{
  "message": "Heartbeat acknowledged",
  "lastSeenAt": "2026-10-15T...Z"
}

7c. 记录进度

curl -X POST "$EC_URL/api/mcp/tasks/$EC_TASK_ID/notes" \
  -H "Authorization: Bearer $EC_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen 2>/dev/null || python3 -c 'import uuid; print(uuid.uuid4())')" \
  -d '{
    "agentId": "'"$EC_AGENT_ID"'",
    "note": "Starting the welcome report",
    "kind": "progress"
  }'

每条笔记都带有时间戳和归属信息——它们构成了你的审计轨迹。

7d. 完成任务

curl -X POST "$EC_URL/api/mcp/tasks/$EC_TASK_ID/result" \
  -H "Authorization: Bearer $EC_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen 2>/dev/null || python3 -c 'import uuid; print(uuid.uuid4())')" \
  -d '{
    "state": "done",
    "agentId": "'"$EC_AGENT_ID"'",
    "comment": "Welcome report generated successfully",
    "outputJson": {
      "summary": "Report written to welcome-report.md"
    }
  }'

任务变为 done，输出也被记录下来。人可以在界面中审阅它、重新打开它或批准它——全部都在同一套记录系统中完成。

第 8 步：把交付物存入存储

生成任务输出固然不错，存下一个真实的文件更好——正是这一点让 EmperorClaw 成为一套记录系统，而不只是一个待办清单。

写一个报告文件：

cat > /tmp/welcome.md << 'EOF'
# Welcome to EmperorClaw

This report was generated by my first EmperorClaw agent.

- **Date:** $(date +%Y-%m-%d)
- **Status:** Working
- **Agent:** my-first-worker

## Next Steps

1. Deploy production with a PostgreSQL backup strategy
2. Register specialized agents for each skill domain
3. Set up human approval gates for sensitive work
EOF

把它作为 artifact 上传：

curl -X POST "$EC_URL/api/mcp/artifacts/upload" \
  -H "Authorization: Bearer $EC_TOKEN" \
  -H "Idempotency-Key: $(uuidgen 2>/dev/null || python3 -c 'import uuid; print(uuid.uuid4())')" \
  -F "file=@/tmp/welcome.md" \
  -F "projectId=$EC_PROJECT_ID" \
  -F "kind=report" \
  -F "title=welcome-report.md"

预期响应：

{
  "message": "Artifact uploaded",
  "artifact": {
    "id": "...",
    "path": "welcome-report.md",
    "sha256": "...",
    "sizeBytes": 1234
  }
}

验证 artifact

curl -s "$EC_URL/api/mcp/artifacts/$EC_ARTIFACT_ID/verify" \
  -H "Authorization: Bearer $EC_TOKEN" | jq .

预期响应：

{
  "ok": true,
  "artifactId": "...",
  "sha256": "...",
  "expectedSizeBytes": 1234,
  "sizeBytes": 1234,
  "expectedSha256": "...",
  "error": null
}

保存 artifact 的 id：

EC_ARTIFACT_ID="<returned-artifact-id>"

在界面中打开 Storage（存储）——文件就在那里，带有版本，并且可以分享。

第 9 步：验证完整流程

检查项	方法
任务已完成	`curl -s "$EC_URL/api/mcp/tasks/$EC_TASK_ID" -H "Authorization: Bearer $EC_TOKEN"`
进度笔记可见	界面：打开任务，查看笔记时间线
Artifact 已验证	`curl ... $EC_URL/api/mcp/artifacts/$EC_ARTIFACT_ID/verify`
智能体活动	`curl -s "$EC_URL/api/mcp/agents" -H "Authorization: Bearer $EC_TOKEN"`

🎉 你刚刚搭建了一个可运行的智能体循环

在 10–15 分钟内，你完成了：

部署了 EmperorClaw 控制面（自托管）
检查了运行时健康状态——确认 API 在线且所有能力可用
注册了智能体——在控制面中拥有持久身份
创建了项目——一个有独立范围的长期目标
创建了任务——一个带类型和规格的工作单元
领取了下一个可用任务——仅凭 agentId 获得原子租约
发送了心跳——用 currentLoad 保持租约有效
记录了进度——在笔记时间线中带时间戳和归属信息
完成了任务——agentId + state 已持久化
上传并验证了 artifact——存储中一个可校验的文件

这正是你的生产环境智能体将要运行的工作流——只不过规模更大、按计划执行，并带有人工审批和故障恢复。EmperorClaw 是底层的记录系统：智能体重启时不会丢失任何东西，也不依赖共享文件系统，每一个操作都会留下持久的痕迹。

后续步骤

你已经走完了整个流程，接下来可以从这些地方深入：

目标	资源
理解架构	How it Works（英文）
编写生产环境智能体	开发者指南
从零开始安装	快速上手指南
排查常见问题	故障排查指南（英文）
社区与支持	GitHub Discussions
完整 API 参考	GitHub 文档目录（英文）

发现本教程有问题？请提交 issue。