Smart Report Plugin for OpenClaw

Plugin OpenClaw untuk integrasi ke ekosistem Smart Report melalui:

• CLI commands untuk autentikasi dan health check
• chat/native commands untuk akses cepat dari runtime OpenClaw
• resources untuk expose data Smart Report ke agent/runtime
• tools untuk reasoning agent berbasis data Smart Report
• plugin skill agar output ke user tetap rapi dan tidak menampilkan JSON mentah

README ini sudah disesuaikan dengan alur code terbaru di source saat ini, termasuk perilaku install.sh terbaru.

Ringkasan alur terbaru

Plugin melakukan registrasi pada saat register(api) / activate(api) dipanggil, lalu:

1. mendaftarkan CLI commands
2. mendaftarkan chat commands bila runtime mendukung registerCommand
3. mendaftarkan resources
4. mendaftarkan tools

Struktur registrasi utama ada di src/index.ts:

• registerCommands(api)
• registerResources(api)
• registerTools(api)

Struktur plugin

smart-report-plugin/
├── package.json
├── openclaw.plugin.json
├── openclaw.cjs
├── index.js
├── install.sh
├── src/
│   ├── client.ts
│   ├── commands.ts
│   ├── resources.ts
│   ├── tools.ts
│   └── index.ts
├── dist/
│   ├── client.js
│   ├── commands.js
│   ├── resources.js
│   ├── tools.js
│   ├── index.js
│   └── openclaw.cjs
├── skills/
│   └── smart-report/
│       └── SKILL.md
├── docs/
│   └── USER_GUIDE.md
└── scripts/
    └── test-loader.js

Requirement

• OpenClaw terpasang dan bisa menjalankan openclaw
• Node.js dan npm tersedia
• Token API Smart Report valid
• Runtime/plugin manager OpenClaw mengizinkan install plugin dari source repository

Instalasi

Opsi 1 — dari source repo lokal

Jika repo ini sudah ada di mesin:

bash install.sh

Opsi 2 — install via OpenClaw plugin manager dari path repo

openclaw plugins install /path/ke/smart-report-plugin

Opsi 3 — installer via raw GitHub

