1. 项目概述：为什么需要一个可维护的OpenClaw技能结构？

最近在折腾OpenClaw，一个挺有意思的本地AI智能体框架。很多朋友跟着教程把环境跑起来，接入了飞书或者微信，让AI能自动回复消息，感觉挺酷。但玩上几天，问题就来了：想加个新功能，比如让AI查个天气或者控制下智能家居，发现代码东一块西一块，改起来小心翼翼，生怕把原来的对话逻辑搞崩。更头疼的是，从社区或GitHub上看到一个很棒的技能（Skill），想集成进来，却发现对方的代码风格、配置文件和自己项目里的完全对不上，复制粘贴都无从下手。

这就是典型的“能跑起来，但不好维护”的状态。OpenClaw本身设计很灵活，但官方文档更多是教你“怎么用”，而不是“怎么组织”。如果你只是写一两个简单的技能脚本，问题不大。但当你打算把它当作一个长期运行、功能不断扩展的生产力工具或自动化中枢时，一个混乱的项目结构会成为你最大的绊脚石。每次添加新技能都像在走钢丝，调试一个技能可能意外影响另一个，团队协作更是无从谈起。

所以，我们今天不聊怎么安装OpenClaw（网上教程很多了），也不聊基础指令。我们聚焦一个更核心、但常被忽略的问题： 如何从零开始，搭建一个清晰、可扩展、易于协作的OpenClaw技能项目结构 。这个结构的目标是，让你或你的团队在半年后回头看，依然能快速找到任何功能的代码，轻松添加新技能，并且能安全地进行测试和部署。我会基于我实际部署和维护多个OpenClaw项目的经验，分享一套经过验证的目录组织和代码规范，你可以直接“抄作业”。

2. 核心设计思路：模块化、配置化与依赖隔离

在动手创建目录和文件之前，我们先明确三个核心设计原则。这决定了你的项目是“一次性玩具”还是“可长期服役的工具”。

2.1 技能（Skill）的模块化封装

OpenClaw的技能本质是一段能处理特定任务（如问答、工具调用）的代码。模块化的核心思想是 “高内聚、低耦合” 。

• 高内聚 ：一个技能只负责一件事，并且把所有相关的逻辑（对话处理、API调用、数据处理）都封装在自己内部。比如，一个“天气查询”技能，它应该自己包含解析用户意图、调用天气API、格式化回复文本的全部代码。
• 低耦合 ：技能之间尽可能不要直接调用对方的函数或读写对方的变量。它们通过OpenClaw框架定义的标准接口（输入、输出）进行通信。这样，修改或删除一个技能，不会影响到其他技能。

在实际项目中，这意味着每个技能都应该是一个独立的Python模块（一个文件夹或一个.py文件），拥有清晰的边界。

2.2 配置与代码分离

千万不要把API密钥、模型地址、服务器端口这些可变参数硬编码在你的技能逻辑里。一旦需要更换模型或调整参数，你就得去翻代码，既危险又低效。

• 集中管理 ：使用一个或多个配置文件（如 config.yaml , .env ）来统一管理所有配置项。
• 环境区分 ：配置应该支持环境区分，比如 development （开发）、 testing （测试）、 production （生产）。开发时用测试用的API Key和本地模型，上线时用生产环境的配置，互不干扰。
• 技能专属配置 ：除了全局配置，每个技能也可以有自己独立的配置节，用于管理技能特有的参数。

2.3 依赖管理的清晰化

OpenClaw技能可能会依赖各种第三方库，比如 requests 调用API， pydantic 做数据验证， sqlalchemy 操作数据库。

• 统一声明 ：使用 requirements.txt 或更现代的 pyproject.toml 来明确定义项目依赖及其版本。
• 按需分组 ：可以将依赖分组，例如 base （基础运行）、 skills （技能特定）、 dev （开发工具）。这样在部署生产环境时，可以只安装必要的包。
• 虚拟环境 ：务必使用 venv , conda 或 poetry 等工具创建独立的Python虚拟环境，避免污染系统Python环境，也便于不同项目使用不同版本的库。

遵循以上思路，我们构建的项目结构将自然具备良好的可维护性。

3. 可维护项目结构蓝图与详解

下面是我推荐的一个标准项目结构。它看起来可能比简单的单文件脚本复杂，但每一项都有其存在的必要，长期来看会极大节省你的时间。

