全网首发】OpenClaw 二次开发全教程：从源码解析到自定义插件 / 指令 / 模型适配（2026 实战版）

​

🔥 从 “会用” 到 “会改”｜源码核心解读｜自定义插件开发｜指令扩展｜模型适配｜实战案例

0 前言：为什么要做 OpenClaw 二次开发？

前两篇我们讲了 OpenClaw 的极简搭建和底层原理，但真正让 OpenClaw 适配你的业务场景，必须掌握二次开发：

• 内置功能满足不了个性化需求（比如对接企业内部系统、自定义命令）
• 想适配国产大模型（如通义千问、文心一言）
• 想优化性能、删减无用功能、定制 UI
• 想开发专属插件，把 OpenClaw 变成 “私人 AI 助手”

本文全程实战驱动，从源码环境搭建到最终打包发布，一步不落，新手也能跟着做。

---

1 开发环境准备（必看）

1.1 核心依赖

bash

运行

# 基础环境（先确认版本）
node -v  # ≥22.0.0
pnpm -v  # ≥9.0.0
git -v   # ≥2.40.0
# 安装pnpm（如果没装）
npm install -g pnpm

1.2 拉取源码（国内镜像优先）

bash

运行

# 官方仓库（海外）
git clone https://github.com/OpenClaw/OpenClaw.git
# 国内Gitee镜像（推荐）
git clone https://gitee.com/OpenClaw-CN/openclaw-cn.git

cd openclaw-cn
# 安装所有依赖（关键：不要用npm，必须用pnpm）
pnpm install

1.3 启动开发模式

bash

运行

# 启动前端UI开发服务（热更新）
pnpm dev:ui
# 新开终端，启动网关开发服务
pnpm dev:gateway
# 访问开发环境：http://localhost:5173

✅ 验证环境：能打开 UI、Gateway 无报错，说明环境搭建成功。

---

2 OpenClaw 源码核心结构解析

先看懂源码目录，才知道改哪里：

plaintext

openclaw-cn/
├── packages/          # 核心包（重点！）
│   ├── ui/            # 前端UI（Vue3+TS）
│   ├── gateway/       # 网关层（HTTP服务、鉴权）
│   ├── core/          # 核心调度层（AI意图解析、任务编排）
│   ├── runtime/       # 执行层（命令/脚本调用）
│   └── cli/           # 命令行工具
├── scripts/           # 构建/部署脚本
├── tsconfig.json      # TS配置
└── package.json       # 项目依赖

关键目录说明：

表格

目录	作用	开发重点
packages/ui	前端界面	改样式、加按钮、定制页面
packages/gateway	网关服务	加接口、改鉴权、适配端口
packages/core	核心逻辑	改 AI 调度、加自定义指令
packages/runtime	执行层	加自定义命令、扩展权限

---

3 实战 1：开发第一个自定义插件（最常用）

3.1 插件开发规范

OpenClaw 插件采用模块化设计，核心是实现Plugin接口，包含：

• name：插件名称（唯一）
• description：描述
• actions：插件提供的动作（比如 “查询天气”）
• init：初始化方法

3.2 编写 “天气查询” 插件（完整代码）

步骤 1：新建插件文件

在packages/core/src/plugins/下新建weather.plugin.ts：

typescript

运行

import { Plugin, Action } from '../types/plugin';
import axios from 'axios';

// 定义插件
const WeatherPlugin: Plugin = {
  name: 'weather-plugin',
  description: '查询指定城市的天气',
  // 插件动作（核心）
  actions: [
    {
      name: 'get-weather',
      description: '查询城市天气',
      // 参数定义（AI会识别这些参数）
      parameters: [
        {
          name: 'city',
          type: 'string',
          required: true,
          description: '城市名称，如北京、上海'
        }
      ],
      // 执行逻辑
      handler: async (params) => {
        const { city } = params;
        try {
          // 调用免费天气API（替换成自己的）
          const res = await axios.get(
            `https://api.vvhan.com/api/weather?city=${encodeURIComponent(city)}`
          );
          return {
            success: true,
            data: res.data,
            message: `查询到${city}的天气：${res.data.info}`
          };
        } catch (e) {
          return {
            success: false,
            message: `查询失败：${(e as Error).message}`
          };
        }
      }
    }
  ],
  // 初始化方法（可选）
  init: () => {
    console.log('天气插件已初始化');
  }
};

// 导出插件
export default WeatherPlugin;

步骤 2：注册插件

修改packages/core/src/plugins/index.ts，导入并注册插件：

typescript

运行

import { PluginManager } from '../manager/plugin';
// 导入自定义插件
import WeatherPlugin from './weather.plugin';

// 注册所有插件
const pluginManager = new PluginManager();
pluginManager.register(WeatherPlugin); // 新增这行

export default pluginManager;

步骤 3：测试插件

1. 重启开发服务：pnpm dev:gateway
2. 在 UI 输入：查询北京的天气
3. 看返回结果：能正确显示天气，说明插件生效！

---

4 实战 2：扩展自定义系统指令

如果想让 OpenClaw 支持自定义系统命令（比如openclaw my-command），按这个步骤来：

4.1 编写指令逻辑

在packages/cli/src/commands/下新建my-command.ts：

typescript

运行

import { Command } from 'commander';
import { logger } from '../../utils/logger';

