实战演练¶

端到端操作演练，从安装到运行，每一步都包含预期输出。适合首次接触 PyClaw 的开发者按步骤操作。

演练 1：从零到首次对话 (5 分钟)¶

目标¶

完成 PyClaw 安装、配置和首次对话。

第 1 步：安装 PyClaw¶

pip install openclaw-py

预期输出：

Successfully installed openclaw-py-x.x.x

验证安装：

pyclaw --version

预期输出：

pyclaw x.x.x

第 2 步：运行设置向导¶

pyclaw setup --wizard

向导交互示例：

=== PyClaw Setup Wizard ===

Step 1/4: Choose LLM Provider
  1. Anthropic (Claude)
  2. OpenAI (GPT)
  3. Google (Gemini)
  4. Ollama (Local)
  5. DeepSeek
  6. Other (OpenAI-compatible)

Select [1-6]: 1

Step 2/4: Enter API Key
  Anthropic API Key: sk-ant-****

Step 3/4: Set Default Model
  Default model [claude-sonnet-4-20250514]: 

Step 4/4: Configure Channels (Optional)
  Configure Telegram? [y/N]: N
  Configure Discord? [y/N]: N

Configuration saved to ~/.pyclaw/pyclaw.json

第 3 步：启动 Gateway¶

pyclaw gateway

预期输出：

INFO  pyclaw.gateway.server  Starting PyClaw Gateway on 127.0.0.1:18777
INFO  pyclaw.gateway.server  WebSocket endpoint: ws://127.0.0.1:18777/ws
INFO  pyclaw.gateway.server  OpenAI API: http://127.0.0.1:18777/v1
INFO  pyclaw.agents.runner    Default agent initialized (model: claude-sonnet-4-20250514)

第 4 步：首次对话¶

在另一个终端中运行：

pyclaw agent "你好，请用一句话介绍你自己"

预期输出：

我是 PyClaw AI 助手，一个连接到 25+ 消息平台的多通道 AI 网关，随时为你提供智能对话服务。

注意: 实际回复取决于 LLM 模型和系统提示配置。

第 5 步：运行诊断¶

pyclaw doctor

预期输出：

PyClaw Doctor
=============

[OK] Python 3.10.12
[OK] PyClaw x.x.x
[OK] Configuration file: ~/.pyclaw/pyclaw.json
[OK] LLM Provider: anthropic (connected)
[OK] Default model: claude-sonnet-4-20250514
[OK] Gateway: running on 127.0.0.1:18777
[OK] Channels: 0 active / 25 available
[OK] Memory: SQLite + LanceDB
[OK] Secrets: no plaintext keys detected

All checks passed.

演练 2：连接 Telegram 通道 (10 分钟)¶

目标¶

将 Agent 连接到 Telegram，实现通过 Telegram 与 Agent 对话。

第 1 步：创建 Telegram Bot¶

在 Telegram 中：

搜索 @BotFather，发送 /newbot
输入 Bot 名称：My PyClaw Bot
输入用户名：my_pyclaw_bot
记录返回的 Token

预期 BotFather 回复：

Done! Congratulations on your new bot...
Use this token to access the HTTP API:
7012345678:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep your token secure...

第 2 步：获取 User ID¶

搜索 @userinfobot，发送 hi
记录返回的 ID

预期回复：

@your_username
Id: 12345678
First: Your Name

第 3 步：配置 PyClaw¶

# 设置环境变量（推荐方式）
echo 'TELEGRAM_BOT_TOKEN=7012345678:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' >> ~/.pyclaw/.env

# 启用通道
pyclaw config set channels.telegram.enabled true
pyclaw config set channels.telegram.token '${TELEGRAM_BOT_TOKEN}'
pyclaw config set channels.telegram.allowFrom '["12345678"]'

第 4 步：验证配置¶

pyclaw config get channels.telegram

预期输出：

{
  enabled: true,
  token: "${TELEGRAM_BOT_TOKEN}",
  allowFrom: ["12345678"],
}

第 5 步：检查通道状态¶

如果 Gateway 正在运行，通道会通过热重载自动启用：

pyclaw channels status

预期输出：

Channel    Status     Messages
─────────  ─────────  ────────
telegram   connected  0

如果 Gateway 未运行，启动它：

pyclaw gateway

预期日志中出现：

INFO  pyclaw.channels.telegram  Telegram channel starting (long polling)

第 6 步：测试对话¶

在 Telegram 中找到你的 Bot，发送：

你好，今天天气怎么样？

预期行为：Bot 在 3-10 秒内回复，具体内容取决于 LLM 模型。

演练 3：使用 UI 管理对话 (5 分钟)¶

目标¶

启动桌面 UI，通过图形界面管理会话、查看通道状态和配置 Agent。

第 1 步：确保 Gateway 运行¶

pyclaw status

预期输出：

Gateway: running on 127.0.0.1:18777
Agent: 1 active
Channels: 1 connected

如果未运行：

pyclaw gateway &

第 2 步：启动 UI¶

pyclaw ui

预期行为：

桌面窗口打开，显示 PyClaw 主界面
左侧 Navigation Rail 显示 8 个功能页面
默认进入 Chat 页面
UI 自动连接到本地 Gateway（WebSocket）

或以 Web 模式启动：

pyclaw ui --web --port 18776

预期输出：

✓ Ready in 2.3s
Web UI available at http://localhost:3000

第 3 步：在 UI 中发送消息¶

在 Chat 页面的输入框中输入消息
按 Enter 发送
观察 Agent 的流式回复（文字逐字显示）
如果 Agent 调用了工具，工具调用过程实时显示

第 4 步：查看通道状态¶