your_openclaw_project/
├── .env.example                    # 环境变量示例文件
├── .gitignore                     # Git忽略文件
├── pyproject.toml                 # 项目依赖和元数据（推荐）
├── README.md                      # 项目说明文档
├── config/                        # 配置目录
│   ├── __init__.py
│   ├── settings.py                # 主配置加载逻辑
│   └── config.yaml                # 主配置文件（或按环境拆分）
├── core/                          # 核心框架与扩展
│   ├── __init__.py
│   ├── cli.py                     # 自定义命令行工具
│   └── extensions.py              # 自定义框架扩展（如中间件）
├── skills/                        # 技能包目录（核心）
│   ├── __init__.py
│   ├── base_skill.py              # 技能基类，定义通用接口
│   ├── weather/                   # 示例技能：天气查询
│   │   ├── __init__.py
│   │   ├── skill.py               # 技能主逻辑
│   │   ├── config.yaml            # 技能专属配置
│   │   └── schemas.py             # 技能用到的数据模型
│   ├── todo_manager/              # 示例技能：待办管理
│   │   ├── __init__.py
│   │   ├── skill.py
│   │   ├── models.py              # 数据库模型（如果用到）
│   │   └── crud.py                # 数据库操作
│   └── ...                        # 其他技能
├── storage/                       # 数据存储目录
│   ├── database/                  # SQLite或其他数据库文件
│   └── files/                     # 技能生成或下载的文件
├── tests/                         # 测试目录
│   ├── __init__.py
│   ├── conftest.py                # Pytest共享配置
│   ├── test_skills/               # 技能测试
│   │   ├── test_weather.py
│   │   └── test_todo.py
│   └── test_core/                 # 核心逻辑测试
├── scripts/                       # 辅助脚本目录
│   ├── deploy.sh                  # 部署脚本
│   └── backup_data.sh             # 数据备份脚本
└── main.py                        # 应用主入口

3.1 关键目录与文件职责解析

skills/ 目录 ：这是项目的灵魂。每个子目录代表一个独立的技能。 base_skill.py 定义了所有技能必须实现的接口（例如一个 execute 方法），这保证了统一性。技能目录内的 config.yaml 让技能配置独立且可覆盖全局配置。

config/ 目录 ：集中管理所有配置。 settings.py 负责从环境变量、 config.yaml 、技能配置中按优先级加载并合并配置，形成一个全局可访问的配置对象。使用Pydantic进行配置验证是很好的实践，能避免配置错误导致运行时崩溃。

core/ 目录 ：存放对OpenClaw框架本身的轻量级封装或扩展。比如，你可能会写一个自定义的日志中间件放在 extensions.py 里，或者创建一个统一的异常处理器。 cli.py 可以让你通过 python -m core.cli --help 的方式运行一些管理命令，比如初始化数据库、检查技能状态等。

storage/ 目录 ：明确数据存放位置。将数据库文件、上传的图片、技能生成的报告等统一放在这里，便于备份，也避免在代码库中提交大文件或敏感数据。

tests/ 目录 ：可维护性的基石。为每个技能编写单元测试和集成测试，确保修改代码后原有功能正常。 conftest.py 可以定义测试用的固定数据（fixtures），如模拟的OpenClaw会话对象。

scripts/ 目录 ：将常用的、复杂的命令行操作脚本化。比如一键部署、数据迁移、日志清理等。这降低了操作门槛，也减少了误操作。

main.py ：尽可能简洁。它只负责三件事：1. 加载配置；2. 初始化OpenClaw框架并注册所有在 skills/ 目录中找到的技能；3. 启动服务。

注意 ：这种结构初看有些“重”，但对于超过3个技能或需要协作的项目，其优势是压倒性的。它强制你进行清晰的逻辑划分，当项目规模增长时，你不需要重构，只需按规则添加新模块。

4. 从零搭建：一步步实现与编码规范

现在，我们抛开理论，动手从零创建这个结构。假设我们的项目叫 my_openclaw_agent 。

4.1 初始化项目与虚拟环境

首先，创建项目根目录并初始化虚拟环境。我强烈推荐使用 uv 或 poetry 这类现代工具，它们能更好地管理依赖和项目元数据。这里以 poetry 为例。

# 1. 创建项目目录
mkdir my_openclaw_agent && cd my_openclaw_agent

