1. 项目缘起：当班级群需要一个“永不掉线”的助教

作为一名技术爱好者，同时也是班级里的“热心肠”，我经常在班级QQ群里看到这样的场景：深夜有同学问一道高数题，半天没人回应；老师发的实验报告模板，很快被聊天记录淹没，需要时又得翻半天；或者，大家讨论一个专业术语，总得有人去百度再回来解释。这些琐碎但高频的需求，消耗着大家的时间和精力。于是我就想，能不能做一个24小时在线的“智能助教”，让它常驻在QQ群里，随时回答学习问题、管理资料、甚至组织简单的签到？

这个想法听起来很酷，但实现起来，摆在面前的有几座大山：首先，需要一个足够聪明的“大脑”来处理自然语言，理解同学们五花八门的问题；其次，它得能“住”进QQ群里，也就是成为一个QQ机器人；最后，整个系统要稳定、低成本，最好还能自己维护。经过一番调研和折腾，我最终选定了OpenClaw这个开源框架，结合腾讯云的资源，成功地把一个AI“学长”塞进了我们的班级群。现在，它已经默默无闻地服务了两个月，效果远超预期。接下来，我就把这套从零到一的搭建过程、核心原理以及我踩过的那些坑，毫无保留地分享出来。

2. OpenClaw：为何它是打造智能助教的“瑞士军刀”

在决定技术方案时，我考察过不少路径。比如直接用一些现成的QQ机器人框架，但它们大多只提供了基础的聊天和群管理功能，智能对话能力要么很弱，要么需要对接昂贵的商用API。也想过自己从头写一个，但光是处理QQ协议、对接大模型、设计技能插件，工作量就大得吓人。直到我发现了OpenClaw，它几乎完美地契合了我的所有需求。

2.1 OpenClaw的核心定位与优势

OpenClaw本质上是一个开源、可扩展的AI Agent（智能体）框架。你可以把它理解为一个“机器人操作系统”。它不只是一个聊天机器人，而是一个能够集成多种AI能力（如对话、知识库查询、工具调用）并执行复杂任务的智能中枢。对于班级助教这个场景，它的优势非常明显：

1. 模块化与技能（Skill）体系：OpenClaw采用“核心框架 + 技能插件”的架构。核心框架负责基础的生命周期管理、消息路由和上下文保持。而具体的功能，比如“回答数学问题”、“查询课表”、“从群文件里找资料”，都被封装成一个个独立的Skill（技能）。这意味着我可以像搭积木一样，按需启用或开发技能，非常灵活。班级需要什么功能，我就安装什么技能。
2. 强大的大模型集成能力：OpenClaw原生支持对接多种主流大语言模型（LLM），如GPT、Claude、通义千问、文心一言等。它负责处理复杂的对话逻辑、意图识别和任务规划，而大模型则充当“大脑”，提供理解和生成能力。这种解耦设计让我可以自由选择性价比最高或效果最好的模型，而不用被某个供应商绑定。
3. 多平台适配器（Adapter）：这是让我最终选择它的关键。OpenClaw通过不同的Adapter（适配器）来连接外部平台。除了QQ，它理论上可以接入微信、钉钉、飞书、Discord等几乎所有主流IM工具。我只需要配置好QQ的Adapter，我的AI助教就能在QQ群里“活”起来。这避免了针对某个IM协议进行繁琐的底层开发。
4. 开源与社区驱动：作为开源项目，OpenClaw的代码透明，我可以根据班级的特殊需求进行二次开发。活跃的社区也意味着遇到问题时，有更多找到解决方案的可能。

2.2 技术栈全景图

为了让这个“智能助教”跑起来，我最终搭建的技术栈如下：

