OpenClaw Kurulumu ve OmniProxy Yapılandırması

OpenClaw, kendi bilgisayarınıza kurulan bir AI asistanıdır. Başka bir sohbet penceresini sürekli açık tutmadan doğrudan Telegram, Discord, WhatsApp veya Feishu üzerinden onunla konuşabilirsiniz. Görüşmeler ve kayıtlar bu bilgisayarda kalır; asistan sonraki adımları da yerel olarak tamamlayabilir.

Kurulumdan önce

OpenClaw için Node 24.16 veya üzeri gerekir; Node 26.1 veya üzeri de kullanılabilir. Node 26 önerilir. Node, OpenClaw’ın çalışması için gereken temel çalışma ortamıdır.

macOS, Linux ve Windows üzerinde kurulabilir. Bilgisayarda uygun bir Node sürümü yoksa kurulum betiği bunu kendisi hazırlar: macOS’te Node 26, Linux’ta ise Node 24 LTS hazırlanır. pnpm yalnızca OpenClaw kaynak koddan derlenirken gereklidir.

Bilgisayarınızda daha eski bir Node sürümü kuruluysa hemen kaldırmanız gerekmez. 2026-10-09 tarihindeki test sırasında bilgisayarın sistem Node sürümü 24.2.0 idi ve gerekli 24.16 sürümünden düşüktü. Etkileşimsiz kurulum betiği Node 24.21.0 sürümünü kendisi hazırladı.

Pencere istiyorsanız

Masaüstü yardımcısı

• Windows'ta Hub kurulum paketi
• macOS'ta GitHub üzerindeki DMG
• İlk kullanımda yerel Gateway kurulabilir

Resmi öneri

Kurulum betiği

• macOS Linux WSL2
• Windows'ta PowerShell kullanın
• --no-onboard eklenebilir

Node zaten varsa

Paket yöneticisi

• npm, pnpm veya bun
• Ardından onboard çalıştırın
• Node sürümü için kurulum sayfasına bakın

Kurulum ve ilk çalıştırma

Pencereli masaüstü yardımcı uygulamasını kurabilir veya doğrudan terminal üzerinden kurulum yapabilirsiniz. Gateway, mesajları alan, modeli çağıran ve sonuçları geri gönderen yerel hizmettir. Masaüstü yardımcı uygulamasını ilk kez açarken Gateway’i de hazırlayabilirsiniz.

Pencere kullanmak istiyorsanız

• Windows: OpenClawCompanion-Setup-x64.exe veya OpenClawCompanion-Setup-arm64.exe dosyasını indirip çalıştırın. Kurulum paketi imzalıdır ve ayarlar, sistem tepsisi durumu, sohbet ve node modunu içerir.
• macOS: OpenClaw’ın GitHub releases sayfasından OpenClaw için .dmg dosyasını indirin. Öncelikle dmg kullanın; .zip de kullanılabilir. Kurulumdan sonra OpenClaw.app uygulamasını açın. Bu sürümde macOS dosyası yoksa macOS uygulama sayfasındaki yöntemi izleyin.

İlk açılışta OpenClaw’ın bu bilgisayarda Gateway’i hazırlamasına izin verebilir veya mevcut bir uzak Gateway’e bağlanabilirsiniz.

Terminal üzerinden kurulum

macOS, Linux ve WSL2 için:

curl -fsSL https://openclaw.ai/install.sh | bash

Windows PowerShell için:

iwr -useb https://openclaw.ai/install.ps1 | iex

Betik mevcut sistemi algılar, gerektiğinde Node’u kurar, ardından OpenClaw’ı yükleyip ilk kurulum sihirbazını başlatır. Sihirbaz ilk yapılandırmayı tamamlamanıza yardımcı olur.

Şimdilik kurulum sihirbazını başlatmak istemiyorsanız macOS, Linux ve WSL2 üzerinde bunun yerine şunu kullanın:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

Windows’ta resmî -NoOnboard seçeneğini kullanın:

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

Node’u kendiniz yönetiyorsanız npm, pnpm veya bun da kullanabilirsiniz. npm 12 ile npm 11.16 ve üzeri sürümlerde şunları çalıştırın:

npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

npm 11.15 ve daha eski sürümlerde --allow-scripts=openclaw kaldırılmalıdır. pnpm kullanırken --allow-build=openclaw eklenmelidir. Ayrıntılı farklılıklar için kurulum sayfasını esas alın.

Kurulum tamamlandıktan sonra aşağıdaki üç komutu sırayla çalıştırın:

openclaw --version
openclaw doctor
openclaw gateway status

openclaw --version sürümü gösterir, openclaw doctor yaygın ortam sorunlarını denetler ve openclaw gateway status Gateway’in çalışıp çalışmadığını gösterir. Temel kurulumun tamamlanmış sayılması için üç komutun da normal çıktı vermesi gerekir.