# 2. 初始化poetry项目（如果没有poetry，请先安装：pip install poetry）
poetry init -n  # -n 跳过交互问答，稍后编辑pyproject.toml

# 3. 创建基础目录结构
mkdir -p config core skills/weather skills/todo_manager storage/{database,files} tests/{test_skills,test_core} scripts

# 4. 创建所有 __init__.py 文件（让Python将其视为包）
find . -type d -name "[a-zA-Z]*" -exec touch {}/__init__.py \;

接下来，编辑 pyproject.toml 文件。这是项目的“身份证”和“菜单”。

# pyproject.toml
[tool.poetry]
name = "my-openclaw-agent"
version = "0.1.0"
description = "A maintainable OpenClaw agent with modular skills."
authors = ["Your Name <you@example.com>"]

[tool.poetry.dependencies]
python = "^3.9"
open-claw = "^0.2.0"  # 请检查最新版本
pydantic = "^2.0"
pydantic-settings = "^2.0"  # 用于配置管理
requests = "^2.31.0"
sqlalchemy = "^2.0.0"  # 如果技能需要数据库
python-dotenv = "^1.0.0"  # 加载.env文件

[tool.poetry.group.dev.dependencies]
pytest = "^7.0.0"
pytest-asyncio = "^0.21.0"  # OpenClaw多异步，测试需要
black = "^23.0.0"  # 代码格式化
isort = "^5.12.0"  # 导入排序
pre-commit = "^3.0.0"  # Git提交前钩子

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

然后，安装依赖： poetry install 。这会同时安装项目依赖和开发依赖。

4.2 实现配置管理中心

在 config/ 目录下创建 config.yaml 和 settings.py 。

# config/config.yaml
openclaw:
  model: "qwen:7b"  # 默认使用的模型
  base_url: "http://localhost:11434"  # Ollama地址
  system_prompt: "你是一个乐于助人的AI助手。"

logging:
  level: "INFO"
  file: "storage/app.log"

skills:
  weather:
    enabled: true
    api_key: ""  # 从环境变量覆盖
    default_city: "北京"
  todo_manager:
    enabled: true
    database_url: "sqlite:///storage/database/todos.db"

# config/settings.py
from pydantic_settings import BaseSettings, SettingsConfigDict
from pydantic import Field, validator
import yaml
from pathlib import Path
from typing import Any, Dict

class SkillSettings(BaseSettings):
    enabled: bool = True
    # 其他技能通用配置...

class WeatherSkillSettings(SkillSettings):
    api_key: str = Field("", validation_alias="WEATHER_API_KEY") # 优先从环境变量读
    default_city: str = "北京"

class TodoSkillSettings(SkillSettings):
    database_url: str = "sqlite:///storage/database/todos.db"

class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        extra="ignore"  # 忽略配置文件中未定义的字段
    )

    openclaw_model: str = "qwen:7b"
    openclaw_base_url: str = "http://localhost:11434"
    openclaw_system_prompt: str = "你是一个乐于助人的AI助手。"

    log_level: str = "INFO"
    log_file: Path = Path("storage/app.log")

    # 技能配置
    weather: WeatherSkillSettings = WeatherSkillSettings()
    todo_manager: TodoSkillSettings = TodoSkillSettings()

    @classmethod
    def from_yaml(cls, yaml_path: Path = Path("config/config.yaml")) -> "Settings":
        """从YAML文件加载配置，并和环境变量合并"""
        if not yaml_path.exists():
            return cls()
        with open(yaml_path, 'r', encoding='utf-8') as f:
            yaml_config = yaml.safe_load(f) or {}
        # 这里可以实现更复杂的合并逻辑，例如深度合并字典
        # 简化处理：将YAML配置扁平化后传入
        flattened_config = cls._flatten_dict(yaml_config)
        return cls(**flattened_config)

    @staticmethod
    def _flatten_dict(d: Dict, parent_key: str = '', sep: '_') -> Dict:
        """将嵌套字典扁平化，例如 {'openclaw': {'model': 'x'}} -> {'openclaw_model': 'x'}"""
        items = []
        for k, v in d.items():
            new_key = f"{parent_key}{sep}{k}" if parent_key else k
            if isinstance(v, dict):
                items.extend(Settings._flatten_dict(v, new_key, sep).items())
            else:
                items.append((new_key, v))
        return dict(items)