• 核心框架：OpenClaw（运行在Docker容器中）。
• 计算与部署平台：腾讯云轻量应用服务器。选择它是因为性价比高，自带公网IP，对于学生党和小型项目非常友好，而且与OpenClaw的某些国内部署优化很契合。
• “大脑”提供商：我选择了DeepSeek的API。原因很简单：在中文场景下表现优异，价格实惠（甚至有免费额度），API稳定且响应速度快，非常适合教育类问答。
• 消息通道：通过OpenClaw的onebotv11协议适配器连接到一个开源的QQ机器人实现（如go-cqhttp），从而间接接入QQ。
• 持久化与知识库：使用腾讯云对象存储（COS）来存放班级的公共文档、图片，并利用OpenClaw的向量数据库技能，将课程PPT、实验手册等文档切片存入，实现基于语义的资料检索。

这套组合拳下来，成本可控（服务器+少量API调用费），能力全面，并且完全自主可控。

3. 从零部署：在腾讯云上搭建OpenClaw运行环境

理论讲完，开始动手。整个部署过程可以分为三个主要阶段：准备云服务器、部署OpenClaw核心、配置QQ连接桥。我会详细说明每一步的操作和背后的原因。

3.1 腾讯云服务器初始化与关键配置

我选用的是腾讯云轻量应用服务器，配置为2核4G，系统镜像选择Ubuntu 22.04 LTS。为什么是Ubuntu？因为绝大多数开源项目的Docker镜像和部署脚本对Ubuntu的支持最完善，社区资料也最多。

购买并启动服务器后，第一件事不是急着安装软件，而是进行安全加固：

1. 修改SSH端口：通过控制台或SSH登录后，编辑/etc/ssh/sshd_config文件，将Port 22改为一个1024-65535之间的随机端口（例如Port 23456）。这能有效减少被自动化脚本爆破的风险。
2. 设置防火墙：腾讯云轻量服务器有自带防火墙，务必在控制台只开放必要的端口：你修改后的SSH端口（如23456）、后续OpenClaw可能需要用到的Web端口（如8080），以及QQ机器人桥接服务go-cqhttp需要用到的端口（通常是5700, 6700）。切记，不要图省事放行所有端口。
3. 创建非root用户：永远不要用root用户直接操作。使用adduser openclaw创建一个新用户，并把它加入sudo组。后续的所有操作，都尽量在这个用户下进行。

注意：很多部署失败，问题都出在最初的系统环境上。确保你的系统源是有效的，可以运行sudo apt update && sudo apt upgrade -y进行一次全面的更新。

3.2 通过Docker安装与启动OpenClaw

OpenClaw官方推荐使用Docker部署，这能解决环境依赖的噩梦。如果你的系统没有安装Docker和Docker Compose，请先安装。

# 安装Docker curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER # 将当前用户加入docker组，避免每次用sudo newgrp docker # 刷新组权限，或退出重新登录 # 安装Docker Compose (v2) sudo apt install docker-compose-plugin -y

接下来，获取OpenClaw的部署配置文件。通常社区会提供一个docker-compose.yml示例。

mkdir openclaw && cd openclaw # 假设从官方仓库获取示例配置，这里需要替换为真实的配置文件地址 # wget https://raw.githubusercontent.com/.../docker-compose.yml # 由于地址可能变化，请务必查阅OpenClaw官方文档获取最新的配置。

一个简化的docker-compose.yml核心部分可能长这样：

version: '3.8' services: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: unless-stopped ports: - "8080:8080" # 将容器内Web管理端口映射到主机 volumes: - ./data:/app/data # 挂载数据目录，持久化配置和技能 - ./logs:/app/logs # 挂载日志目录 environment: - OPENCLAW_API_KEY=your-initial-api-key-here # 用于内部通信的密钥 - LLM_PROVIDER=deepseek # 指定大模型提供商 - DEEPSEEK_API_KEY=your-deepseek-api-key # 你的DeepSeek API Key - DEEPSEEK_BASE_URL=https://api.deepseek.com networks: - openclaw-net networks: openclaw-net: driver: bridge

在启动前，你需要去DeepSeek官网注册并获取一个API Key，替换掉上面的your-deepseek-api-key。OPENCLAW_API_KEY可以自己生成一个复杂的随机字符串。

