OpenClaw技能开发入门：为Qwen3-32B编写自定义文件处理器

1. 为什么需要自定义技能？

去年我接手了一个数据分析项目，每天需要手动将几十份CSV报告转换成Markdown格式。重复劳动不仅耗时，还容易出错。当我发现OpenClaw支持自定义技能开发时，立刻意识到这是解决问题的绝佳机会——通过编写一个文件处理器技能，让AI自动完成格式转换。

与直接调用大模型API不同，OpenClaw技能提供了更完整的工程化封装。它允许我们将文件操作、模型调用、错误处理等逻辑打包成可复用的模块，通过自然语言指令触发。这种"工具+模型"的组合，比单纯依赖模型生成更可靠。

2. 开发环境准备

2.1 基础工具链配置

我的开发环境是macOS + VS Code，关键依赖包括：

# 确认Node.js版本（要求18+）
node -v
# v20.12.2

# 全局安装OpenClaw CLI
npm install -g openclaw@latest

# 安装技能开发工具包
npm install -g @openclaw/cli-devkit

建议在项目目录初始化npm环境：

mkdir csv-to-markdown-skill && cd csv-to-markdown-skill
npm init -y

2.2 连接Qwen3-32B模型

在~/.openclaw/openclaw.json中添加模型配置（如果使用星图平台的私有部署镜像）：

{
  "models": {
    "providers": {
      "qwen-local": {
        "baseUrl": "http://localhost:8080/v1",
        "apiKey": "your-api-key",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3-32b",
            "name": "Qwen3-32B Local",
            "contextWindow": 32768
          }
        ]
      }
    }
  }
}

验证模型连接：

openclaw models list
# 应看到qwen3-32b在可用模型列表中

3. 创建技能脚手架

OpenClaw提供了标准的技能模板生成器：

clawdev skill init

交互式命令行会提示输入以下信息：

• 技能名称：csv-to-markdown
• 描述：Convert CSV files to markdown tables
• 触发词：convert csv（用户说这个词时会触发该技能）
• 是否需要文件操作权限：yes

生成的项目结构如下：

csv-to-markdown/
├── package.json
├── src/
│   ├── index.ts          # 技能主逻辑
│   ├── types.ts          # 类型定义
│   └── utils.ts          # 工具函数
├── test/
│   └── index.spec.ts     # 测试用例
└── openclaw.skill.json   # 技能元数据

重点关注openclaw.skill.json中的权限声明：

{
  "permissions": {
    "files": {
      "read": [".csv"],
      "write": [".md"]
    }
  }
}

这确保技能只能访问指定类型的文件，遵循最小权限原则。

4. 核心逻辑开发

4.1 文件处理器设计

在src/index.ts中实现核心转换逻辑。我们先实现一个纯函数版本的CSV转换器：

interface ConversionParams {
  inputPath: string;
  outputPath?: string;
  delimiter?: string;
}

export async function convertCSVToMarkdown(
  params: ConversionParams
): Promise<string> {
  const { inputPath, delimiter = ',' } = params;
  
  // 读取CSV文件
  const csvContent = await fs.promises.readFile(inputPath, 'utf-8');
  const lines = csvContent.split('\n').filter(line => line.trim());

  // 解析表头
  const headers = lines[0].split(delimiter);
  const headerRow = `| ${headers.join(' | ')} |`;
  const separatorRow = `| ${headers.map(() => '---').join(' | ')} |`;

  // 构建表格内容
  const bodyRows = lines.slice(1).map(line => {
    return `| ${line.split(delimiter).join(' | ')} |`;
  });

  // 组合成完整Markdown
  return [headerRow, separatorRow, ...bodyRows].join('\n');
}

4.2 集成模型调用

简单的表格转换可以直接完成，但复杂数据可能需要模型辅助。我们添加模型增强逻辑：

async function enhanceWithModel(markdown: string): Promise<string> {
  const response = await openclaw.models.complete({
    model: 'qwen3-32b',
    prompt: `请优化以下Markdown表格的格式，确保对齐且易读：\n\n${markdown}`,
    temperature: 0.3,
    max_tokens: 1024
  });

  return response.choices[0].message.content;
}

关键参数说明：

• temperature=0.3：降低随机性，确保格式稳定
• max_tokens=1024：控制响应长度，避免过度消耗token

4.3 完整技能封装

将上述功能封装成OpenClaw技能标准接口：

export default defineSkill({
  async execute(task: SkillTask) {
    const { inputPath } = task.params;
    
    try {
      // 基础转换
      const rawMarkdown = await convertCSVToMarkdown({
        inputPath,
        outputPath: task.workspacePath('output.md')
      });

      // 模型增强
      const enhanced = await enhanceWithModel(rawMarkdown);
      
      // 保存结果
      await fs.promises.writeFile(
        task.workspacePath('output.md'), 
        enhanced
      );

      return { success: true, outputPath: 'output.md' };
    } catch (error) {
      return { 
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error'
      };
    }
  }
});

5. 本地测试与调试

5.1 单元测试

在test/index.spec.ts中添加测试用例：

describe('CSV to Markdown', () => {
  it('should convert basic CSV', async () => {
    const testCSV = `name,age\nAlice,30\nBob,25`;
    const expected = `| name | age |\n| --- | --- |\n| Alice | 30 |\n| Bob | 25 |`;
    
    const tempPath = await createTempFile(testCSV);
    const result = await convertCSVToMarkdown({
      inputPath: tempPath
    });

    expect(result.trim()).toEqual(expected);
  });
});

5.2 集成测试

使用OpenClaw CLI进行端到端测试：

# 在项目目录下
clawdev skill test --params '{"inputPath":"test.csv"}'

测试文件test.csv内容：

product,price,stock
Laptop,1200,15
Mouse,25,200

检查生成的output.md应包含格式正确的表格。

5.3 调试技巧

遇到问题时，可以通过以下方式排查：

1. 查看OpenClaw日志：

tail -f ~/.openclaw/logs/gateway.log

2. 在代码中添加调试输出：

task.logger.debug('Current markdown:', { content: rawMarkdown });

3. 使用模型调试模式：

await openclaw.models.complete({
  model: 'qwen3-32b',
  prompt: '...',
  debug: true  // 会返回详细的推理过程
});

6. 部署与使用

6.1 打包发布

# 构建生产版本
npm run build

# 发布到ClawHub
clawhub publish --access-token YOUR_TOKEN

6.2 用户使用方式

安装技能：

clawhub install csv-to-markdown

通过自然语言触发：

帮我将data/report.csv转换成Markdown表格

或在代码中调用：

const result = await openclaw.skills.execute('csv-to-markdown', {
  inputPath: 'data/report.csv'
});

7. 工程化建议

在实际使用中，我总结了几个优化点：

1. 批量处理：修改技能支持目录遍历，可以一次性处理多个CSV文件
2. 缓存机制：对相同内容的CSV文件，可以跳过模型增强步骤
3. 增量更新：当CSV文件变更时，只重新处理受影响的行
4. 安全校验：添加文件大小限制和内容校验，防止恶意输入

一个典型的生产级改进是添加文件变更监听：

import chokidar from 'chokidar';

watcher = chokidar.watch('data/*.csv').on('change', path => {
  openclaw.skills.execute('csv-to-markdown', { inputPath: path });
});

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。