# 创建全局配置对象
settings = Settings.from_yaml()

这个 Settings 类做了几件关键事：1. 优先从 .env 文件读取敏感信息（如API Key）；2. 从 config.yaml 读取通用配置；3. 通过Pydantic进行类型验证和默认值设置；4. 提供了一个全局可访问的 settings 对象。

4.3 定义技能基类与实现示例技能

在 skills/base_skill.py 中定义所有技能的契约。

# skills/base_skill.py
from abc import ABC, abstractmethod
from typing import Any, Dict, Optional
from open_claw import Skill

class BaseSkill(ABC):
    """所有技能的抽象基类"""
    name: str  # 技能唯一标识，如 "weather"
    description: str  # 技能描述，用于帮助系统理解

    def __init__(self, config: Dict[str, Any]):
        self.config = config
        self._initialized = False

    async def initialize(self):
        """异步初始化技能（如建立数据库连接、加载模型）"""
        if not self._initialized:
            await self._setup()
            self._initialized = True

    @abstractmethod
    async def _setup(self):
        """子类必须实现的初始化逻辑"""
        pass

    @abstractmethod
    async def execute(self, input_text: str, context: Optional[Dict] = None) -> str:
        """
        执行技能的核心方法
        Args:
            input_text: 用户输入或处理后的文本
            context: 会话上下文信息（如用户ID、历史）
        Returns:
            技能的文本输出
        """
        pass

    def to_openclaw_skill(self) -> Skill:
        """将本技能实例转换为OpenClaw框架可识别的Skill对象"""
        from functools import wraps
        async def wrapper(state, **kwargs):
            # 这里可以添加统一的预处理、日志、错误处理
            result = await self.execute(state.get("message", ""), context=state)
            return result
        return Skill(name=self.name, description=self.description, function=wrapper)

现在，实现一个具体的天气技能。创建 skills/weather/skill.py 。

# skills/weather/skill.py
import aiohttp
import asyncio
from typing import Dict, Any, Optional
from skills.base_skill import BaseSkill
from config.settings import settings

class WeatherSkill(BaseSkill):
    name = "weather"
    description = "查询指定城市的当前天气情况。"

    def __init__(self):
        # 从全局配置中获取该技能的配置
        super().__init__(config=vars(settings.weather))
        self.api_key = self.config.get('api_key')
        self.default_city = self.config.get('default_city', '北京')
        self.api_url = "https://api.weatherapi.com/v1/current.json"  # 示例API

    async def _setup(self):
        """初始化，这里可以验证API Key是否有效"""
        if not self.api_key:
            raise ValueError("Weather API Key 未配置。请在 .env 文件中设置 WEATHER_API_KEY。")
        # 可以做一个简单的连通性测试
        # async with aiohttp.ClientSession() as session:
        #     ...

    async def execute(self, input_text: str, context: Optional[Dict] = None) -> str:
        """
        解析用户输入，调用天气API，返回格式化结果。
        示例输入: "北京天气怎么样？" 或 "查询上海天气"
        """
        # 1. 简单的意图/实体解析（这里可以替换成更复杂的NLP模型）
        city = self._extract_city(input_text) or self.default_city

        # 2. 调用外部API
        try:
            weather_data = await self._fetch_weather(city)
        except aiohttp.ClientError as e:
            return f"抱歉，获取{city}的天气信息时出错：{e}"

        # 3. 格式化回复
        return self._format_response(weather_data, city)

    def _extract_city(self, text: str) -> Optional[str]:
        # 非常简单的关键词匹配，实际项目应使用更可靠的方法（如正则、NER）
        import re
        # 假设城市名在“查询”、“天气”等词之后
        match = re.search(r'(?:查询|查看)?(.+?)的?天气', text)
        if match:
            return match.group(1).strip()
        # 也可以从上下文（context）中获取上次询问的城市
        return None

    async def _fetch_weather(self, city: str) -> Dict[str, Any]:
        params = {
            'key': self.api_key,
            'q': city,
            'aqi': 'no'
        }
        async with aiohttp.ClientSession() as session:
            async with session.get(self.api_url, params=params, timeout=10) as resp:
                resp.raise_for_status()
                return await resp.json()

    def _format_response(self, data: Dict, city: str) -> str:
        current = data.get('current', {})
        temp_c = current.get('temp_c', 'N/A')
        condition = current.get('condition', {}).get('text', '未知')
        humidity = current.get('humidity', 'N/A')
        return f"{city}当前天气：{condition}，温度{temp_c}°C，湿度{humidity}%。"

