OpenClaw Aracıları için API Entegrasyon Modelleri

Bir yapay zeka aracısının değeri, erişebildiği ve üzerinde işlem yapabileceği sistemlerle orantılıdır. Yalnızca metin okuyup yazabilen bir aracı, gelişmiş bir sohbet robotudur. ERP'nize, CRM'nize, veritabanlarınıza ve üçüncü taraf hizmetlerinize sağlam, güvenilir bağlantılara sahip bir aracı, özerk bir operasyonel yetenektir.

Bu entegrasyonları doğru kimlik doğrulama, hata işleme, hız sınırlama, yeniden deneme mantığı ve testlerle doğru şekilde oluşturmak, demolarda çalışan bir aracı ile üretim trafiğini yıllarca güvenilir bir şekilde yöneten bir aracı arasındaki farktır. Bu kılavuz, üretim düzeyindeki OpenClaw entegrasyonlarını kırılgan kavram kanıtlama kodundan ayıran kalıpları kapsar.

Önemli Çıkarımlar

• Aracılar, Araçlar aracılığıyla harici sistemlere bağlanır - API çağrılarını uygun hata işlemeyle kapsayan ayrı işlevler
• Belirteç yenilemeli OAuth 2.0, üçüncü taraf API kimlik doğrulaması için standarttır; kimlik bilgileri hiçbir zaman istemlerde bulunmaz
• Kimlik anahtarları, aracılar başarısız istekleri yeniden denediğinde yinelenen eylemleri önler
• Devre kesiciler, harici hizmetler mevcut olmadığında aracıları art arda gelen arızalardan korur
• Hız sınırı farkındalığı, aracıların yeniden deneme döngüleri aracılığıyla API kısıtlamasını tetiklemesini önler
• Web kancası modelleri, aracıların yoklama yerine harici olaylara tepki vermesine olanak tanır
• Kaydedilen API yanıtlarıyla entegrasyon testi, güvenilir otomatik testlere olanak sağlar
• Entegrasyon sınırlarındaki şema tarafından doğrulanan girişler ve çıkışlar, veri kalitesi sorunlarını önler

---

Araç Mimarisi

OpenClaw aracıları, Araçlar aracılığıyla harici sistemlerle etkileşime girer. Araç, bir API uç noktasını sorgulamak, bir veritabanı kaydı yazmak, bir e-posta göndermek, bir CRM alanını güncellemek gibi tek bir harici eylemi kapsayan ayrı, iyi tanımlanmış bir işlevdir.

Bu mimari kasıtlıdır. Aracıya doğrudan API erişimi vermek yerine, her harici etkileşime aşağıdakileri gerçekleştiren bir Araç aracılığıyla aracılık edilir:

• API çağrısı yapmadan önce girişleri doğrular
• Kimlik doğrulamayı şeffaf bir şekilde yönetir
• Uygun hata işleme ve yeniden deneme mantığını uygular
• Harici API'nin formatından bağımsız olarak yapılandırılmış, normalleştirilmiş çıktı döndürür
• Gözlemlenebilirlik ve hata ayıklama için her çağrıyı günlüğe kaydeder

Araç tasarım ilkeleri:

Tek sorumluluk: Her Araç belirli bir şeyi yapar. Bir CRM entegrasyonu ayrı Araçlar sunar: getCRMContact, updateCRMContact, createCRMOpportunity, logCRMActivity. Her şeyi yapan tek bir crmTool yok.

Tasarım gereği eşgüçlü: Mümkün olduğunda, veri yazan Araçlar eşgüçlü olmalıdır; bunları aynı girdiyle birden çok kez çağırmak, onları bir kez çağırmakla aynı sonucu verir. Bu, yeniden deneme mantığını güvenli hale getirir.

