文档中心

完整的文档和教程，帮助你快速上手 WeClaw

快速开始

环境要求

Python 3.10 或更高版本
至少 500MB 可用磁盘空间
至少一个大模型 API Key（DeepSeek、OpenAI 等）

安装 WeClaw

使用 pip 一行命令即可完成安装，无需复杂配置：

pip install weclaw

首次启动

安装完成后，选择你喜欢的方式启动 WeClaw：

# CLI 模式
python -m weclaw

# GUI 模式
weclaw-gui

基本使用

对话功能

WeClaw 支持与多种大模型进行自然语言对话，具备以下特性：

流式输出

实时显示 AI 回复，无需等待完整响应

多轮对话

自动维护对话上下文，支持连续追问

Markdown 渲染

支持代码高亮、表格、列表等富文本格式

图片理解

上传图片让 AI 分析和理解图片内容

工具调用

使用自然语言描述你想要完成的任务，WeClaw 会自动选择并调用合适的工具：

# 使用自然语言调用工具
> 帮我截取当前屏幕
> 搜索最近修改的文件
> 打开浏览器访问 github.com

工作流配置

通过工作流功能，你可以定义多步骤的自动化任务，让 AI 按照预设流程执行操作。

高级配置

模型配置

WeClaw 支持同时配置多个 LLM 模型，在 config/models.toml 中进行配置：

# config/models.toml
[deepseek]
api_key = "sk-xxx"
model = "deepseek-chat"

[openai]
api_key = "sk-xxx"
model = "gpt-4o"
base_url = "https://api.openai.com/v1"

[claude]
api_key = "sk-ant-xxx"
model = "claude-3-5-sonnet-20241022"

工具自定义

你可以启用或禁用特定工具，以及为工具配置特定参数：

# config/tools.json
{
  "enabled_tools": ["shell", "file", "browser", "voice"],
  "tool_settings": {
    "browser": {
      "headless": true,
      "timeout": 30000
    }
  }
}

系统 Prompt 自定义

通过设置中的系统 Prompt 功能，你可以自定义 AI 的行为和人格特征，让 AI 更符合你的使用习惯。

API 参考

远程服务概述

WeClaw 远程服务提供 WebSocket 和 REST 两种接口，支持从 PWA 移动端或其他客户端远程控制桌面 AI。

WebSocket 通信

WebSocket 接口用于实时双向通信，支持流式对话和实时状态更新：

// WebSocket 连接
const ws = new WebSocket('ws://localhost:8765/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'chat',
    message: 'Hello, WeClaw!'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Response:', data);
};

REST 端点

REST API 提供以下主要端点：

POST/api/chat

发送对话消息并获取 AI 回复

GET/api/tools

获取可用工具列表

POST/api/tool/execute

执行指定工具并返回结果

部署指南

本地部署

最简单的部署方式，适合个人使用：

# 本地部署
pip install weclaw
weclaw-gui

远程服务部署

如果需要从手机远程控制，需要启动远程服务：

# 启动远程服务
python -m weclaw.remote_server --host 0.0.0.0 --port 8765

# 配置防火墙（可选）
ufw allow 8765/tcp

Docker 部署

使用 Docker 可以快速部署完整的 WeClaw 环境：

# docker-compose.yml
version: '3.8'
services:
  weclaw:
    image: weclaw/weclaw:latest
    ports:
      - "8765:8765"
    volumes:
      - ./config:/app/config
      - ./data:/app/data
    environment:
      - DEEPSEEK_API_KEY=sk-xxx

常见问题

安装时遇到依赖冲突怎么办？

建议使用虚拟环境隔离依赖。运行 python -m venv venv 创建虚拟环境，然后激活后再安装。如果问题持续，可以尝试 pip install weclaw --no-deps 然后手动安装缺失依赖。

为什么 API 调用失败？

首先检查 API Key 是否正确配置在 config/models.toml 中。其次确认网络连接正常，部分模型（如 DeepSeek）可能需要科学上网。最后查看 logs/winclaw.log 中的详细错误信息。

如何切换不同的 AI 模型？

在设置界面中可以选择当前使用的模型。你也可以在对话中使用 /model 命令快速切换。支持的模型包括 DeepSeek、OpenAI、Claude、Gemini 等 10+ 种。

PWA 移动端无法连接远程服务？

确保远程服务已启动且端口已开放。检查防火墙设置，确保 8765 端口允许外部访问。如果使用公网 IP，需要在路由器中配置端口转发。

工具调用没有响应怎么办？

部分工具（如浏览器自动化）首次使用需要下载 Playwright 浏览器，请耐心等待。检查 config/tools.json 确认工具已启用。某些系统操作可能需要管理员权限运行。