这个技能类展示了完整的生命周期：初始化配置、异步准备、解析输入、调用外部服务、格式化输出。它完全独立，不依赖其他技能。

4.4 构建主应用与技能自动发现

最后，在 main.py 中，我们将所有部分串联起来。

# main.py
import asyncio
import logging
from pathlib import Path
from importlib import import_module
from typing import List, Type

from open_claw import OpenClaw
from config.settings import settings
from skills.base_skill import BaseSkill

def setup_logging():
    """配置日志"""
    log_format = '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
    logging.basicConfig(
        level=getattr(logging, settings.log_level.upper()),
        format=log_format,
        handlers=[
            logging.FileHandler(settings.log_file),
            logging.StreamHandler()
        ]
    )

def discover_skills() -> List[Type[BaseSkill]]:
    """
    自动发现 skills/ 目录下所有的技能类。
    约定：每个技能目录下必须有一个 skill.py，且其中包含一个继承自BaseSkill的类。
    """
    skill_classes = []
    skills_dir = Path(__file__).parent / "skills"
    # 遍历skills目录下的所有子目录
    for skill_dir in skills_dir.iterdir():
        if skill_dir.is_dir() and not skill_dir.name.startswith('_'):
            skill_module_path = f"skills.{skill_dir.name}.skill"
            try:
                module = import_module(skill_module_path)
                # 查找模块中BaseSkill的子类
                for attr_name in dir(module):
                    attr = getattr(module, attr_name)
                    if (isinstance(attr, type) and
                        issubclass(attr, BaseSkill) and
                        attr != BaseSkill):
                        skill_classes.append(attr)
                        logging.info(f"发现技能: {attr.name}")
            except ImportError as e:
                logging.warning(f"无法导入技能模块 {skill_module_path}: {e}")
                continue
    return skill_classes

async def main():
    setup_logging()
    logger = logging.getLogger(__name__)

    # 1. 发现并实例化所有技能
    skill_classes = discover_skills()
    skills_instances = []
    for SkillClass in skill_classes:
        try:
            instance = SkillClass()
            await instance.initialize()  # 执行异步初始化
            skills_instances.append(instance)
            logger.info(f"技能 '{instance.name}' 初始化成功。")
        except Exception as e:
            logger.error(f"技能 '{SkillClass.name}' 初始化失败: {e}", exc_info=True)
            # 根据配置决定是否禁用失败技能
            continue

    # 2. 转换为OpenClaw Skill对象
    openclaw_skills = [skill.to_openclaw_skill() for skill in skills_instances]

    # 3. 创建并配置OpenClaw Agent
    agent = OpenClaw(
        model=settings.openclaw_model,
        base_url=settings.openclaw_base_url,
        system_prompt=settings.openclaw_system_prompt,
        skills=openclaw_skills,
    )

    logger.info(f"OpenClaw Agent 启动成功，加载了 {len(openclaw_skills)} 个技能。")

    # 4. 这里可以根据需要启动HTTP服务器、连接飞书/微信机器人等
    # 示例：简单的控制台交互
    print("Agent已就绪。输入 'quit' 退出。")
    while True:
        try:
            user_input = input("\nYou: ").strip()
            if user_input.lower() in ['quit', 'exit', 'q']:
                break
            response = await agent.run(user_input)
            print(f"Agent: {response}")
        except KeyboardInterrupt:
            break
        except Exception as e:
            logger.error(f"处理输入时出错: {e}", exc_info=True)
            print("抱歉，处理时出现了问题。")

if __name__ == "__main__":
    asyncio.run(main())

这个主程序完成了几个关键任务：1. 动态发现并加载所有技能，无需手动注册；2. 统一初始化技能；3. 集中配置日志；4. 构建最终的Agent。你可以轻松地将控制台交互替换为WebSocket服务器或机器人框架的入口。

5. 进阶维护：测试、部署与团队协作

一个可维护的项目，光有结构还不够，还需要配套的工程实践。

5.1 为技能编写单元测试

为 skills/weather 技能编写测试。创建 tests/test_skills/test_weather.py 。