Yazılan girişler ve çıkışlar: Her Aracın tanımlanmış bir giriş şeması (kabul ettiği parametreler, türleri, hangilerinin gerekli olduğu) ve tanımlanmış bir çıkış şeması vardır. Aracı, doğrulanmış girişlerle Aracı çağırır ve normalleştirilmiş çıktı alır. Şekil tutarlılığı, aracının Araç çıktıları hakkında güvenilir bir şekilde akıl yürütmesini sağlar.

Açık hata semantiği: Araçlar, ham HTTP hata kodları yerine işlem yapılabilir kodlar (RATE_LIMITED, NOT_FOUND, AUTHENTICATION_FAILED, VALIDATION_ERROR) içeren yapılandırılmış hatalar döndürür. Temsilci, hata türüne göre akıllı kararlar verebilir.

---

Kimlik Doğrulama Modelleri

Kimlik doğrulama, API entegrasyonunun güvenliğe en duyarlı yönüdür. Yanlış kullanılan kimlik bilgileri, hem güvenlik ihlallerinin hem de gizemli arızaların en yaygın nedenidir.

API Anahtarı Kimlik Doğrulaması

En basit biçim, istek başlığına gizli bir anahtar eklemektir. Uygulama hususları:

Depolama: API anahtarları gizli dizi yönetim sisteminde depolanır (AWS Secrets Manager, HashiCorp Vault, sınırlı erişime sahip ortam değişkenleri). Bunlar hiçbir zaman Beceri kodunda, bilgi istemi şablonlarında veya kaynak kontrolüne teslim edilen yapılandırma dosyalarında sabit kodlanmaz.

Döndürme: API anahtarları döndürülebilir olmalıdır. Entegrasyon, geçerli anahtarı süresiz olarak önbelleğe almak yerine her yürütmede gizli depodan alır. Bir anahtar döndürüldüğünde herhangi bir kod değişikliği gerekmez.

Kapsam belirleme: Gerekli minimum izinlere sahip API anahtarlarını isteyin. Bir raporlama entegrasyonunun yalnızca okuma erişimine ihtiyacı vardır; işlemsel bir entegrasyonun yalnızca ilgili uç noktalara yazma erişimine ihtiyacı vardır.

# Pattern: retrieve secret from secrets manager, not hardcoded
def get_api_key() -> str:
    return secrets_manager.get_secret("salesforce-api-key")

def call_salesforce_api(endpoint: str, payload: dict) -> dict:
    headers = {
        "Authorization": f"Bearer {get_api_key()}",
        "Content-Type": "application/json"
    }
    response = requests.post(endpoint, json=payload, headers=headers)
    response.raise_for_status()
    return response.json()

OAuth 2.0 ve Token Yenileme

OAuth 2.0 (Salesforce, Microsoft 365, Google Workspace, HubSpot) kullanan üçüncü taraf hizmetler için erişim jetonunun süresi düzenli aralıklarla dolar ve yenileme jetonu kullanılarak yenilenmesi gerekir. Bunun şeffaf bir şekilde ele alınması üretim güvenilirliği açısından kritik öneme sahiptir.

Token yaşam döngüsü yönetimi:

class OAuthTokenManager:
    def __init__(self, client_id, client_secret, token_store):
        self.client_id = client_id
        self.client_secret = client_secret
        self.token_store = token_store

    def get_access_token(self) -> str:
        token_data = self.token_store.get()
        if token_data and not self._is_expired(token_data):
            return token_data["access_token"]
        return self._refresh_token(token_data["refresh_token"])

    def _is_expired(self, token_data: dict) -> bool:
        # Treat token as expired 5 minutes before actual expiry
        return time.time() > token_data["expires_at"] - 300

    def _refresh_token(self, refresh_token: str) -> str:
        response = requests.post(TOKEN_ENDPOINT, data={
            "grant_type": "refresh_token",
            "client_id": self.client_id,
            "client_secret": self.client_secret,
            "refresh_token": refresh_token
        })
        new_token_data = response.json()
        new_token_data["expires_at"] = time.time() + new_token_data["expires_in"]
        self.token_store.save(new_token_data)
        return new_token_data["access_token"]

