OpenClaw ile Özel Yapay Zeka Aracıları Oluşturma: Geliştirici Kılavuzu

Üretime hazır bir yapay zeka aracısı oluşturmak, bir sohbet robotu yazmakla aynı şey değildir. Aracıların bağlamı algılaması, eksik bilgiler üzerinde mantık yürütmesi, çok adımlı planları yürütmesi ve hatalardan kurtulması gerekir; bunların tümünü insan denetimi olmadan yapmalıdır. OpenClaw, geliştiricilere yapılandırılmış bir çalışma süresi, beceri kompozisyon modeli ve ilk günden itibaren birinci sınıf gözlemlenebilirlik sağlayan, özellikle bu seviyedeki operasyonel özerklik için oluşturulmuş bir kurumsal yapay zeka aracı platformudur.

Bu kılavuz, sıfırdan konuşlandırılmış, izlenen bir OpenClaw aracısına geçmek isteyen mühendisler için yazılmıştır. Aracıların üretim yükü altında güvenilir kalmasını sağlayan mimari iç bileşenleri, beceri yazmayı, bellek yönetimini, orkestrasyon kancalarını ve dağıtım modellerini ele alıyoruz.

Önemli Çıkarımlar

OpenClaw aracıları Becerilerden (atomik yetenekler), Bellek katmanlarından ve yürütme sıralarını planlayan bir Orkestratörden oluşur.

Ajan Bildirimi dosyası, çalışma zamanından önce tüm bağımlılıkları, izinleri ve araç bağlamalarını bildirir.

Beceriler, yazılan girdileri kabul eden ve yazılan çıktıları yayan durum bilgisi olmayan işlevlerdir; test edilebilirlik yerleşiktir.

Çalışma Belleği, Bölüm Belleği ve Uzun Süreli Bellek katmanları farklı saklama ve geri alma ihtiyaçlarına hizmet eder.

Kancalar (çalışma öncesi, çalışma sonrası, hata durumunda), temel beceri kodunu değiştirmeden izleme, hız sınırlama ve geri dönüş mantığı eklemenizi sağlar.

OpenClaw'ın Sandbox modu, canlı API çağrıları olmadan hata ayıklama için üretim izlerini yerel olarak yeniden oynatmanıza olanak tanır.

Çoklu aracı aktarımları, yazılı bir Mesaj Veriyolu kullanır; aracılar arasında ham dize geçişi olmaz.

ECOSIRE, kurumsal ekipler için yönetilen OpenClaw uygulamaları, özel beceri kitaplıkları ve sürekli optimizasyon sağlar.

OpenClaw Aracı Modelini Anlamak

Her OpenClaw aracısı dört temel unsurdan oluşur: Beceriler, Bellek, Araçlar ve Orkestratör.

Beceriler, temsilci yeteneğinin atomik birimleridir. Beceri, yazılan bir giriş şemasını kabul eden ve yazılan bir çıktı şemasını döndüren bir işlevdir. Beceriler eşzamanlı veya eşzamansız olabilir ve dış bağımlılıklarını açıkça bildirirler. Örnekler: KOD0, KOD1, KOD2, KOD3.

Araçlar harici sistem bağlamalarıdır. OpenClaw, REST API'leri, veritabanları, dosya sistemleri, tarayıcılar ve mesaj kuyrukları için yerleşik araçlarla birlikte gelir. Araçları Aracı Bildirimi'ne kaydedersiniz ve bunları bağımlılık enjeksiyonu yoluyla çalışma zamanında becerilere enjekte edersiniz.

Bellek üç katman halinde düzenlenmiştir. Çalışma Belleği mevcut görev durumunu, yani aracının karalama defterini tutar. Bölüm Belleği, geçerli oturumdaki anlamsal benzerliğe göre alınabilen tamamlanmış görev geçmişlerini saklar. Uzun Süreli Bellek, oturumlar boyunca varlığını sürdürür ve öğrenilen gerçekleri, kullanıcı tercihlerini ve alan bilgisini depolar.

Orkestratör muhakeme çekirdeğidir. Bir hedef bildirimi alır, mevcut beceri kaydını sorgular, bir yürütme planı oluşturur ve her adımı izler. Bir beceri başarısız olduğunda, orkestratör yeniden denemeye, alternatif bir beceriyi değiştirmeye veya bir insana yükseltmeye karar verir.