Terminal openclaw komutunu bulamadığını bildiriyorsa bunun nedeni genellikle npm’in global bin dizininin PATH’e eklenmemiş olmasıdır. PATH, terminalin programları aradığı konumların listesidir. node -v, npm prefix -g ve echo "$PATH" komutlarının sonuçlarını karşılaştırın, ilgili bin dizinini PATH’e ekleyin ve ardından terminali yeniden açın.

~/.openclaw içinde hâlihazırda kullanılan bir yapılandırma varsa varsayılan kurulum betiği bu dizini kullanır. Ayrı bir kurulum yapmak ve mevcut yapılandırmayı değiştirmemek için etkileşimsiz betiği yeni bir dizin belirterek çalıştırabilirsiniz:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix "$HOME/openclaw-omniproxy" --no-onboard

--no-onboard, bu betiğin varsayılan davranışıdır. Bu komut 2026-10-09 tarihinde OpenClaw 2026.9.9 sürümünü kurdu. Kurulum tamamlandıktan sonra bu dizinin bin klasöründeki openclaw programını çalıştırmanız gerekir.

OmniProxy bağlantı bilgilerini alma

Önce OmniProxy’nin çalıştığını doğrulayın, ardından model listesini açıp aşağıdaki üç bilgiyi hazırlayın:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: Geçerli OmniProxy model listesinden tamamını kopyalayın

baseUrl, OpenClaw’ın model isteklerini gönderdiği adrestir ve /v1 ile bitmelidir. OmniProxy bağlantısında api için openai-completions kullanın. Yalnızca ilgili model gerçekten /v1/responses üzerinden çalışıyorsa bunu openai-responses olarak değiştirin.

Model ID, modelin listedeki tam tanımlayıcısıdır. Listede göründüğü biçimi aynen kopyalayın; eğik çizgiler varsa onları da koruyun. Aşağıdaki iki ad yalnızca 2026-10-09 tarihindeki sağlayıcı belgelerinde yer alan karşılaştırma örnekleridir. Listede yoklarsa kullanmayın: claude-sonnet-5-5, gpt-6-luna.

Gateway anahtarı denetlemese bile apiKey alanına bir değer girilmelidir. Yalnızca bu bilgisayarda kullanılacak bir yer tutucu karakter dizisi kullanabilirsiniz. Gerçek anahtarı depoya göndermeyin.

Araç yapılandırmasını girme

Provider, OpenClaw’ın model hizmetini bulmak için kullandığı bağlantı ayarları grubu olarak düşünülebilir. Burada Provider adı omniproxy olarak belirlenir.

Terminalde aşağıdaki komutu çalıştırın; adresi, anahtarı ve iki model ID’sini kendi bilgilerinizle değiştirin:

openclaw config set models.providers.omniproxy '{"baseUrl":"https://your-omniproxy-origin.example/v1","apiKey":"<YOUR_OMNIPROXY_API_KEY>","api":"openai-completions","models":[{"id":"claude-sonnet-5-5","name":"Claude Sonnet 5.5"},{"id":"gpt-6-luna","name":"GPT-6 Luna"}]}' --strict-json --merge

Bu komut Provider’ı ve model listesini yapılandırmaya yazar. Komut başarıyla tamamlandıktan sonra Gateway’i yeniden başlatmanız gerekmez.

Ardından varsayılan modeli belirtin. Model başvurusu omniproxy/ ile model ID’sinden oluşur. ID’de bulunan tüm eğik çizgileri koruyun. Model listesindeki ID aşağıdaki kısa addan daha uzunsa listedeki tam değeri kullanın:

openclaw config set agents.defaults.model.primary '"omniproxy/claude-sonnet-5-5"' --strict-json

reasoning, input, cost, contextWindow ve maxTokens alanlarını belirtmek zorunda değilsiniz. Bu alanlar girilmezse metin modeli varsayılan şekilde işlenir.

Aynı ayarlar doğrudan yapılandırma dosyasına da yazılabilir. Ana yapılandırmadaki Provider, models.providers altında bulunur. Her agent’ın kendi models.json dosyası da olabilir. agent, görevleri gerçekten alan ve modeli çağıran asistan örneğidir. Dosya, ~/.openclaw/agents/ altında ilgili agent dizinindeki agent/models.json konumundadır.

Bu models.json dosyasında boş olmayan bir baseUrl varsa ana yapılandırmadaki adresin yerine kullanılır.

Kurulumu denetleme

Üç komut

• openclaw --version
• openclaw doctor
• gateway status

Yapılandırma

models.providers

• baseUrl /v1 ile bitmeli
• api için completions kullanın
• Modelde en az id bulunmalı

Seçim

provider/model

• primary için bu başvuruyu kullanın
• Anahtar için tercihen ortam değişkeni kullanın
• Ağ geçidi listesini esas alın