Bu model, aracının manuel müdahale olmadan ve çalışma zamanı hatalarına neden olan belirteç süresinin dolmadan her zaman geçerli bir belirtecine sahip olmasını sağlar.

Yüksek Güvenlikli Entegrasyonlar için mTLS

Finansal sistemler, sağlık hizmeti API'leri veya karşılıklı TLS kimlik doğrulaması gerektiren devlet hizmetleriyle entegrasyonlar için:

• Sır yönetim sisteminde saklanan istemci sertifikası ve özel anahtar
• Bağlantı kurulduğunda alındı
• Sertifika rotasyonu, kod değişikliği olmadan sır yöneticisi güncellemesi aracılığıyla gerçekleştirilir

---

Hata İşleme Modelleri

Hata Sınıflandırması

Hataları uygun yanıtlarına göre sınıflandırın; bu, yeniden deneme ve yükseltme mantığını harekete geçirir:

Üstel Geri Alma ile Yeniden Deneyin

Şiddetli sürü sorunlarından kaçınmak için geçici başarısızlıklar üstel geri çekilme ve titreşimle yeniden denenmelidir:

def retry_with_backoff(func, max_retries=3, base_delay=1.0):
    for attempt in range(max_retries + 1):
        try:
            return func()
        except TransientError as e:
            if attempt == max_retries:
                raise
            # Exponential backoff with jitter
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)

Yeniden deneme sınırları: Maksimum yeniden deneme sayısını (genellikle 3-5) ayarlayın; bunun ardından Araç, bir başarısızlık sonucu döndürür. Sonsuz yeniden deneme döngüleri hiçbir zaman uygun değildir.

Titreşim: Bir hizmet kurtarıldıktan sonra tüm aracıların aynı anda yeniden denemesini önlemek için yeniden deneme gecikmelerine rastgele varyasyon ekleyin.

Kimlik Anahtarları

Yazma işlemleri için (sipariş oluşturma, e-posta gönderme, ödemeleri başlatma), yeniden denediğinizde yinelenen eylemleri önlemek için kimlik anahtarlarını kullanın:

def create_payment(amount, currency, customer_id):
    # Derive idempotency key from the logical operation, not a random UUID
    # This ensures the same payment request always maps to the same key
    idempotency_key = hashlib.sha256(
        f"payment:{customer_id}:{amount}:{currency}:{date.today()}"
        .encode()
    ).hexdigest()

    response = payment_api.create(
        amount=amount,
        currency=currency,
        customer_id=customer_id,
        idempotency_key=idempotency_key
    )
    return response

Stripe API, çoğu modern ödeme API'si ve birçok SaaS API'si, idempotency anahtarlarını destekler. Bunu yapmayan API'ler için, yeniden denemeden önce işlemin daha önce tamamlanıp tamamlanmadığını kontrol ederek OpenClaw düzeyinde idempotency uygulayın.

---

Hız Sınırlama Modelleri

API Hız Sınırlarına Saygı

API'ler, kötüye kullanımı önlemek için oran sınırlarını zorunlu kılar. Hız sınırlarını göz ardı eden bir aracı kısıtlanacak, bu da güvenilirlik sorunlarına neden olacak ve potansiyel olarak IP adreslerinin veya API anahtarlarının askıya alınmasına neden olacaktır.

Oran sınırı farkındalığı:

1. Her API yanıtındaki hız sınırı başlıklarını saklayın (X-RateLimit-Remaining, X-RateLimit-Reset)
2. Talepte bulunmadan önce kalan limitin sıfıra yaklaşıp yaklaşmadığını kontrol edin.
3. Sınıra yaklaşılıyorsa 429 yanıtı beklemek yerine proaktif olarak yavaşlayın