配置好后，运行docker compose up -d，OpenClaw核心服务就会在后台启动。你可以通过docker logs -f openclaw查看实时日志，确认没有报错。访问http://你的服务器IP:8080应该能看到OpenClaw的管理界面（如果镜像提供了的话）或健康检查页面。

3.3 配置QQ机器人桥接：go-cqhttp详解

OpenClaw本身不直接连接QQ，它通过标准协议与“机器人客户端”通信。这里我们选用最流行的go-cqhttp。它是一个用Go语言编写的、实现了OneBot v11协议的QQ客户端。

1. 下载与配置：在服务器上单独创建一个目录用于运行go-cqhttp。

   mkdir ~/go-cqhttp && cd ~/go-cqhttp # 从GitHub Release页面下载对应系统架构的最新版本，例如Linux amd64 wget https://github.com/Mrs4s/go-cqhttp/releases/download/v1.2.0/go-cqhttp_linux_amd64.tar.gz tar -zxvf go-cqhttp_linux_amd64.tar.gz chmod +x go-cqhttp

2. 生成配置文件：首次运行./go-cqhttp，选择3 - 反向WebSocket模式。这会在目录下生成一个config.yml文件。我们需要编辑几个关键部分：

   account: uin: 123456789 # 你的机器人QQ号 password: '' # 密码，但更推荐用扫码登录，这里留空 encrypt: false # 是否启用加密，通常关闭 # 连接设置 connection: protocol: 0 # 0: 安卓手机，1: 安卓平板，2: 安卓手表，3: MacOS，4: 企点。通常用0或1。 use-sso-address: true # 反向WebSocket服务器设置 servers: - ws-reverse: universal: ws://你的服务器内网IP:8080/onebot/v11/ws # 指向OpenClaw的WebSocket端点 reconnect-interval: 5000 max-reconnection-attempts: 0 # 无限重连

   重点解释：universal地址填写的是OpenClaw容器内部的地址和端口。因为go-cqhttp和openclaw通过Docker网络通信。如果你按照上面的docker-compose.yml配置，并且两者在同一台服务器，那么OpenClaw的服务名就是openclaw，端口是容器内的8080。因此这里通常填ws://openclaw:8080/onebot/v11/ws。如果go-cqhttp运行在宿主机（而非容器内），则需要填写宿主机能访问到的OpenClaw的地址，例如如果OpenClaw映射了宿主机的8081端口，则可能是ws://localhost:8081/onebot/v11/ws。这是最容易出错的地方之一。

3. 登录与运行：配置好后，再次运行./go-cqhttp。程序会提示你扫码登录（推荐）或输入密码。登录成功后，go-cqhttp就会以反向WebSocket的方式，主动连接到OpenClaw，并将收到的QQ消息转发过去，同时将OpenClaw的回复发回QQ。

至此，基础设施的搭建就完成了。你的QQ机器人已经在线，并且背后连接着OpenClaw框架。但此时它还是个“空壳”，因为还没有给它安装任何“技能”。

4. 技能开发实战：为班级助教注入灵魂

OpenClaw的强大在于其技能系统。我们的AI助教需要哪些技能？我根据班级需求，规划了三个核心技能：智能问答、资料检索和群管理。下面以“智能问答”技能为例，详细讲解开发过程。

4.1 技能（Skill）的基本结构

一个OpenClaw技能本质上是一个Python包，它有固定的目录结构。我们可以在OpenClaw挂载的data/skills目录下创建我们的技能。

my_class_assistant_skill/ ├── __init__.py ├── config.yaml ├── skill.py └── requirements.txt (可选)

• __init__.py: 标识这是一个Python包，可以为空。
• config.yaml: 技能的配置文件，定义技能的名称、描述、触发方式等。
• skill.py: 技能的核心逻辑代码。
• requirements.txt: 列出技能所需的额外Python依赖。

4.2 编写智能问答技能：连接大模型

首先看config.yaml，它定义了技能的元信息：