Gerçek bir görevi doğrulama

Normal bir proje dizinine girin ve çok kısa bir mesaj gönderin. Komuttaki model başvurusunu kendi tam Model ID’nizle değiştirin:

openclaw agent --local --model omniproxy/claude-sonnet-5-5 --timeout 300 --message "Tek kelimeyle yanıt ver."

--local, bu agent görevinin yerel bilgisayarda çalıştırılacağını belirtir. --model, bu çalıştırmada kullanılacak modeli seçer. --timeout 300 ise en fazla 300 saniye bekleneceği anlamına gelir.

Modelin yanıtı terminalde gerçekten görünmelidir. OpenClaw 2026.9.9, 2026-10-09 tarihinde bu komut kullanılarak yanıt verdi. İlk çağrı bir veya iki dakika sürebilir.

Özgün hata metni Request timed out before a response was generated görünürse önce --timeout değerini yükseltin ve mesajı yeniden gönderin. Bu genellikle bekleme süresinin yetersiz olduğunu gösterir; adresin mutlaka yanlış olduğu anlamına gelmez.

Kısa yanıt başarıyla alındıktan sonra asistanın belirttiğiniz yerel bir dosyayı okumasını isteyin. Ardından OmniProxy’nin çağrı kayıtlarını açarak kayıttaki kaynağı ve model ID’sini doğrulayın. Yalnızca sürüm numarasının veya doctor çıktısının görünmesi, model bağlantısının yapılandırmasının tamamlandığını göstermez.

Kurulum

Komut yanıt veriyor

• Sürüm numarası görüntülenebiliyor
• doctor engelleyici bir sorun göstermiyor
• Gateway durumu okunabiliyor

Görev

Küçük bir görev yaptı

• Örneğin yerel bir dosyayı okudu
• Yanıt bir hata değil
• Model başvurusu doğru yazılmış

Kayıtlar

Ağ geçidinde görünüyor

• Kaynak OpenClaw
• Model ID eşleşiyor
• Anahtar depoya girmedi

Yaygın hatalar

• openclaw bulunamıyor: npm’in global bin dizinini PATH’e ekleyin ve terminali yeniden açın. Belirli bir dizine kurulum yaptıysanız o dizinin bin klasöründeki programı çalıştırın.
• node -v değeri 24.16’dan düşük: Önce eski sürümü kaldırmanız gerekmez. Kurulum betiğinin hazırladığı Node sürümünü kontrol edin veya kurulum sayfasına göre 24.16+ ya da 26.1+ kullanın. Node 26 önerilir.
• Model görünmüyor: Model, models.providers altındaki models dizisinde yer almalı ve en azından aynı id değerine sahip olmalıdır. Yalnızca agents.defaults.models yazmak yeni bir modeli ayrıca kaydetmez.
• 400 yanıtı geliyor ve developer rolünden söz ediliyor: Adresin ana makinesi api.openai.com değilse varsayılan ayarı koruyun ve supportsDeveloperRole değerini true yapmayın. true olarak ayarlansa bile üzerine yazılır.
• Çok hızlı zaman aşımına uğruyor: Önce adresi değiştirmeden --timeout değerini 300 saniyenin üzerine çıkarın.
• gpt-6-luna seçildi ancak araç çağrısı başarısız oluyor: Bu model Chat Completions’ı destekler. Chat Completions içinde işlev çağrısı yalnızca reasoning_effort değeri none olduğunda desteklenir. Listedeki ID bundan farklıysa listeyi esas alın.
• Adrese bağlanılamıyor: OmniProxy’nin çalıştığını, baseUrl değerinin /v1 ile bittiğini ve yapılandırmaya yazılan adresin erişilebilir olduğunu doğrulayın. Diğer özel ağ adresleri için ayrıca erişim izni verilmelidir.
• Yapılandırmaya rağmen başka bir adrese gidiliyor: İlgili agent’ın models.json dosyasında başka bir baseUrl bulunup bulunmadığını kontrol edin.

Resmî başvurular

Kurulum adımları için OpenClaw install sayfasına bakın. Özel Provider ayarları için Custom providers ve yapılandırma alanları sayfalarını kullanın. Örnekte kullanılan model ID’lerini Claude model genel bakışı ve GPT-6 Luna sayfalarıyla karşılaştırabilirsiniz.

Tüm yer tutucuları kendi OmniProxy yapılandırmanızdaki değerlerle değiştirin. Gerçek bir anahtar asla paylaşmayın.

Kaydedilmiş bir sonuç veya yalnızca HTTP 200, tam Aracı uyumluluğunu kanıtlamaz. OmniProxy'nin çağrı kaydındaki kaynağı ve modeli kontrol edin.

Resmi kaynaklar · OpenClaw ↗