# tests/test_skills/test_weather.py
import pytest
from unittest.mock import AsyncMock, patch, MagicMock
from skills.weather.skill import WeatherSkill

@pytest.fixture
def mock_settings():
    """模拟配置"""
    class MockWeatherSettings:
        api_key = "test_key"
        default_city = "上海"
        enabled = True
    class MockSettings:
        weather = MockWeatherSettings()
    return MockSettings

@pytest.mark.asyncio
async def test_weather_skill_initialization(mock_settings):
    """测试技能初始化"""
    with patch('skills.weather.skill.settings', mock_settings):
        skill = WeatherSkill()
        assert skill.name == "weather"
        assert skill.default_city == "上海"
        # 测试初始化方法
        await skill.initialize()
        assert skill._initialized == True

@pytest.mark.asyncio
async def test_extract_city():
    """测试城市名提取逻辑"""
    skill = WeatherSkill.__new__(WeatherSkill)  # 不调用__init__，避免配置依赖
    # 简单测试关键词匹配
    assert skill._extract_city("北京天气怎么样？") == "北京"
    assert skill._extract_city("查询纽约的天气") == "纽约"
    assert skill._extract_city("今天天气真好") is None  # 无城市名

@pytest.mark.asyncio
async def test_execute_with_mock_api(mock_settings):
    """模拟API调用，测试完整的execute流程"""
    with patch('skills.weather.skill.settings', mock_settings), \
         patch('skills.weather.skill.aiohttp.ClientSession') as mock_session:
        # 构造模拟的API响应
        mock_response_data = {
            'current': {'temp_c': 22, 'condition': {'text': '晴朗'}, 'humidity': 65}
        }
        mock_response = AsyncMock()
        mock_response.json = AsyncMock(return_value=mock_response_data)
        mock_response.raise_for_status = MagicMock()

        mock_session_instance = AsyncMock()
        mock_session_instance.__aenter__.return_value.get.return_value.__aenter__.return_value = mock_response
        mock_session.return_value = mock_session_instance

        skill = WeatherSkill()
        skill.api_key = "test_key"
        skill.default_city = "上海"

        result = await skill.execute("上海天气")
        # 验证返回的字符串包含预期信息
        assert "上海" in result
        assert "22" in result
        assert "晴朗" in result
        assert "65" in result

运行测试： poetry run pytest tests/ -v 。良好的测试覆盖率能让你在重构代码时充满信心。

5.2 使用预提交钩子（Pre-commit）保证代码质量

在项目根目录创建 .pre-commit-config.yaml 。

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace  # 删除行尾空格
      - id: end-of-file-fixer    # 确保文件以换行符结尾
      - id: check-yaml           # 检查YAML语法
      - id: check-added-large-files # 检查大文件

  - repo: https://github.com/psf/black
    rev: 23.12.1
    hooks:
      - id: black
        language_version: python3

  - repo: https://github.com/pycqa/isort
    rev: 5.13.2
    hooks:
      - id: isort
        args: ["--profile", "black"]

  - repo: https://github.com/pycqa/flake8
    rev: 7.0.0
    hooks:
      - id: flake8
        args: ["--max-line-length=120", "--extend-ignore=E203,W503"]

安装钩子： poetry run pre-commit install 。此后每次 git commit ，这些工具会自动格式化你的代码并检查基本问题。

5.3 容器化部署（Docker）

创建 Dockerfile 和 docker-compose.yml ，实现一键部署。

# Dockerfile
FROM python:3.11-slim as builder

WORKDIR /app
RUN pip install poetry==1.7.0
COPY pyproject.toml poetry.lock ./
RUN poetry export --without-hashes --without dev -f requirements.txt -o requirements.txt

FROM python:3.11-slim

WORKDIR /app
COPY --from=builder /app/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
# 创建非root用户运行
RUN useradd -m -u 1000 agent && chown -R agent:agent /app
USER agent

# 假设通过环境变量注入配置，主入口为main.py
CMD ["python", "main.py"]