class RateLimitedAPIClient:
    def __init__(self, calls_per_minute: int):
        self.calls_per_minute = calls_per_minute
        self.call_times = []

    def _can_call(self) -> bool:
        now = time.time()
        # Remove calls older than 60 seconds
        self.call_times = [t for t in self.call_times if now - t < 60]
        return len(self.call_times) < self.calls_per_minute

    def call(self, func):
        while not self._can_call():
            time.sleep(0.5)
        self.call_times.append(time.time())
        return func()

Kuyruğa Alma İsteği

Yüksek hacimleri işleyen aracılar için trafiği düzeltmek amacıyla bir istek kuyruğu kullanın:

# Agents submit API requests to the queue
# The queue worker processes at the API's rate limit
# Agents are notified of results asynchronously

class APIRequestQueue:
    def submit(self, request: APIRequest) -> str:
        """Returns a job_id for result retrieval"""
        job_id = uuid4()
        self.queue.push(job_id, request)
        return job_id

    def get_result(self, job_id: str) -> Optional[APIResult]:
        return self.result_store.get(job_id)

---

Devre Kesici Modeli

Devre kesici, bir aracının arızalı bir harici hizmeti tekrar tekrar aramasını önleyerek, aracıyı art arda gelen arızalardan korurken hizmete iyileşmesi için zaman tanır.

Eyaletler:

• Kapalı (normal çalışma): Tüm çağrılar aktarılır
• Açık (hizmet kapalı): Hizmet denenmeden tüm aramalar hemen başarısız oluyor
• Yarı açık (test kurtarma): Sınırlı sayıda test çağrısı geçer; başarılı olurlarsa devre kapanır; başarısız olursa devre yeniden açılır

class CircuitBreaker:
    def __init__(self, failure_threshold=5, recovery_timeout=60):
        self.failure_count = 0
        self.failure_threshold = failure_threshold
        self.recovery_timeout = recovery_timeout
        self.state = "closed"
        self.last_failure_time = None

    def call(self, func):
        if self.state == "open":
            if time.time() - self.last_failure_time > self.recovery_timeout:
                self.state = "half-open"
            else:
                raise CircuitOpenError("Circuit is open, service unavailable")

        try:
            result = func()
            if self.state == "half-open":
                self.state = "closed"
                self.failure_count = 0
            return result
        except Exception as e:
            self.failure_count += 1
            self.last_failure_time = time.time()
            if self.failure_count >= self.failure_threshold:
                self.state = "open"
            raise

OpenClaw'ın aracı çerçevesi, her harici entegrasyonu saran yerleşik bir devre kesici sağlar. Operatörler entegrasyon başına eşikleri ve kurtarma zaman aşımlarını yapılandırabilir.

---

Webhook Entegrasyon Modeli

Webhook entegrasyonları, durum değişiklikleri için harici hizmetleri yoklamak yerine, bir şey olduğunda harici hizmetlerin olayları aracıya iletmesine olanak tanır. Bu, gecikmeyi dakikalardan saniyelere düşürür ve gereksiz API çağrılarını ortadan kaldırır.

Gelen web kancası yönetimi:

@webhook_endpoint("/hooks/stripe")
def handle_stripe_webhook(request: WebhookRequest):
    # Verify webhook signature
    stripe.webhook.verify_signature(
        request.body,
        request.headers["Stripe-Signature"],
        STRIPE_WEBHOOK_SECRET
    )

    event = stripe.Event.construct_from(request.json())

    # Route to appropriate agent workflow
    if event.type == "payment_intent.succeeded":
        agent_workflows.trigger("process_successful_payment", event.data)
    elif event.type == "customer.subscription.deleted":
        agent_workflows.trigger("handle_subscription_cancellation", event.data)

    return {"status": "received"}

Web kancası güvenilirliği:

