Plugin OpenClaw: Tugas sederhana (simple-tasks)

Dokumen ini menjelaskan bagaimana proses plugin berjalan dari sisi gateway OpenClaw sampai eksekusi kode Anda.

Ringkasan

Plugin ini mendaftarkan beberapa tool (fungsi yang bisa dipanggil model/agen) untuk mengelola daftar tugas in-memory di dalam proses Node.js yang menjalankan gateway. Tidak ada basis data atau layanan eksternal: semua data hilang saat proses gateway dihentikan.

• ID plugin: simple-tasks (harus cocok dengan plugins.allow jika Anda memakai allowlist).
• Entry: ./index.ts (diarahkan dari blok openclaw.extensions di package.json).
• State: satu instance createTaskStore dibuat saat modul extension dimuat; dipakai bersama oleh semua pemanggilan tool dalam proses yang sama.

Alur tingkat tinggi

sequenceDiagram
  participant Admin
  participant Gateway as Gateway OpenClaw
  participant Ext as index.ts
  participant Store as store.ts
  participant Agent as Agen / model

  Admin->>Gateway: plugins install + restart
  Gateway->>Ext: muat extension, import default definePluginEntry
  Ext->>Ext: hitung maxTasks, buat store
  Ext->>Gateway: register(api) mendaftarkan tool
  Agent->>Gateway: panggil tool mis. simple_task_add
  Gateway->>Ext: execute(toolCallId, params, ...)
  Ext->>Store: add / list / complete / ...
  Store-->>Ext: hasil
  Ext-->>Gateway: jsonResult(payload)
  Gateway-->>Agent: AgentToolResult (content + details)

Tahap 1: Instalasi dan pemuatan gateway

1. Paket npm berisi package.json dengan blok openclaw dan extensions menunjuk ke ./index.ts.
2. Perintah seperti openclaw plugins install <path> memasang plugin ke konfigurasi gateway.
3. Saat gateway start, runtime memuat file extension tersebut.
4. Jika konfigurasi memakai allowlist plugin, id simple-tasks harus diizinkan; jika tidak, extension tidak aktif.

Tahap 2: Eksekusi sekali saat modul dimuat

Saat index.ts pertama kali dievaluasi:

1. Batas tugas dihitung dari variabel lingkungan OPENCLAW_SIMPLE_TASKS_MAX (angka positif, dipotong maksimal 10.000). Jika tidak diset, dipakai 200.
2. createTaskStore(maxTasks) membuat struktur internal berupa array tugas di closure (tidak diekspor ke dunia luar).
3. Schema Typebox (simpleTaskAddParams, dll.) didefinisikan untuk dokumentasi argumen tool dan validasi di sisi runtime OpenClaw.

Langkah ini terjadi sekali per proses; restart gateway mengulang dari awal (store kosong lagi).

Tahap 3: definePluginEntry dan register(api)

Ekspor default adalah hasil definePluginEntry({ id, name, description, register }). OpenClaw memanggil register(api) saat plugin diaktifkan.

Di dalam register:

• api.registerTool({ name, label, description, parameters, execute }) menambahkan tool ke registry gateway.
• Tool simple_task_clear juga menerima argumen kedua { optional: true } agar diperlakukan sebagai tool opsional (misalnya tidak selalu ditawarkan ke model).

Setelah registrasi selesai, nama tool seperti simple_task_add dikenal oleh agen yang terhubung ke gateway ini.

Tahap 4: Satu kali pemanggilan tool (request → response)

Ketika agen memutuskan memanggil sebuah tool:

1. Gateway memetakan nama tool ke fungsi execute yang Anda daftarkan.
2. Argumen JSON dari pemanggilan divalidasi terhadap parameters (Typebox).
3. execute dijalankan dengan params yang sudah sesuai skema (di kode ditanggapi dengan Static<typeof ...>).
4. Hasil dikembalikan sebagai jsonResult(payload) dari openclaw/plugin-sdk/core, yang menghasilkan AgentToolResult: blok teks untuk model plus details berisi payload yang sama (berguna untuk log/UI).

Alur ini sinkron dengan satu pemanggilan tool; beberapa chat atau sesi di gateway yang sama berbagi store yang sama jika mereka berada dalam proses gateway yang sama.

Isi tiap tool (ringkas)

Model data di src/store.ts

• Setiap tugas: id unik, title, notes, status (pending | done), createdAt (ISO string).
• Tugas baru dimasukkan di depan daftar (unshift).
• Tidak ada persistensi: hanya memori proses.

Metadata tambahan

• openclaw.plugin.json: id, nama, deskripsi, dan skema konfigurasi untuk UI/docs (mis. maxTasks); nilai runtime batas tugas saat ini mengikuti env di index.ts, bukan otomatis dari file ini, kecuali Anda nanti mengaitkannya di kode.

Pengembangan lokal

npm install
npx tsc --noEmit

Instal ke gateway (contoh):

openclaw plugins install /path/ke/openclaw-plugin-rag-lab

Lalu pastikan simple-tasks di allowlist (jika dipakai) dan restart gateway.

Referensi dokumentasi OpenClaw

• Plugin SDK / setup
• Building extensions