# docker-compose.yml
version: '3.8'
services:
  openclaw-agent:
    build: .
    container_name: my-openclaw-agent
    restart: unless-stopped
    volumes:
      - ./storage:/app/storage  # 持久化数据
      - ./config/config.yaml:/app/config/config.yaml:ro  # 挂载配置文件
    env_file:
      - .env  # 包含敏感环境变量
    # 如果需要连接本地Ollama
    # extra_hosts:
    #   - "host.docker.internal:host-gateway"
    environment:
      - OPENCLAW_BASE_URL=http://host.docker.internal:11434
    ports:
      - "8000:8000"  # 如果主程序启动了HTTP服务

部署时，只需 docker-compose up -d 。所有依赖、环境、配置都被封装，与宿主机隔离。

6. 常见问题与避坑指南

在实际开发和维护中，你肯定会遇到各种问题。这里记录一些典型场景和解决方案。

6.1 技能加载失败或冲突

• 问题 ：启动时日志报错 ModuleNotFoundError 或技能功能异常。
• 排查 ：
  1. 检查技能目录是否有 __init__.py 文件。
  2. 检查 skill.py 中类的命名，确保它继承自 BaseSkill 且不是抽象类。
  3. 在 main.py 的 discover_skills 函数中添加更详细的日志，打印导入路径和发现的类。
• 技巧 ：可以在 BaseSkill 中增加一个类变量 enabled = True ，在发现技能后检查此变量，方便动态禁用某些技能。

6.2 配置不生效或优先级混乱

• 问题 ：修改了 config.yaml 或 .env 文件，但程序运行时似乎还是旧值。
• 排查 ：
  1. 确认 .env 文件在项目根目录，且变量名正确（如 WEATHER_API_KEY ）。
  2. 在 settings.py 的 from_yaml 方法中打印合并后的配置字典，确认YAML文件被正确读取和解析。
  3. 记住配置优先级： 环境变量 > YAML配置文件 > Pydantic模型默认值 。
• 技巧 ：为关键配置（如API Key）在初始化时添加验证，如果为空则立即抛出清晰的错误信息，而不是在运行时才因API调用失败而报错。

6.3 异步（Async）操作导致的卡顿或错误

• 问题 ：技能执行缓慢，或者出现 RuntimeWarning: coroutine was never awaited 。
• 排查 ：
  1. 确保所有技能中涉及I/O的操作（网络请求、文件读写、数据库查询）都使用异步库（如 aiohttp , aiofiles , asyncpg ）并正确使用 await 。
  2. 在 BaseSkill 的 execute 方法中，用 try...except 包裹核心逻辑，并记录详细的错误日志，避免一个技能的崩溃导致整个Agent挂掉。
  3. 对于耗时的CPU密集型任务，考虑使用 asyncio.to_thread 将其放到线程池中执行，避免阻塞事件循环。
• 技巧 ：在技能初始化 ( _setup ) 和执 ( execute ) 方法中，使用 logging 记录耗时，便于性能分析和优化。

6.4 技能间的数据共享与通信

• 问题 ：技能A需要用到技能B产生的数据。
• 方案 ： 避免直接函数调用 。推荐两种模式：
  1. 通过上下文（Context） ：OpenClaw的 state 或自定义的 context 字典可以作为技能间传递数据的通道。技能A将结果以特定键（如 weather_data ）存入 context ，技能B在 execute 方法中检查 context 是否存在该键。需注意数据序列化和生命周期管理。
  2. 通过共享存储 ：使用一个外部的、中立的存储服务，如Redis或数据库。技能A将数据写入，技能B读取。这解耦更彻底，但引入外部依赖。可以在 core 目录下创建一个 storage_client.py 来统一管理这类连接。

6.5 版本升级与依赖管理

• 问题 ：OpenClaw框架升级后，原有代码不兼容。
• 策略 ：
  1. 在 pyproject.toml 中，对关键依赖（如 open-claw ）使用宽容但明确的版本约束，例如 ^0.2.0 表示允许 0.2.x 但不允许 0.3.0 。定期更新并测试。
  2. 将框架相关的调用封装在 core/extensions.py 或技能基类中。如果框架API变更，你只需要修改这些封装点，而不是每个技能。
  3. 维护一个 CHANGELOG.md ，记录依赖升级和对应的代码修改。

遵循这个从零搭建的结构和规范，你的OpenClaw技能项目将不再是散落的脚本集合，而是一个真正可维护、可扩展、可协作的工程。它开始可能需要多一点前期投入，但当你需要添加第5个、第10个技能，或者与新队友一起开发时，你会庆幸当初做了这个决定。