name: class_assistant_qa description: 班级智能助教问答核心技能 version: 1.0.0 author: YourName # 触发条件：当消息以“@助教”开头，或者直接私聊机器人时触发 triggers: - type: command command: ["@助教"] prefix: true # 作为前缀触发 - type: direct_message # 私聊消息 # 技能参数，可以在管理界面配置 parameters: - name: temperature type: float default: 0.7 description: 生成答案的随机性

接下来是核心的skill.py。OpenClaw框架会注入一些工具和上下文给我们使用。

import logging from typing import Dict, Any from openclaw.skill import BaseSkill, SkillContext logger = logging.getLogger(__name__) class ClassAssistantQASkill(BaseSkill): """班级助教问答技能""" def __init__(self, context: SkillContext): super().__init__(context) # 从配置中读取参数 self.temperature = self.config.get("temperature", 0.7) # 获取框架内置的LLM客户端 self.llm_client = context.get_service("llm_client") async def handle(self, message: Dict[str, Any]) -> Dict[str, Any]: """处理消息的核心方法""" user_message = message.get("text", "").strip() # 移除触发命令，例如“@助教 什么是微积分？” -> “什么是微积分？” if user_message.startswith("@助教"): user_message = user_message[3:].strip() if not user_message: return {"reply": "你好，我是班级智能助教，请问有什么可以帮你的吗？"} # 构建给大模型的提示词（Prompt） system_prompt = """你是一个专业的大学班级助教，负责解答同学们在学习、生活、校园事务中遇到的问题。 请用友好、清晰、准确的语言回答。如果问题涉及专业课程，请确保答案的准确性。 如果不知道答案，请诚实告知，并建议同学查阅教材或咨询老师。 回答请尽量简洁，突出重点。""" user_prompt = user_message try: # 调用大模型生成回复 response = await self.llm_client.chat_completion( model="deepseek-chat", # 指定模型 messages=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt} ], temperature=self.temperature, max_tokens=1024 ) answer = response.choices[0].message.content.strip() logger.info(f"成功回复用户问题: {user_message[:50]}...") return {"reply": answer} except Exception as e: logger.error(f"调用大模型失败: {e}", exc_info=True) # 失败时返回友好的错误信息 return {"reply": "抱歉，助教现在有点晕，请稍后再试一下。"} async def cleanup(self): """技能卸载时的清理工作""" logger.info("班级助教问答技能正在关闭...")

4.3 技能的热加载与调试

将技能目录放到OpenClaw挂载的data/skills下后，OpenClaw支持热加载。你可以在管理界面（如果有）或通过发送特定命令（如!reload skills）来重新加载技能。更简单的方法是重启OpenClaw容器：docker compose restart openclaw。

调试阶段，查看日志至关重要：

docker logs -f openclaw # 查看OpenClaw核心日志 # 另外开一个终端，查看go-cqhttp日志 tail -f ~/go-cqhttp/logs/最新日期.log

通过日志，你可以看到消息是如何流转的：QQ消息 -> go-cqhttp -> OpenClaw (路由到对应技能) -> 调用LLM -> 生成回复 -> 返回给go-cqhttp -> 发送到QQ。任何一个环节出错，日志都会体现。

4.4 扩展技能：资料检索与群管理

有了问答技能的基础，其他技能的开发模式是类似的：

• 资料检索技能：这个技能更复杂一些。它需要结合向量数据库。流程是：先将班级的课程PDF、Word文档通过文本分割、向量化，存入ChromaDB或Milvus等向量数据库。当同学问“第三章的课后习题答案在哪？”时，技能会先将问题转换成向量，在向量库中搜索最相关的文档片段，然后将这些片段作为上下文，连同问题一起提交给大模型，让大模型生成一个基于资料的精准回答。这避免了“幻觉”，回答更有依据。
• 群管理技能：这个技能主要调用go-cqhttp提供的API来实现。例如，可以开发一个“自动签到”技能，每天上午在群里发布签到指令，识别同学的回复并进行统计。或者一个“关键词监控”技能，当群里出现“实验报告”、“截止日期”等关键词时，自动提醒相关事项。这些功能的实现，依赖于对QQ群消息事件（notice）和API调用（如禁言、踢人、发送群公告）的熟练使用。