Tek bir aracının mimari diyagramı şuna benzer:

User Request
     ↓
[ Orchestrator ]
     ↓ plan
[ Skill Selector ] → [ Skill Registry ]
     ↓ execute
[ Skill Instance ]
     ↓ tool calls
[ Tool Layer ] → [ External Systems ]
     ↓ result
[ Memory Writer ]
     ↓ store
[ Working / Episode / Long-Term Memory ]
     ↓ next step or done
[ Orchestrator ] → response

Bu döngü, orkestratör hedefin karşılandığını veya durma koşuluna ulaşıldığını belirleyene kadar devam eder.

Geliştirme Ortamınızı Kurma

İlk becerinizi yazmadan önce OpenClaw SDK'sına ve yerel aracı çalışma zamanına ihtiyacınız var.

npm install @openclaw/sdk @openclaw/runtime @openclaw/cli
npx openclaw init my-agent --template=typescript

init komutu şu yapıya sahip bir proje oluşturur:

my-agent/
  agent.manifest.json   # Agent declaration
  skills/               # Skill implementations
  tools/                # Tool registrations
  memory/               # Memory adapter config
  tests/                # Skill and integration tests
  .openclaw/            # Local runtime state

agent.manifest.json en önemli dosyadır. OpenClaw'ın aracınızı önyüklemesi için ihtiyaç duyduğu her şeyi bildirir:

{
  "name": "invoice-processor",
  "version": "1.0.0",
  "runtime": "node-20",
  "skills": [
    "skills/extract-line-items.ts",
    "skills/validate-vendor.ts",
    "skills/post-to-erp.ts"
  ],
  "tools": {
    "erp": { "type": "rest", "baseUrl": "${ERP_BASE_URL}", "auth": "bearer" },
    "storage": { "type": "s3", "bucket": "${DOCS_BUCKET}" }
  },
  "memory": {
    "working": { "ttl": 3600 },
    "episode": { "backend": "redis", "maxItems": 500 },
    "longTerm": { "backend": "postgres", "table": "agent_facts" }
  },
  "permissions": ["read:invoices", "write:erp", "read:vendors"]
}

Ortam değişkenleri çalışma zamanında enjekte edilir ve hiçbir zaman bildirimde saklanmaz.

İlk Becerinizi Yazma

Beceriler sıkı bir sözleşmeye tabidir. Bildirilen bir şemayla eşleşen bir input nesnesini kabul ederler, enjekte edilen tools ve memory'yi alırlar ve bir output nesnesi döndürürler veya yazılan bir SkillError atarlar.

import { defineSkill, SkillError } from "@openclaw/sdk";
import { z } from "zod";

const ExtractLineItemsInput = z.object({
  documentUrl: z.string().url(),
  documentType: z.enum(["invoice", "receipt", "purchase-order"]),
});

const ExtractLineItemsOutput = z.object({
  lineItems: z.array(
    z.object({
      description: z.string(),
      quantity: z.number(),
      unitPrice: z.number(),
      total: z.number(),
    })
  ),
  confidence: z.number().min(0).max(1),
});

export const ExtractLineItems = defineSkill({
  name: "extract-line-items",
  description: "Extracts line items from a document using OCR and LLM parsing",
  input: ExtractLineItemsInput,
  output: ExtractLineItemsOutput,
  tools: ["storage"],
  async run({ input, tools, memory }) {
    const fileBuffer = await tools.storage.get(input.documentUrl);
    if (!fileBuffer) {
      throw new SkillError("DOCUMENT_NOT_FOUND", `No document at ${input.documentUrl}`);
    }

    // OCR + LLM extraction logic here
    const extracted = await runOcrPipeline(fileBuffer);

    await memory.working.set("lastExtraction", extracted);

    return {
      lineItems: extracted.items,
      confidence: extracted.confidence,
    };
  },
});

Beceriler için temel tasarım kuralları:

