​

Eklentiler (Uzantılar)

​

38. Hızlı başlangıç (eklentilere yeni misiniz?)

1. Zaten yüklü olanları görün:

openclaw plugins list

2. Resmî bir eklenti kurun (örnek: Voice Call):

openclaw plugins install @openclaw/voice-call

3. Gateway’i yeniden başlatın, ardından plugins.entries.<id>.config altında yapılandırın.

​

40. Mevcut eklentiler (resmi)

• Microsoft Teams, 2026.1.15 itibarıyla yalnızca eklenti olarak sunulmaktadır; Teams kullanıyorsanız @openclaw/msteams’yi kurun.
• Memory (Core) — paketli bellek arama eklentisi (plugins.slots.memory ile varsayılan olarak etkindir)
• Memory (LanceDB) — paketli uzun süreli bellek eklentisi (otomatik geri çağırma/yakalama; plugins.slots.memory = "memory-lancedb" ayarlayın)
• Voice Call — @openclaw/voice-call
• Zalo Personal — @openclaw/zalouser
• Matrix — @openclaw/matrix
• Nostr — @openclaw/nostr
• Zalo — @openclaw/zalo
• Microsoft Teams — @openclaw/msteams
• Google Antigravity OAuth (sağlayıcı kimlik doğrulaması) — google-antigravity-auth olarak paketlidir (varsayılan olarak devre dışı)
• Gemini CLI OAuth (sağlayıcı kimlik doğrulaması) — google-gemini-cli-auth olarak paketlidir (varsayılan olarak devre dışı)
• Qwen OAuth (sağlayıcı kimlik doğrulaması) — qwen-portal-auth olarak paketlidir (varsayılan olarak devre dışı)
• Copilot Proxy (sağlayıcı kimlik doğrulaması) — yerel VS Code Copilot Proxy köprüsü; yerleşik github-copilot cihaz oturum açmadan ayrıdır (paketli, varsayılan olarak devre dışı)

• Gateway RPC yöntemleri
• Gateway HTTP işleyicileri
• Ajan araçları
• CLI komutları
• Arka plan servisleri
• İsteğe bağlı yapılandırma doğrulaması
• Skills (eklenti bildiriminde skills dizinlerini listeleyerek)
• Otomatik yanıt komutları (AI ajanını çağırmadan çalışır)

​

Çalışma zamanı yardımcıları

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

• Çekirdek messages.tts yapılandırmasını kullanır (OpenAI veya ElevenLabs).
• PCM ses arabelleği + örnekleme hızı döndürür. Eklentiler, sağlayıcılar için yeniden örnekleme/kodlama yapmalıdır.
• Edge TTS telefon için desteklenmez.

​

Keşif ve öncelik

1. Yapılandırma yolları

• plugins.load.paths (dosya veya dizin)

2. Çalışma alanı uzantıları

• <workspace>/.openclaw/extensions/*.ts
• <workspace>/.openclaw/extensions/*/index.ts

3. Genel uzantılar

• ~/.openclaw/extensions/*.ts
• ~/.openclaw/extensions/*/index.ts

4. Paketli uzantılar (OpenClaw ile birlikte gönderilir, varsayılan olarak devre dışıdır)