5. 避坑实录：那些让我熬夜的典型问题与解决方案

在实际部署和运行过程中，我遇到了无数问题。下面挑几个最具代表性的，把排查过程和解决方案详细记录下来，希望能帮你节省大量时间。

5.1 网络连接与容器间通信故障

• 问题现象：go-cqhttp日志不断显示连接OpenClaw的WebSocket失败，提示connection refused或timeout。
• 排查思路：
  1. 确认OpenClaw是否在运行：docker ps查看openclaw容器状态是否为Up。
  2. 确认端口映射和内部端口：docker-compose.yml中是否将容器内的端口（如8080）映射到了宿主机？go-cqhttp配置中universal地址指向的是否正确？这里是最常见的错误点。
     • 场景A：go-cqhttp运行在宿主机，OpenClaw运行在容器。那么universal应指向宿主机的IP和映射出来的端口，例如ws://localhost:8080/...（如果映射到宿主机8080）。
     • 场景B：两者都运行在Docker容器中，且在同一docker-compose.yml下。那么universal应指向服务名和容器内部端口，例如ws://openclaw:8080/...。同时，确保go-cqhttp的服务定义在docker-compose.yml中，并且两者在同一个自定义网络（如上面的openclaw-net）下。
  3. 检查防火墙：宿主机防火墙、云服务商安全组是否放行了相关端口？
  4. 检查OpenClaw的WebSocket端点：OpenClaw的OneBot适配器是否成功加载并监听在正确路径？查看OpenClaw启动日志，确认类似Loaded adapter: onebot_v11和WebSocket server started on /onebot/v11/ws的信息。
• 我的解决方案：我采用的是场景B，将go-cqhttp也容器化，与OpenClaw放在同一个docker-compose.yml中，使用服务名通信，彻底避免了宿主机网络配置的复杂性。