// 定义自定义指令
export const myCommand = new Command('my-command')
  .description('我的自定义指令：打印指定信息')
  .argument('<message>', '要打印的信息')
  .option('-r, --repeat <times>', '重复次数', '1')
  .action((message, options) => {
    const repeat = parseInt(options.repeat);
    for (let i = 0; i < repeat; i++) {
      logger.info(`[自定义指令] ${message}`);
    }
    logger.success('自定义指令执行完成！');
  });

4.2 注册指令

修改packages/cli/src/index.ts：

typescript

运行

import { program } from 'commander';
import { myCommand } from './commands/my-command'; // 导入

// 注册内置指令
// ...（保留原有代码）
// 注册自定义指令
program.addCommand(myCommand); // 新增

program.parse(process.argv);

4.3 测试指令

bash

运行

# 编译指令
pnpm build:cli
# 测试自定义指令
node dist/cli/index.js my-command "Hello OpenClaw" -r 3
# 输出：
# [自定义指令] Hello OpenClaw
# [自定义指令] Hello OpenClaw
# [自定义指令] Hello OpenClaw
# ✔ 自定义指令执行完成！

---

5 实战 3：适配国产大模型（通义千问）

OpenClaw 默认适配 OpenAI 格式，我们修改核心代码，让它支持通义千问：

5.1 新增模型适配器

在packages/core/src/model/adapters/下新建tongyi.adapter.ts：

typescript

运行

import { ModelAdapter, ModelRequest, ModelResponse } from '../types';
import axios from 'axios';

// 通义千问适配器
export class TongyiAdapter implements ModelAdapter {
  private apiKey: string;

  constructor(config: { apiKey: string }) {
    this.apiKey = config.apiKey;
  }

  // 实现请求方法
  async request(req: ModelRequest): Promise<ModelResponse> {
    try {
      const res = await axios.post(
        'https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions',
        {
          model: 'qwen-turbo',
          messages: req.messages,
          temperature: req.temperature || 0.7
        },
        {
          headers: {
            'Authorization': `Bearer ${this.apiKey}`,
            'Content-Type': 'application/json'
          }
        }
      );

      return {
        content: res.data.choices[0].message.content,
        finishReason: res.data.choices[0].finish_reason,
        raw: res.data
      };
    } catch (e) {
      throw new Error(`通义千问请求失败：${(e as Error).message}`);
    }
  }
}

5.2 注册适配器

修改packages/core/src/model/modelManager.ts：

typescript

运行

import { TongyiAdapter } from './adapters/tongyi.adapter';
// ...（保留原有代码）

// 新增通义千问模型支持
export function createModelAdapter(type: string, config: any) {
  switch (type) {
    case 'openai':
      return new OpenAIAdapter(config);
    case 'tongyi': // 新增
      return new TongyiAdapter(config);
    default:
      throw new Error(`不支持的模型类型：${type}`);
  }
}

5.3 配置使用

在 OpenClaw 配置文件（~/.openclaw/config.yaml）中添加：

yaml

model:
  type: tongyi
  config:
    apiKey: 你的通义千问API Key

重启 Gateway，就能用通义千问作为 OpenClaw 的 AI 大脑了！

---

6 打包发布自定义版本

开发完成后，打包成可执行文件 / 安装包：

bash

运行

# 全量构建
pnpm build
# 打包CLI（生成可执行文件）
pnpm build:cli
# 打包成npm包（可全局安装）
cd packages/cli
npm pack
# 安装自定义版本
npm install -g ./openclaw-cli-1.0.0.tgz

✅ 验证：执行openclaw --version，能看到自定义版本，说明打包成功。

---

7 二次开发避坑指南

🔴 坑 1：pnpm install 失败

• 原因：网络问题 / 依赖版本冲突

• 解决：

  bash

  运行

  # 配置国内镜像
  pnpm config set registry https://registry.npmmirror.com
  # 删除lock文件重新装
  rm -rf pnpm-lock.yaml node_modules
  pnpm install
  

🔴 坑 2：开发模式热更新不生效

• 解决：检查vite.config.ts的server.watch配置，确保监听正确目录。

🔴 坑 3：插件注册后不生效

• 检查：插件名称是否唯一、是否导出正确、是否在index.ts中注册。

🔴 坑 4：模型适配后返回格式错误

• 核心：必须严格遵循ModelResponse接口格式，否则 Core 无法解析。

---

8 总结

OpenClaw 二次开发的核心是：

1. 看懂分层架构：知道 UI/Gateway/Core/Runtime 各自的作用，改对应目录
2. 遵循插件规范：开发插件优先，尽量不修改核心代码（便于升级）
3. 适配模型抓准格式：所有模型最终要转换成 OpenClaw 能识别的格式

掌握这些，你就能把 OpenClaw 从 “通用工具” 改成 “专属 AI 助手”，真正发挥它的价值。

---

👉 系列教程回顾

1. 《OpenClaw 全网最简单搭建步骤 + 最全避错坑位指南》
2. 《【深度解剖】OpenClaw 底层原理全解析》
3. 《OpenClaw 二次开发全教程（本文）》

进阶方向（下篇预告）

《OpenClaw 性能优化实战：内存占用降低 50%+ 响应速度提升 3 倍》

---

总结

1. OpenClaw 二次开发核心是基于其分层架构，在对应目录（ui/gateway/core/runtime）做定制化修改，优先通过插件扩展功能而非直接改核心源码。
2. 自定义插件需实现Plugin接口，包含名称、描述、动作（参数 + 执行逻辑），并在插件管理器中注册。
3. 适配国产大模型的关键是实现统一的ModelAdapter接口，将不同模型的请求 / 响应格式标准化，让 Core 层能统一解析。

​