• İmza doğrulamasından hemen sonra 200'ü döndürün — web kancası işleyicisindeki uzun işlem, zaman aşımı sorunlarına neden olur
• Aracı kuyruğunda olayları eşzamansız olarak işleyin
• Bağımsızlığı uygulayın — teslimat en az bir kez yapılır, bu nedenle kopyaları tespit etmek için olay kimliklerini işleyin
• Tekrar oynatma özelliği için işlenmeden önce alınan tüm olayları saklayın

---

GraphQL Entegrasyonu

GraphQL API'lerine (Shopify, GitHub, Contentful ve diğerleri) sahip sistemler için OpenClaw, sorgu oluşturma ve değişken ekleme işlemlerini gerçekleştiren GraphQL'e özgü Araçlar sağlar:

def get_shopify_orders(shop_id: str, status: str, limit: int = 50) -> list:
    query = """
    query GetOrders($status: OrderSortKeys!, $limit: Int!) {
      orders(first: $limit, sortKey: $status) {
        edges {
          node {
            id
            name
            totalPrice
            fulfillmentStatus
            customer {
              email
              firstName
              lastName
            }
          }
        }
      }
    }
    """
    variables = {"status": status, "limit": limit}
    result = shopify_graphql.execute(query, variables)
    return [edge["node"] for edge in result["data"]["orders"]["edges"]]

GraphQL'in kendi kendini belgeleyen yapısı (iç gözlem), Araçların şemadan otomatik olarak oluşturulmasına olanak tanır; GraphQL ağırlıklı entegrasyonlar için önemli bir zaman tasarrufu sağlar.

---

Entegrasyon Testi

Harici API'leri çağıran entegrasyonları test etmek, mevcut harici hizmetlere bağlı olmayan stratejiler gerektirir:

Kayıtlı yanıtlar (VCR modeli): Geliştirme sırasında gerçek API yanıtlarını kaydedin, ardından testler sırasında bunları yeniden oynatın. Bu, testleri hızlı, belirleyici hale getirir ve harici hizmet kullanılabilirliğine bağlı değildir.

Saplama sunucuları: Harici API'yi simüle eden yerel bir saplama sunucusunu başlatın. Saplamalar, belirli girişler için yapılandırılmış yanıtlar döndürerek, gerçek API'lerde tetiklenmesi zor olan hata senaryolarının test kapsamına alınmasına olanak tanır.

Sözleşme testi: Entegrasyonunuzun beklentilerinin harici API'nin gerçekte sağladığıyla eşleştiğini doğrulamak için tüketici odaklı sözleşme testlerini (Anlaşma) kullanın. Bu testler, API değişikliklerini üretimi etkilemeden önce yakalar.

Hata ekleme: Saplamaları 429, 500 ve 503 yanıtlarını döndürecek şekilde yapılandırarak ve yeniden deneme mantığının, devre kesicilerin ve yükseltme davranışının doğru şekilde çalıştığını doğrulayarak hata işlemeyi açık bir şekilde test edin.

---

Sıkça Sorulan Sorular

Harici hizmet yeni bir API sürümü yayınladığında API sürüm oluşturma işlemini nasıl yaparız?

Araç yapılandırmanızda belirli bir API sürümüne sabitleyin (çoğu API, başlıklar veya URL yolu aracılığıyla sürüm sabitlemeyi destekler). Her Aracın hangi API sürümünü kullandığını kaydeden bir bağımlılık kayıt defteri tutun. Bir API kullanımdan kaldırıldığını duyurduğunda, üretim Araçlarını taşımadan önce yeni sürümü bir geliştirme ortamında değerlendirin. ECOSIRE, bakım hizmetlerinde API sürümü izlemeyi içerir.

Harici bir API, yanıt şemasını beklenmedik bir şekilde değiştirdiğinde ne olur?

Araçlar'daki çıktı şeması doğrulaması, beklenmeyen şema değişikliklerini yakalar; API artık mevcut olmayan bir alanı veya farklı bir veri türünü döndürürse, Aracın doğrulaması, hatalı biçimlendirilmiş verileri aracıya iletmek yerine açık bir hatayla başarısız olur. Şema doğrulama hataları, uyarıları tetikleyerek aracıların hatalı verilerden yanlış çıktılar üretmesinden önce inceleme yapılmasına olanak tanır.