bash <(curl -fsSL https://raw.githubusercontent.com/sodikinnaa/smart-report-plugin/master/install.sh)

Alur installer terbaru

install.sh sekarang mengikuti alur berikut:

1. clone repository source
2. menjalankan npm ci atau fallback npm install
3. build plugin dengan npm run build
4. validasi file penting plugin
5. install plugin lewat official OpenClaw plugin manager:

openclaw plugins install <path-repo>

6. tidak fallback ke copy manual ke ~/.openclaw/extensions
7. bila gagal karena plugin lama sudah ada, installer akan:
   • backup plugin lama
   • retry install resmi satu kali
8. gateway tidak di-restart otomatis secara default

Tujuan alur ini adalah menjaga provenance/trust plugin tetap bersih dan menghindari state plugin local yang tidak ter-track.

Opsi installer

Contoh penggunaan:

bash install.sh
bash install.sh --branch main
bash install.sh --repo https://github.com/sodikinnaa/smart-report-plugin.git
bash install.sh --token <GITHUB_TOKEN>
bash install.sh --skip-build
bash install.sh --restart

Opsi yang tersedia:

• --repo <url> → URL git source plugin
• --branch <name> → branch/tag yang akan di-clone
• --target <path> → reserved untuk diagnostik; bukan jalur manual install utama
• --token <token> → GitHub token untuk private repo, atau gunakan env GITHUB_TOKEN
• --skip-build → lewati npm install dan npm run build
• --restart → restart openclaw gateway setelah install
• --no-restart → alias legacy; restart tetap di-skip secara default

Batasan penting install.sh

Perilaku script saat ini:

• wajib ada command git, node, npm, dan openclaw
• installer ini hanya mendukung install via OpenClaw plugin manager
• script tidak publish ke npm dan tidak install dari package npm
• jika openclaw tidak ditemukan, proses akan dihentikan
• jika install via openclaw plugins install gagal karena alasan selain plugin lama sudah ada, script akan stop dan meminta environment OpenClaw diperbaiki dulu

Artinya, install.sh memang sengaja dibuat konservatif supaya tidak menghasilkan plugin local yang untracked atau bermasalah secara provenance.

Build & test

npm test
npm run build

Script yang tersedia di package.json:

• npm run build
• npm test
• npm run publish

Konfigurasi plugin

Manifest openclaw.plugin.json mendeklarasikan config berikut:

• apiToken
• companyName
• companyDomain

Contoh shape config:

{
  "apiToken": "TOKEN_SMART_REPORT",
  "companyName": "Nama Perusahaan",
  "companyDomain": "member.smartreport.my.id"
}

Cara autentikasi

Setelah plugin ter-install, jalankan:

openclaw smart-auth <TOKEN_ANDA>

Perilaku smart-auth di code terbaru:

• token disimpan ke api.pluginConfig saat runtime berjalan
• plugin mencoba verifikasi token dengan memanggil company/info
• jika sukses, plugin menyimpan:
  • apiToken
  • companyName
  • companyDomain
• jika api.saveConfig() tersedia, plugin memakai mekanisme save resmi runtime
• jika tidak tersedia, plugin fallback ke update file config OpenClaw yang ditemukan

Candidate config path yang dicoba oleh plugin:

• ~/.openclaw/openclaw.json
• ~/.openclaw/config.json
• /root/.openclaw/openclaw.json
• /root/.openclaw/config.json
• /etc/openclaw/openclaw.json
• /etc/openclaw/config.json

Cara cek konektivitas

Untuk health check end-to-end, jalankan:

openclaw smart-status

Status check saat ini menguji method berikut:

• company/info
• smartreport/dashboard
• employees/list
• reports/list
• divisions/list
• guides/list
• analyze_performance

Jika ada check gagal, command akan exit dengan status non-zero.

CLI commands yang tersedia

Plugin saat ini mendaftarkan 2 CLI command:

• openclaw smart-auth <token>
• openclaw smart-status

Chat/native commands yang tersedia

Jika runtime OpenClaw mendukung registerCommand, plugin akan mendaftarkan command berikut:

• /smart_status
• /smart_dashboard
• /smart_dashboard_raw
• /smart_employees
• /smart_employees_raw
• /smart_reports
• /smart_reports_raw
• /smart_divisions
• /smart_divisions_raw
• /smart_guides
• /smart_guides_raw
• /smart_guide
• /smart_guide_raw
• /smart_analysis
• /smart_analysis_raw

Catatan penting nama command

Di code terbaru, nama chat command memakai underscore, bukan dash.

Benar:

• /smart_status
• /smart_dashboard

Bukan:

• /smart-status
• /smart-dashboard

Format argumen command

Command chat membaca ctx.args lalu mencoba parsing dengan alur berikut:

1. jika kosong → {}
2. jika valid JSON object → dipakai langsung
3. jika valid JSON tapi bukan object → dibungkus sebagai { "input": ... }
4. jika bukan JSON → dibungkus sebagai { "input": "teks-raw" }

Contoh:

/smart_reports {"per_page":5}
/smart_guide {"id":12}
/smart_dashboard {"mode":"compact"}

Tools yang didaftarkan

Plugin saat ini mendaftarkan tool berikut:

• get_daily_dashboard
• get_guides_list
• get_guide_content
• get_list_reports
• get_reports_summary
• get_report_detail
• get_debt_analysis

Semua tool memanggil backend MCP lalu mengembalikan hasil JSON dalam field text.

Catatan:

• tool memang ditujukan untuk reasoning internal agent
• output ke user sebaiknya dirapikan terlebih dahulu
• skill smart-report sebaiknya dipakai agar agent tidak menampilkan JSON mentah ke user

Resources yang didaftarkan

Plugin mendaftarkan resource berikut:

• smartreport://reports
• smartreport://employees
• smartreport://divisions
• smartreport://guides
• smartreport://dashboard

Semua resource saat ini mengembalikan application/json.

Method MCP yang dipakai plugin

Source src/client.ts saat ini memanggil endpoint:

https://member.smartreport.my.id/api/mcp

Method MCP yang dipakai di berbagai command/resource/tool:

• company/info
• smartreport/dashboard
• employees/list
• reports/list
• divisions/list
• guides/list
• guides/get
• analyze_performance

Token resolution flow

Saat melakukan request, plugin mencari token dengan urutan:

1. api.pluginConfig.apiToken
2. api.config.apiToken
3. api.config.plugins.entries.smart-report-plugin.config.apiToken

Jika token tidak ditemukan, plugin akan melempar error:

API token not found. Jalankan "openclaw smart-auth <token>" terlebih dahulu.

Kompatibilitas runtime OpenClaw terbaru

Pada runtime OpenClaw yang lebih baru, command chat/native harus memakai field:

• handler
• bukan execute

Plugin ini sudah mengikuti pola tersebut dan juga menyetel:

• acceptsArgs: true

Selain itu, proses registrasi chat command dibungkus try/catch agar kegagalan registrasi tidak ikut menjatuhkan startup plugin secara keseluruhan.

Verifikasi setelah install

Langkah verifikasi yang direkomendasikan:

openclaw plugins list --verbose
openclaw smart-auth <TOKEN_SMART_REPORT>
openclaw smart-status

Output akhir install.sh juga memang mengarahkan verifikasi ke alur ini, lalu menyarankan pengujian chat command bila runtime mendukung native command.

Jika runtime mendukung chat/native command, lanjut uji:

/smart_status
/smart_dashboard {"mode":"compact"}
/smart_reports {"per_page":5}

Dokumentasi tambahan

• docs/USER_GUIDE.md
• docs/AGENT_SESSION_MCP_TROUBLESHOOTING.md

Troubleshooting

1. Plugin gagal install

Cek:

openclaw plugins list --verbose
openclaw plugins doctor

Kemungkinan penyebab:

• trust/provenance plugin belum valid
• plugin lama masih tercatat
• policy OpenClaw menolak install source tertentu

2. Auth gagal

Pastikan:

• token valid
• endpoint Smart Report bisa diakses
• backend menerima Bearer token

Ulangi:

openclaw smart-auth <TOKEN_ANDA>

3. Command chat tidak muncul

Kemungkinan:

• runtime tidak menyediakan registerCommand
• channel/runtime tidak mendukung native command plugin
• ada error registrasi command saat startup

4. Tool mengembalikan error

Cek apakah token sudah tersimpan dan method MCP yang dipanggil memang tersedia di backend.

Manifest & metadata saat ini

package.json

• package name: @sodikinnaa/smart-report-plugin
• version: 2100.11.6

openclaw.plugin.json

• plugin id: smart-report-plugin
• name: Smart Report Integration
• version: 2100.11.6
• entrypoint: ./index.js

Catatan desain

• registrasi dipisah per concern: commands, resources, tools, client
• client.ts menangani auth, persistence config, dan call MCP
• commands.ts menangani CLI + chat command
• resources.ts expose dataset Smart Report sebagai resource JSON
• tools.ts expose method penting untuk reasoning agent
• skill plugin disediakan di folder ./skills

Rekomendasi penggunaan

Gunakan:

• CLI command untuk setup awal dan health check
• chat command untuk akses cepat/manual dari runtime
• tools untuk analisis oleh agent
• skill untuk merapikan output akhir ke user

Kalau ingin menjaga UX tetap bagus, jangan tampilkan raw JSON ke end-user kecuali memang untuk debugging.