点击左侧 Navigation Rail 的 Channels 图标
查看已连接通道的列表和状态

第 5 步：修改设置¶

点击 Settings 图标
修改模型或 Provider 配置
修改主题和语言

第 6 步：查看系统信息¶

点击 System 图标
查看系统状态、运行日志和诊断信息

演练 4：探索技能系统 (5 分钟)¶

目标¶

了解技能系统，安装和浏览可用技能。

第 1 步：列出已安装技能¶

pyclaw skills list

预期输出：

Installed Skills:

  * code-review  (bundled)
    ~/.pyclaw/workspace/skills/code-review
  * analytics    (bundled)
    ~/.pyclaw/workspace/skills/analytics

第 2 步：浏览内置技能¶

pyclaw skills browse

预期输出：

Built-in Skills Catalog
========================

  analytics       - 数据分析与可视化
  code-review     - 代码审查与改进建议
  healthcheck     - 系统健康检查与诊断
  ...

  Install: pyclaw skills install <name>

第 3 步：搜索 ClawHub 市场¶

pyclaw skills search "code review"

预期输出：

Searching ClawHub for 'code-review'...

Found 3 skill(s):

  * code-review-pro
    Professional code review with security analysis
    https://clawhub.dev/skills/code-review-pro

  * pr-reviewer
    Automated pull request review
    https://clawhub.dev/skills/pr-reviewer

  * security-scanner
    Security vulnerability scanning
    https://clawhub.dev/skills/security-scanner

  Install with: pyclaw skills install <name>

第 4 步：安装技能¶

pyclaw skills install code-review-pro

预期输出：

Installing skill 'code-review-pro' from ClawHub...
Downloading... done.
Verifying checksum... OK.
Installed to ~/.pyclaw/skills/code-review-pro/SKILL.md

第 5 步：验证技能生效¶

技能安装后自动注入 Agent 系统提示，无需重启：

pyclaw skills list

预期输出中应包含新安装的技能：

Installed Skills:

  * code-review       (bundled)
    ~/.pyclaw/workspace/skills/code-review
  * code-review-pro   (marketplace)
    ~/.pyclaw/skills/code-review-pro

演练 5：通过 OpenAI 兼容 API 调用 (5 分钟)¶

目标¶

使用 OpenAI SDK 或 curl 调用 PyClaw Gateway 的兼容 API。

第 1 步：确保 Gateway 运行¶

pyclaw gateway &

第 2 步：使用 curl 调用¶

curl -s http://127.0.0.1:18777/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "messages": [
      {"role": "user", "content": "Hello, who are you?"}
    ],
    "stream": false
  }' | python -m json.tool

预期输出：

{
  "id": "chatcmpl-xxxxxx",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "claude-sonnet-4-20250514",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I'm your PyClaw AI assistant..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 30,
    "total_tokens": 50
  }
}

第 3 步：使用 Python OpenAI SDK¶

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:18777/v1",
    api_key="not-needed",  # PyClaw 使用自己的认证
)

response = client.chat.completions.create(
    model="claude-sonnet-4-20250514",
    messages=[
        {"role": "user", "content": "用三个词描述 PyClaw"}
    ],
)

print(response.choices[0].message.content)

预期输出：

多通道、智能、灵活

第 4 步：流式调用¶

stream = client.chat.completions.create(
    model="claude-sonnet-4-20250514",
    messages=[
        {"role": "user", "content": "写一首关于 AI 的俳句"}
    ],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

print()

演练 6：配置定时任务 (5 分钟)¶

目标¶

创建一个每日定时任务，让 Agent 每天早上发送摘要。

第 1 步：创建定时任务¶

pyclaw config set cron.enabled true

直接编辑 ~/.pyclaw/pyclaw.json，添加定时任务：

{
  cron: {
    enabled: true,
    jobs: [
      {
        id: "morning-report",
        scheduleType: "cron",
        schedule: "0 8 * * *",       // 每天早上 8:00
        message: "生成今日工作摘要，包括待办事项和重要提醒",
        agentId: "main",
        channel: "telegram",           // 发送结果到 Telegram
        deliver: true,
      },
    ],
  },
}

第 2 步：验证定时任务¶

pyclaw config get cron

预期输出：

{
  enabled: true,
  jobs: [
    {
      id: "morning-report",
      scheduleType: "cron",
      schedule: "0 8 * * *",
      message: "生成今日工作摘要，包括待办事项和重要提醒",
      agentId: "main",
      channel: "telegram",
      deliver: true,
    },
  ],
}

第 3 步：手动触发测试¶

通过 UI 的 Cron 管理页面手动触发定时任务，或通过 Gateway RPC：

pyclaw agent "生成今日工作摘要"

演练 7：MCP 工具服务器集成 (10 分钟)¶

目标¶

连接一个 MCP 文件系统工具服务器，让 Agent 能够读写本地文件。

第 1 步：安装 MCP 服务器¶

npm install -g @modelcontextprotocol/server-filesystem

第 2 步：配置 MCP¶

直接编辑 ~/.pyclaw/pyclaw.json：

{
  tools: {
    mcpServers: {
      filesystem: {
        command: "npx",
        args: [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "/home/user/documents",
        ],
      },
    },
  },
}

第 3 步：检查 MCP 状态¶

pyclaw mcp status

预期输出：

MCP Servers
===========

filesystem
  Status: connected
  Transport: stdio
  Tools: read_file, write_file, list_directory, search_files, get_file_info

第 4 步：使用 MCP 工具¶

pyclaw agent "列出 /home/user/documents 目录下的文件"

Agent 将使用 MCP filesystem 工具列出目录内容。

相关文档: 快速开始 · 通道设置教程 · 配置说明 · API 参考