OpenClaw aracıları, iş kimliklerini döndüren eşzamansız API işlemlerini gerçekleştirebilir mi?

Evet. OpenClaw, eşzamansız Araç kalıplarını destekler: Araç, isteği gönderir ve bir iş kimliği alır, aracı diğer çalışmalarına devam eder ve bir yoklama Aracı (veya web kancası işleyicisi), hazır olduğunda sonucu alır. Çok uzun süren harici işlemler için aracı, bağlantıyı açık tutmak yerine askıya alınabilir ve bir web kancası geri çağrısıyla uyandırılabilir.

API kimlik bilgilerini birden fazla ortamda (geliştirme, hazırlama, üretim) nasıl yönetiriz?

Her ortamın, ortama özgü kimlik bilgilerine işaret eden kendi gizli dizi yönetimi yapılandırması vardır. Geliştirme ortamları korumalı alan API kimlik bilgilerini kullanır; üretim ortamları üretim kimlik bilgilerini kullanır. Kimlik bilgisi alma kodu tüm ortamlarda aynıdır; yalnızca gizli dizi deposu yapılandırması farklılık gösterir. Bu, üretim kimlik bilgilerinin geliştirme aşamasında kullanılmasını önler ve kimlik bilgileriyle ilgili sorunların "geliştirmede çalışıyor ancak üretimde başarısız oluyor" kategorisini ortadan kaldırır.

Sayfalara ayırma gerektiren API entegrasyonları için önerilen model nedir?

Araç içinde sayfalandırmayı şeffaf bir şekilde uygulayın; arayan kişi "bu haftanın tüm siparişlerini" ister ve Araç, birden fazla sayfayı dahili olarak getirme işlemini gerçekleştirir. Mümkün olduğunda imleç tabanlı sayfalandırmayı kullanın (büyük veri kümeleri için ofset tabanlı sayfalandırmadan daha güvenilir). Aracıların yanlışlıkla API kotalarını tüketmesini veya süresiz olarak çalışmasını önlemek için makul kesin sınırlar (ör. maksimum 10.000 kayıt) uygulayın.

Üretim API'si kimlik bilgilerini açığa çıkarmadan CI/CD'deki entegrasyonları nasıl test ederiz?

CI/CD işlem hatları, entegrasyon testleri için saplama sunucularını veya kayıtlı yanıtları kullanır; asla gerçek API kimlik bilgilerini kullanmaz. Üretim kimlik bilgilerine erişim, üretim dağıtım ortamıyla sınırlıdır. Gerçek API doğrulaması gerektiren testler için (duman testleri, sözleşme testleri), sınırlı izinlere sahip ve üretim verilerine erişimi olmayan test kimlik bilgilerine sahip özel test hesapları kullanın.

---

Sonraki Adımlar

Güçlü API entegrasyonu, bir yapay zeka aracısını deneysel bir projeden üretim operasyonel sistemine dönüştüren şeydir. Bu kılavuzdaki modeller, sektörler genelindeki OpenClaw dağıtımlarından üretim açısından test edilmiş yaklaşımları temsil etmektedir.

ECOSIRE'ın OpenClaw uygulama ekibi, API kimlik doğrulaması ve hata işleme modellerinden test ve üretim izlemeye kadar tam entegrasyon mimarisini yönetir, böylece kuruluşunuz entegrasyon tesisatı yerine iş iş akışlarını tanımlamaya odaklanabilir.

Entegrasyon gereksinimlerinizi tartışmak için ECOSIRE OpenClaw Hizmetlerini keşfedin veya ECOSIRE'ın OpenClaw aracı dağıtımları için kurumsal sistem entegrasyonlarına nasıl yaklaştığını anlamak için teknik uygulama sürecimizi inceleyin.