Girişte hiçbir yan etki yoktur: Beceriler, giriş nesnelerini değiştirmemelidir.
Yazım hataları: SkillError kodunu her zaman makine tarafından okunabilen bir kodla atın, genel Error kodunu değil.
Araç bağımlılıklarını bildir: Yalnızca tools dizisinde bildirilen araçlar eklenir. Bildirilmemiş araçlar başlangıç doğrulama hatasına neden olur.
Bellek'e açıkça yaz: Beceriler durumu otomatik olarak sürdürmez. memory.working.set()'ı bilinçli olarak arayın.

Uygulamada Bellek Yönetimi

Üç bellek katmanı farklı amaçlara hizmet eder ve doğru katmanın seçilmesi aracının doğruluğu açısından kritik öneme sahiptir.

Çalışan Bellek, tek bir görev çalıştırması boyunca varlığını sürdüren, süreç içi bir anahtar/değer deposudur. Çıktı zincirinden geçmeden beceriler arasındaki ara sonuçları aktarmak için bunu kullanın. Orkestratör tamamlandığında veya zaman aşımına uğradığında otomatik olarak temizlenir.

// Skill A writes
await memory.working.set("vendorId", "VND-4521");

// Skill B reads
const vendorId = await memory.working.get("vendorId");

Bölüm Belleği anlamsal bir arama deposudur. Bir görev tamamlandığında, orkestratör isteğe bağlı olarak bölüm belleğine gömülen bir özet yazar. Gelecekteki görevler, gerekçelerini bildirmek için benzer geçmiş bölümleri alabilir.

// Query past episodes
const relatedEpisodes = await memory.episode.search(
  "invoice from Acme Corp with disputed line items",
  { topK: 3, minScore: 0.75 }
);

Uzun Süreli Bellek temsilcinizin kalıcı bilgi tabanıdır. Oturumlar boyunca geçerli olması gereken gerçekler için bunu kullanın: satıcı sınıflandırma kuralları, kullanıcı tercihleri, öğrenilen etki alanı kısıtlamaları.

// Store a learned fact
await memory.longTerm.upsert({
  key: `vendor:${vendorId}:paymentTerms`,
  value: "NET-30",
  source: "invoice-2024-0312",
  confidence: 0.9,
});

Yaygın bir hata, uzun süreli belleğe aşırı yazmaktır. Bunu istikrarlı, yüksek güvenirliğe sahip gerçekler için saklayın. Geçici akıl yürütme, çalışma belleğine aittir.

Gözlemlenebilirlik ve Kontrol için Yaşam Döngüsü Kancaları

OpenClaw beceri yürütme başına dört yaşam döngüsü kancası ortaya çıkarır: preRun, postRun, onError ve onTimeout. Kancaları aracı bildirimine veya önyükleme dosyanıza programlı olarak kaydedin.

import { AgentRuntime } from "@openclaw/runtime";

const agent = new AgentRuntime({ manifest: "./agent.manifest.json" });

agent.useHook("preRun", async (ctx) => {
  ctx.metadata.startTime = Date.now();
  console.log(`[${ctx.skill}] starting with input keys: ${Object.keys(ctx.input)}`);
});

agent.useHook("postRun", async (ctx) => {
  const elapsed = Date.now() - ctx.metadata.startTime;
  metrics.record("skill.duration", elapsed, { skill: ctx.skill });
});

agent.useHook("onError", async (ctx) => {
  if (ctx.error.code === "RATE_LIMIT_EXCEEDED") {
    await sleep(ctx.error.retryAfterMs);
    return "retry";
  }
  alerting.send(`Skill ${ctx.skill} failed: ${ctx.error.message}`);
  return "escalate";
});

onError kanca dönüş değeri orkestratör davranışını kontrol eder: "retry" yeniden denemeyi tetikler (yapılandırılmış maksimum değere kadar), "escalate" görevi bir insan kuyruğuna yönlendirir, "fail" görevi hemen sonlandırır.

İzolasyonda Becerilerin Test Edilmesi

Beceriler girdi ve çıktıları yazdığından birim testi basittir. OpenClaw'ın test yardımcı programları, tüm araç arayüzlerinin sahte uygulamalarını sağlar.

import { testSkill } from "@openclaw/testing";
import { ExtractLineItems } from "../skills/extract-line-items";