5.2 大模型API调用异常：{ "error": { "code": 400 ... }

• 问题现象：技能能触发，但日志报错，类似openclaw llamap svr operator(): got exception: { "error": { "code": 400, "message": "..." }。这是我在使用某个LLM提供商时遇到的真实错误。
• 排查思路：
  1. API Key是否正确：首先检查环境变量DEEPSEEK_API_KEY（或其他LLM的KEY）是否设置正确，是否包含多余空格或换行。
  2. 模型名称是否正确：检查skill.py中model参数是否与提供商支持的模型列表一致。例如DeepSeek可能是deepseek-chat，而误写成gpt-3.5-turbo就会报错。
  3. 请求格式或参数问题：不同的LLM提供商对请求体（如messages的格式、temperature范围）可能有细微要求。OpenClaw的LLM客户端抽象层可能没有完全适配。需要查看OpenClaw对应LLM适配器的源码，或者查看更详细的错误信息。
  4. 额度或频率限制：检查API账户是否有余额，是否达到了速率限制（RPM/TPM）。
• 我的解决方案：通过增加日志级别，我捕获了完整的错误响应体，发现是max_tokens参数超出了该模型的最大限制。调整该参数后问题解决。关键技巧：在技能代码的except Exception as e:块中，将完整的异常信息打印到日志，这是定位第三方API问题最快的方法。

5.3 技能加载失败或行为异常

• 问题现象：技能目录放好了，重启后OpenClaw日志显示技能加载失败，或者技能被触发后无反应。
• 排查思路：
  1. Python依赖：检查技能目录下的requirements.txt，确保所有依赖在OpenClaw的运行环境中已安装。OpenClaw容器可能没有这些包。一种方法是在构建自定义Docker镜像时安装，另一种是在技能加载时动态安装（如果框架支持）。
  2. 语法错误：技能代码本身存在Python语法错误。可以在宿主机上先python -m py_compile skill.py检查一下。
  3. 配置错误：config.yaml的格式不符合YAML规范，或者triggers配置有误。确保缩进是空格而非Tab。
  4. 权限问题：技能目录或文件对运行OpenClaw的用户（容器内通常是非root用户）不可读。
• 我的解决方案：我养成了一个习惯，在开发技能时，先在本地一个简单的Python脚本中模拟测试核心逻辑（比如直接调用LLM API），确保无误后再放入技能目录。同时，充分利用OpenClaw的日志，将技能内部的运行状态（如“收到消息”、“开始调用LLM”、“调用成功”）详细打印出来，便于追踪流程。

5.4 QQ账号风控与掉线问题

• 问题现象：机器人运行一段时间后突然掉线，go-cqhttp提示需要重新扫码登录，甚至账号被临时冻结。
• 排查思路与缓解措施：
  1. 行为模拟：腾讯对非官方客户端的检测越来越严格。避免机器人高频、重复地发送消息，尤其是内容相似的消息。在技能设计中加入随机延迟和更人性化的回复变化。
  2. 协议选择：go-cqhttp的protocol参数尝试使用不同的值（如从安卓手机切换到安卓平板），有时能缓解风控。
  3. 使用现成解决方案：考虑使用基于手表协议、MacOS协议等更稳定的第三方签名服务或客户端，但这可能涉及更复杂的部署和一定费用。
  4. 备用方案：这是使用QQ作为通道的最大风险。务必有一个备用通知方案，例如将关键错误日志通过邮件或Server酱发送到自己的手机。同时，可以考虑将核心技能适配到更开放的平台，如Discord或Telegram，作为备份通道。
• 我的心得：对于班级内部使用，频率不高，内容健康，我使用“安卓平板”协议，并让机器人以“潜水”为主，仅在@它或私聊时才响应，大大降低了风控概率。运行两个月来，仅因网络波动掉线过几次，扫码重连即可。

6. 优化与展望：让助教更聪明、更贴心

基础功能跑通后，就可以着手优化体验和增加高级功能了。

6.1 上下文记忆与会话管理

默认情况下，每次问答都是独立的。但实际对话往往有上下文，比如同学问“微积分难吗？”，接着问“那该怎么学呢？”。为了让AI助教记住之前的对话，需要在技能中实现上下文管理。OpenClaw框架通常提供了会话（Session）机制。你可以在handle方法中，通过message.get("session_id")来获取当前会话，并将历史对话记录存储起来（例如存到Redis或数据库），在构建Prompt时，将最近几轮的历史记录也包含进去。这样，AI就能进行连续对话了。

6.2 工具调用（Function Calling）增强能力

大模型不仅会聊天，还能通过“工具调用”执行具体操作。OpenClaw支持定义工具（Tool）。例如，我可以定义一个“查询课表”的工具，当同学问“今天下午有什么课？”时，AI会先识别出需要调用“查询课表”工具，然后技能代码就去查询数据库或在线日历，将结果返回给AI，由AI组织成自然语言回复给同学。这极大地扩展了机器人的能力边界，从“问答机”变成了“执行者”。

6.3 成本监控与优化

使用大模型API是按Token收费的。虽然DeepSeek等国内模型成本很低，但长期运行仍需关注。可以在技能代码中统计每次对话的输入输出Token数，并定期汇总。对于资料检索技能，优化向量搜索的精度，减少不必要的上下文长度，可以有效降低成本。另外，对于一些固定问答（如“班长电话多少？”），完全可以配置成本地的问答对（QA Pair），直接匹配回复，无需调用大模型。

6.4 多群管理与权限控制

我们的助教目前只在一个班群。如果想推广到年级群或社团群，就需要考虑多群组管理和权限隔离。可以在技能中通过message.get("group_id")来区分消息来源，并为不同群组加载不同的配置或知识库。甚至可以实现管理员指令，只有特定的QQ号才能让机器人执行清空数据、更新技能等敏感操作。

这个项目从构思到落地，花了将近三周的时间，大部分时间都在调试和踩坑。但看到它在群里真正帮到同学们时，觉得一切都很值得。技术最大的乐趣，莫过于用它解决真实世界的问题。如果你也想为自己的小团体打造一个智能助手，OpenClaw是一个非常不错的起点。它就像一副乐高骨架，剩下的，就靠你的想象力去搭建了。