跳转至

快速开始

从零到首次对话，5 分钟上手 pyclaw。

前置条件

  • Python 3.10 或更高版本（运行 python --version 确认）
  • 一个 LLM API Key（OpenAI、Anthropic、Google Gemini、Ollama 等均可）

安装

选择以下任一方式：

# macOS / Linux 一键安装
curl -fsSL https://raw.githubusercontent.com/chensaics/openclaw-py/master/scripts/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/chensaics/openclaw-py/master/scripts/install.ps1 | iex

# 通过 pip
pip install openclaw-py

# 通过 pipx（推荐，隔离环境）
pipx install openclaw-py

更多安装方式（Docker、Homebrew、源码等）请参阅 安装指南。

交互式设置

运行设置向导，配置 Provider、模型和 API Key：

pyclaw setup --wizard

向导会引导你完成：

  1. 选择 LLM 提供商（Anthropic / OpenAI / Google / Ollama 等）
  2. 输入 API Key
  3. 设置默认模型
  4. 可选：配置通道（Telegram、Discord 等）

首次对话

直接在终端与 Agent 对话：

pyclaw agent "你好，请介绍一下自己"

启动 Gateway

Gateway 是核心服务进程，为通道、UI 和 API 提供统一的运行时：

pyclaw gateway

默认监听 http://127.0.0.1:18777。

打开 UI

启动跨平台桌面 UI（自动连接到本地 Gateway）：

pyclaw ui

或以 Web 模式启动：

pyclaw ui --web --port 18776

推荐: 先启动 Gateway (pyclaw gateway)，再启动 UI。UI 会自动通过 WebSocket 连接到 Gateway，获得流式聊天、会话管理、计划/定时任务管理、系统监控等完整功能。如果 Gateway 不可用，UI 会自动回退到本地进程内模式。

检查状态

确认各组件运行正常：

pyclaw status

深度诊断：

pyclaw doctor

常用环境变量

变量 说明 默认值
OPENAI_API_KEY OpenAI API Key —
ANTHROPIC_API_KEY Anthropic API Key —
GOOGLE_API_KEY Google AI API Key —
PYCLAW_AUTH_TOKEN Gateway 认证 Token —
PYCLAW_GATEWAY_PORT Gateway 端口 18777
PYCLAW_STATE_DIR 状态目录 ~/.pyclaw

UI 功能概览

UI 提供 8 个功能页面，全部通过 Gateway WebSocket v3 协议与后端交互：

页面 功能
Chat 流式聊天、中断生成、消息编辑/重发、工具调用实时展示、计划进度条
Agents Agent 列表、创建、配置查看
Channels 消息通道连接状态
Plans 任务计划管理（查看步骤、恢复暂停、删除）
Cron 定时任务管理（列表、添加、执行历史）
Voice 语音合成 (TTS) 与语音转文字 (STT)
System 系统信息、诊断、日志查看、数据备份
Settings 模型/Provider 配置、主题定制、语言切换

连接第一个通道

将 Agent 连接到消息平台，实现 7x24 小时自动回复。以 Telegram 为例：

1. 获取 Bot Token

在 Telegram 中搜索 @BotFather，发送 /newbot，按提示创建 Bot 并获取 Token。

2. 配置通道

# 方式一：通过交互式向导
pyclaw setup --wizard

# 方式二：通过 CLI 直接设置
pyclaw config set channels.telegram.enabled true
pyclaw config set channels.telegram.token "123456:ABC-DEF"

# 方式三：直接编辑配置文件
vim ~/.pyclaw/pyclaw.json

在配置文件中添加：

{
  channels: {
    telegram: {
      enabled: true,
      token: "123456:ABC-DEF",
      allowFrom: ["your_telegram_user_id"],  // 限制谁可以与 Bot 对话
    },
  },
}

3. 重启 Gateway

通道配置通过热重载自动生效，无需重启。如需确认：

pyclaw channels status

4. 测试对话

在 Telegram 中找到你的 Bot，发送一条消息。如果一切正常，Bot 会在几秒内回复。

提示: 如果收不到回复，运行 pyclaw logs --follow 查看日志。常见原因：allowFrom 中的用户 ID 不正确、Bot Token 无效、群组中未 @mention。

详细的通道设置教程（Telegram、Discord、Slack 等），请参阅 通道设置教程。

浏览与安装技能

技能 (Skills) 为 Agent 注入特定领域的知识和能力。

# 列出已安装的技能
pyclaw skills list

# 在 ClawHub 市场搜索技能
pyclaw skills search "code review"

# 安装技能
pyclaw skills install code-review

# 浏览内置技能目录
pyclaw skills browse

技能安装后自动在 Agent 系统提示中生效，无需重启。更多详情参阅 配置说明 — Skills。

下一步