describe("ExtractLineItems", () => {
  it("extracts items from a valid invoice", async () => {
    const result = await testSkill(ExtractLineItems, {
      input: {
        documentUrl: "s3://test-bucket/invoice-001.pdf",
        documentType: "invoice",
      },
      mocks: {
        storage: {
          get: jest.fn().mockResolvedValue(samplePdfBuffer),
        },
      },
    });

    expect(result.lineItems).toHaveLength(3);
    expect(result.confidence).toBeGreaterThan(0.8);
  });

  it("throws DOCUMENT_NOT_FOUND for missing file", async () => {
    await expect(
      testSkill(ExtractLineItems, {
        input: { documentUrl: "s3://test-bucket/missing.pdf", documentType: "invoice" },
        mocks: { storage: { get: jest.fn().mockResolvedValue(null) } },
      })
    ).rejects.toMatchObject({ code: "DOCUMENT_NOT_FOUND" });
  });
});

Entegrasyon testleri için Sandbox modunu kullanın. Sandbox, kayıtlı üretim izlerini mevcut beceri kodunuza göre yeniden oynatır ve gerilemeleri canlı sistemlere ulaşmadan yakalar.

npx openclaw sandbox replay --trace=traces/invoice-20240315.json

Üretime Dağıtım

OpenClaw aracıları Docker kapsayıcıları, sunucusuz işlevler veya uzun süren işlemler olarak dağıtılabilir. Kurumsal dağıtımlar için önerilen model, bir görev kuyruğunun arkasında konteynerleştirilmiş bir aracı havuzudur.

FROM openclaw/runtime:node-20
WORKDIR /agent
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN npx openclaw build
CMD ["npx", "openclaw", "serve", "--workers=4"]

Yüksek verimli senaryolar için aracı havuzunu otomatik ölçeklendirme kurallarıyla yapılandırın. OpenClaw çalışma zamanı, sıra derinliği, beceri gecikme yüzde dilimleri, hata oranları ve bellek kullanımına ilişkin Prometheus ölçümlerini /metrics adresinde gösterir; bunları uyarı yığınınıza bağlayın.

Canlı kullanıma geçmeden önce üretim kontrol listesi:

Tüm ortam değişkenleri .env dosyalarında değil, bir gizli dizi yöneticisinde (AWS Secrets Manager, HashiCorp Vault) bulunur.
Bellek arka uçlarında (Redis, PostgreSQL) bağlantı havuzu yapılandırılmıştır.
maxConcurrentTasks ayarı altyapı kapasitenize uygundur.
Harici araç çağrılarındaki hız limitleri, satıcı API limitleriyle eşleşir.
Yeniden denemeleri tüketen görevler için bir atılacak ileti kuyruğu yapılandırılır.
Dağıtılmış izleme (OpenTelemetry) etkinleştirildi ve izler gözlemlenebilirlik platformunuza akıyor.

Sıkça Sorulan Sorular

OpenClaw orkestratörü bir sonraki adımda hangi becerinin çalıştırılacağına nasıl karar veriyor?

Orkestracı, hedef ayrıştırma ve beceri eşleştirmenin bir kombinasyonunu kullanır. Üst düzey hedefi alt hedeflere böler, ardından her bir alt hedefin açıklamasına göre anlamsal benzerliği kullanarak beceri kaydını sorgular. Beceriler uygunluk puanına, bağımlılığın kullanılabilirliğine ve geçmiş başarı oranına göre sıralanır. Orkestratör, beceri uygulamalarının yönlendirilmiş, döngüsel olmayan bir grafiğini oluşturur ve başlamadan önce bağımlılıkları çözer.

Bir beceri başka bir beceriyi doğrudan çağırabilir mi?

Hayır; beceriler doğrudan diğer becerileri çağırmamalıdır. Çapraz beceri koordinasyonu orkestratörün sorumluluğundadır. B becerisi çalıştırılmadan önce A becerisinin çıktısına ihtiyacınız varsa, bağımlılığı orkestratör planında bildirin. Bu, becerilerin durumsuz ve bireysel olarak test edilebilir olmasını sağlar. Bunun istisnası, açıkça orkestrasyon temelleri olarak işaretlenen bileşik becerilerdir.