• <openclaw>/extensions/*

​

Paket paketleri

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"]
  }
}

​

Kanal katalog meta verileri

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "extensions/nextcloud-talk",
      "defaultChoice": "npm"
    }
  }
}

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

Eklenti kimlikleri (ID’ler)

• Paket paketleri: package.json name
• Tekil dosya: dosya taban adı (~/.../voice-call.ts → voice-call)

​

Yapılandırma

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-extension"] },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}

• enabled: ana anahtar (varsayılan: true)
• allow: izin listesi (isteğe bağlı)
• deny: engelleme listesi (isteğe bağlı; engelleme kazanır)
• load.paths: ek eklenti dosyaları/dizinleri
• entries.<id>: eklenti başına anahtarlar + yapılandırma

• entries, allow, deny veya slots içindeki bilinmeyen eklenti id’leri hatadır.
• Bilinmeyen channels.<id> anahtarları, eklenti bildirimi kanal id’sini beyan etmedikçe hatadır.
• Eklenti yapılandırması, openclaw.plugin.json içine gömülü JSON Schema kullanılarak doğrulanır (configSchema).
• Bir eklenti devre dışıysa, yapılandırması korunur ve bir uyarı üretilir.

​

Eklenti yuvaları (özel kategoriler)

{
  plugins: {
    slots: {
      memory: "memory-core", // or "none" to disable memory plugins
    },
  },
}

​

Kontrol UI’si (şema + etiketler)

• plugins.entries.<id> / .enabled / .config için eklenti başına etiketler ekler
• İsteğe bağlı eklenti tarafından sağlanan yapılandırma alanı ipuçlarını şu altında birleştirir: plugins.entries.<id>.config.<field>

{
  "id": "my-plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": { "type": "string" },
      "region": { "type": "string" }
    }
  },
  "uiHints": {
    "apiKey": { "label": "API Key", "sensitive": true },
    "region": { "label": "Region", "placeholder": "us-east-1" }
  }
}

​

CLI

openclaw plugins list
openclaw plugins info <id>
openclaw plugins install <path>                 # copy a local file/dir into ~/.openclaw/extensions/<id>
openclaw plugins install ./extensions/voice-call # relative path ok
openclaw plugins install ./plugin.tgz           # install from a local tarball
openclaw plugins install ./plugin.zip           # install from a local zip
openclaw plugins install -l ./extensions/voice-call # link (no copy) for dev
openclaw plugins install @openclaw/voice-call # install from npm
openclaw plugins update <id>
openclaw plugins update --all
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins doctor

​

Eklenti API’si (genel bakış)

42. Eklentiler şunlardan birini dışa aktarır:

• Bir fonksiyon: (api) => { ... }
• Bir nesne: { id, name, configSchema, register(api) { ... } }

​

43. Eklenti kancaları

​

Örnek

import { registerPluginHooksFromDir } from "openclaw/plugin-sdk";

export default function register(api) {
  registerPluginHooksFromDir(api, "./hooks");
}

• Kanca dizinleri normal kanca yapısını izler (HOOK.md + handler.ts).
• Kanca uygunluk kuralları geçerliliğini korur (OS/binary/ortam/yapılandırma gereksinimleri).
• Eklenti tarafından yönetilen kancalar openclaw hooks list içinde plugin:<id> ile görünür.
• Eklenti tarafından yönetilen kancaları openclaw hooks üzerinden etkinleştirip devre dışı bırakamazsınız; bunun yerine eklentiyi etkinleştirip devre dışı bırakın.

​

Sağlayıcı eklentileri (model kimlik doğrulaması)

• openclaw models auth login --provider <id> [--method <id>]

api.registerProvider({
  id: "acme",
  label: "AcmeAI",
  auth: [
    {
      id: "oauth",
      label: "OAuth",
      kind: "oauth",
      run: async (ctx) => {
        // Run OAuth flow and return auth profiles.
        return {
          profiles: [
            {
              profileId: "acme:default",
              credential: {
                type: "oauth",
                provider: "acme",
                access: "...",
                refresh: "...",
                expires: Date.now() + 3600 * 1000,
              },
            },
          ],
          defaultModel: "acme/opus-1",
        };
      },
    },
  ],
});

• run, prompter, runtime, openUrl ve oauth.createVpsAwareHandlers yardımcılarını içeren bir ProviderAuthContext alır.
• Varsayılan modelleri veya sağlayıcı yapılandırmasını eklemeniz gerektiğinde configPatch döndürün.
• --set-default’nin ajan varsayılanlarını güncelleyebilmesi için defaultModel döndürün.

​

Bir mesajlaşma kanalı kaydetme

const myChannel = {
  id: "acmechat",
  meta: {
    id: "acmechat",
    label: "AcmeChat",
    selectionLabel: "AcmeChat (API)",
    docsPath: "/channels/acmechat",
    blurb: "demo channel plugin.",
    aliases: ["acme"],
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? {
        accountId,
      },
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async () => ({ ok: true }),
  },
};

export default function (api) {
  api.registerChannel({ plugin: myChannel });
}

• Yapılandırmayı channels.<id> altında tutun (plugins.entries altında değil).
• meta.label, CLI/UI listelerinde etiketler için kullanılır.
• meta.aliases, normalleştirme ve CLI girdileri için alternatif id’ler ekler.
• meta.preferOver, her ikisi de yapılandırıldığında otomatik etkinleştirmeyi atlamak için kanal id’lerini listeler.
• meta.detailLabel ve meta.systemImage, UI’lerin daha zengin kanal etiketleri/simgeleri göstermesini sağlar.

​

Yeni bir mesajlaşma kanalı yazma (adım adım)

1. Bir id + yapılandırma şekli seçin

• Tüm kanal yapılandırması channels.<id> altında yer alır.
• Çoklu hesap kurulumları için channels.<id>.accounts.<accountId>’i tercih edin.

2. Kanal meta verilerini tanımlayın

• meta.label, meta.selectionLabel, meta.docsPath, meta.blurb CLI/UI listelerini kontrol eder.
• meta.docsPath, /channels/<id> gibi bir dokümantasyon sayfasına işaret etmelidir.
• meta.preferOver, bir eklentinin başka bir kanalın yerini almasına izin verir (otomatik etkinleştirme onu tercih eder).
• meta.detailLabel ve meta.systemImage, ayrıntı metni/simgeler için UI’ler tarafından kullanılır.

3. Gerekli bağdaştırıcıları uygulayın

• config.listAccountIds + config.resolveAccount
• capabilities (sohbet türleri, medya, iş parçacıkları vb.)
• outbound.deliveryMode + outbound.sendText (temel gönderim için)

4. Gerektikçe isteğe bağlı bağdaştırıcıları ekleyin

• setup (sihirbaz), security (DM politikası), status (sağlık/tanılamalar)
• gateway (başlat/durdur/giriş), mentions, threading, streaming
• actions (mesaj eylemleri), commands (yerel komut davranışı)

5. Eklentinizde kanalı kaydedin

• api.registerChannel({ plugin })

{
  channels: {
    acmechat: {
      accounts: {
        default: { token: "ACME_TOKEN", enabled: true },
      },
    },
  },
}

const plugin = {
  id: "acmechat",
  meta: {
    id: "acmechat",
    label: "AcmeChat",
    selectionLabel: "AcmeChat (API)",
    docsPath: "/channels/acmechat",
    blurb: "AcmeChat messaging channel.",
    aliases: ["acme"],
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? {
        accountId,
      },
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async ({ text }) => {
      // deliver `text` to your channel here
      return { ok: true };
    },
  },
};

export default function (api) {
  api.registerChannel({ plugin });
}

​

Ajan araçları

​

Bir gateway RPC yöntemi kaydetme

export default function (api) {
  api.registerGatewayMethod("myplugin.status", ({ respond }) => {
    respond(true, { ok: true });
  });
}

​

CLI komutları kaydetme

export default function (api) {
  api.registerCli(
    ({ program }) => {
      program.command("mycmd").action(() => {
        console.log("Hello");
      });
    },
    { commands: ["mycmd"] },
  );
}

​

Otomatik yanıt komutları kaydetme

export default function (api) {
  api.registerCommand({
    name: "mystatus",
    description: "Show plugin status",
    handler: (ctx) => ({
      text: `Plugin is running! Channel: ${ctx.channel}`,
    }),
  });
}

46. Komut işleyici bağlamı:

• senderId: Gönderenin kimliği (varsa)
• channel: Komutun gönderildiği kanal
• isAuthorizedSender: Gönderenin yetkili bir kullanıcı olup olmadığı
• args: Komuttan sonra iletilen argümanlar (eğer acceptsArgs: true)
• commandBody: Komutun tam metni
• config: Geçerli OpenClaw yapılandırması

• name: Komut adı (başındaki / olmadan)
• description: Komut listelerinde gösterilen yardım metni
• acceptsArgs: Komutun argüman kabul edip etmediği (varsayılan: false). False ise ve argüman verilirse, komut eşleşmez ve mesaj diğer işleyicilere düşer
• requireAuth: Yetkili gönderici gerektirip gerektirmediği (varsayılan: true)
• handler: { text: string } döndüren fonksiyon (async olabilir)

api.registerCommand({
  name: "setmode",
  description: "Set plugin mode",
  acceptsArgs: true,
  requireAuth: true,
  handler: async (ctx) => {
    const mode = ctx.args?.trim() || "default";
    await saveMode(mode);
    return { text: `Mode set to: ${mode}` };
  },
});

• Eklenti komutları, yerleşik komutlar ve AI ajanından önce işlenir
• Komutlar küresel olarak kaydedilir ve tüm kanallarda çalışır
• Komut adları büyük/küçük harfe duyarsızdır (/MyStatus, /mystatus ile eşleşir)
• Komut adları bir harfle başlamalı ve yalnızca harfler, sayılar, tireler ve alt çizgiler içermelidir
• Ayrılmış komut adları (ör. help, status, reset vb.) eklentiler tarafından geçersiz kılınamaz
• Eklentiler arasında yinelenen komut kaydı, tanılayıcı bir hatayla başarısız olur

​

Arka plan servisleri kaydetme

export default function (api) {
  api.registerService({
    id: "my-service",
    start: () => api.logger.info("ready"),
    stop: () => api.logger.info("bye"),
  });
}

​

47. Adlandırma kuralları

• Gateway yöntemleri: pluginId.action (örnek: voicecall.status)
• Araçlar: snake_case (örnek: voice_call)
• CLI komutları: kebab veya camel; ancak çekirdek komutlarla çakışmaktan kaçının

​

Skills

​

Dağıtım (npm)

• Ana paket: openclaw (bu depo)
• Eklentiler: @openclaw/* altında ayrı npm paketleri (örnek: @openclaw/voice-call)

• Eklenti package.json’ü, bir veya daha fazla giriş dosyası içeren openclaw.extensions’ü içermelidir.
• Giriş dosyaları .js veya .ts olabilir (jiti, TS’yi çalışma zamanında yükler).
• openclaw plugins install <npm-spec>, npm pack kullanır, ~/.openclaw/extensions/<id>/ içine çıkarır ve yapılandırmada etkinleştirir.
• Yapılandırma anahtarı kararlılığı: kapsamlı paketler, plugins.entries.* için kapsamsız id’ye normalize edilir.

​

Örnek eklenti: Voice Call

• Kaynak: extensions/voice-call
• Skill: skills/voice-call
• CLI: openclaw voicecall start|status
• Araç: voice_call
• RPC: voicecall.start, voicecall.status
• Yapılandırma (twilio): provider: "twilio" + twilio.accountSid/authToken/from (isteğe bağlı statusCallbackUrl, twimlUrl)
• Yapılandırma (geliştirme): provider: "log" (ağ yok)

​

Güvenli kullanım notları

• Yalnızca güvendiğiniz eklentileri kurun.
• plugins.allow izin listelerini tercih edin.
• Değişikliklerden sonra Gateway’i yeniden başlatın.

​

Eklentileri test etme

• Depo içi eklentiler, Vitest testlerini src/** altında tutabilir (örnek: src/plugins/voice-call.plugin.test.ts).
• Ayrı yayımlanan eklentiler kendi CI’larını (lint/build/test) çalıştırmalı ve openclaw.extensions’nın derlenmiş giriş noktasını işaret ettiğini doğrulamalıdır (dist/index.js).