Beceri yürütme sırasında harici bir API kapalı olduğunda ne olur?

onError kancası arızayı keser. Kanca "retry" değerini döndürürse, orkestratör yapılandırılmış geri çekilme aralığını bekler ve beceriyi yeniden dener. Yeniden denemeler tükendikten sonra görev, atılacak iletiler kuyruğuna taşınır. Aynı yetenek için kayıtlı bir yedek beceriniz varsa orkestratör vazgeçmeden önce bunu deneyecektir. Kısmi görev durumu Çalışma Belleğinde korunur, böylece görev son başarılı beceriden devam edebilir.

Çalışma zamanında becerilerin ihtiyaç duyduğu sırları nasıl ele alıyorsunuz?

Aracı bildiriminde bildirilen araçlar, beceriye göre değil, başlangıçta kimlik bilgileriyle başlatılır. Gizli dizi yöneticiniz, manifestte başvurulan ortam değişkenlerini (${ERP_BASE_URL}, ${DOCS_BUCKET}, vb.) kapsayıcı başlangıcında doldurur. Beceriler hiçbir zaman ham kimlik bilgilerini görmez; çalışma zamanı tarafından enjekte edilen, önceden kimliği doğrulanmış araç örnekleriyle etkileşime girer.

Bir temsilcinin sahip olabileceği beceri sayısının bir sınırı var mı?

Beceri kaydının kesin bir sınırı yoktur, ancak yüzlerce beceriyi örtüşen açıklamalarla kaydederseniz pratik orkestrasyon kalitesi düşer. İlgili becerileri beceri paketleri halinde gruplayın ve açık, farklı açıklamalar kullanın. Çok büyük beceri kitaplıkları için, özel aracılara ayrılmayı ve görevleri doğru aracıya yönlendirmek için çoklu aracı orkestrasyonunu kullanmayı düşünün.

OpenClaw aracıları bulut bağımlılıkları olmadan şirket içinde çalışabilir mi?

Evet. OpenClaw buluttan bağımsızdır. Çalışma zamanı, bellek arka uçları ve araç katmanının tamamı şirket içi altyapıyı kullanacak şekilde yapılandırılabilir. Redis yerel olarak çalışabilir, uzun vadeli bellek arka ucu şirket içi bir PostgreSQL örneğine işaret edebilir ve araç entegrasyonları dahili API'leri hedefleyebilir. Orkestratörün gerekçelendirilmesi için tek harici çağrı LLM sağlayıcısına yapılır; gerekirse bunu şirket içi bir LLM kullanacak şekilde yapılandırabilirsiniz.

Çalışan görevleri bozmadan aracı becerilerini nasıl sürümlendirirsiniz?

Beceriler, aracı bildiriminde anlamsal sürümlendirmeyle sürümlendirilir. Çalışma zamanı, sürekli dağıtım sırasında birden fazla beceri sürümünün aynı anda çalıştırılmasını destekler. Uçuş sırasındaki görevler, başladıkları beceri sürümünü kullanmaya devam eder; yeni görevler en son sürümü alır. Beceri giriş/çıkış şemalarında yapılan son değişiklikler, bu becerinin çıktısını tüketen herhangi bir aracı için büyük bir sürüm artışı ve bir geçiş planı gerektirir.

Sonraki Adımlar

Üretim düzeyinde yapay zeka aracıları oluşturmak, iyi koddan fazlasını gerektirir; geliştirilmesi ve iyileştirilmesi aylar süren hata modları, ölçeklendirme modelleri ve alana özgü beceri kitaplıkları konusunda operasyonel deneyim gerektirir.

ECOSIRE'ın OpenClaw Özel Beceriler hizmeti uçtan uca aracı geliştirme sağlar: gereksinim analizi, beceri mimarisi, mevcut sistemlerinizle entegrasyon, test etme, dağıtım ve sürekli optimizasyon. Ekibimiz belge işleme, ERP otomasyonu, müşteri desteği, finansal analiz ve daha fazlası için OpenClaw aracıları oluşturdu.

Otomasyon gereksinimlerinizi görüşmek ve özel bir geliştirme yol haritası almak için Bir OpenClaw uzmanıyla konuşun.

Building Custom AI Agents with OpenClaw: Developer Guide