ACP

Bir OpenClaw Gateway ile iletişim kuran Agent Client Protocol (ACP) köprüsünü çalıştırın.

openclaw acp, IDE'ler için stdio üzerinden ACP iletişimi kurar ve istemleri WebSocket üzerinden Gateway'e iletirken ACP oturumlarını Gateway oturum anahtarlarıyla eşlenmiş hâlde tutar. Tam bir ACP yerel düzenleyici çalışma zamanı değil, Gateway destekli bir ACP köprüsüdür: oturum yönlendirmeye, istem teslimine ve akış güncellemelerine odaklanır.

Harici bir MCP istemcisinin ACP yürütme ortamı oturumu barındırmak yerine doğrudan OpenClaw kanal konuşmalarıyla iletişim kurmasını istiyorsanız openclaw mcp serve kullanın.

Bu ne değildir?

openclaw acp, OpenClaw'ın bir ACP sunucusu olarak çalıştığı anlamına gelir: Bir IDE veya ACP istemcisi OpenClaw'a bağlanır ve OpenClaw bu işi bir Gateway oturumuna iletir.

Bu, OpenClaw'ın Codex veya Claude Code gibi harici bir yürütme ortamını acpx üzerinden çalıştırdığı ACP Aracılarından farklıdır.

Kısa kural:

• düzenleyici/istemci, OpenClaw ile ACP üzerinden iletişim kurmak istiyorsa: openclaw acp kullanın
• OpenClaw, Codex/Claude/Gemini'yi bir ACP yürütme ortamı olarak başlatacaksa: /acp spawn ve ACP Aracılarını kullanın

Uyumluluk matrisi

Bilinen sınırlamalar

• loadSession, tam ACP olay defteri geçmişini yalnızca köprü tarafından oluşturulan oturumlar için yeniden oynatır. Daha eski veya deftersiz oturumlar transkript geri dönüşünü kullanır ve geçmiş araç çağrılarını ya da sistem bildirimlerini yeniden oluşturmaz.
• Birden çok ACP istemcisi aynı Gateway oturum anahtarını paylaşırsa olay ve iptal yönlendirmesi, istemci başına kesin olarak yalıtılmak yerine azami gayretle gerçekleştirilir. Temiz, düzenleyiciye yerel turlara ihtiyacınız varsa varsayılan yalıtılmış acp-bridge:<uuid> oturumlarını tercih edin.
• Gateway durdurma durumları ACP durdurma nedenlerine çevrilir, ancak bu eşleme tam ACP yerel çalışma zamanından daha az ifade gücüne sahiptir.
• Oturum denetimleri, Gateway ayarlarının odaklanmış bir alt kümesini sunar: düşünme düzeyi, araç ayrıntı düzeyi, akıl yürütme, kullanım ayrıntısı ve yükseltilmiş eylemler. Model seçimi ve yürütme ana makinesi denetimleri ACP yapılandırma seçenekleri olarak sunulmaz.
• session_info_update ve usage_update, canlı ACP yerel çalışma zamanı muhasebesinden değil, Gateway oturumu anlık görüntülerinden türetilir. Kullanım yaklaşık değerdir, maliyet verisi içermez ve yalnızca Gateway toplam belirteç verilerini güncel olarak işaretlediğinde yayımlanır.
• Araç izleme verileri azami gayret esasına dayanır: Köprü, bilinen araç bağımsız değişkenlerinde/sonuçlarında görünen dosya yollarını sunar, ancak ACP terminalleri veya yapılandırılmış dosya farkları yayımlamaz.
• Yürütme onayı aktarımı etkin ACP istem turuyla sınırlıdır; diğer Gateway oturumlarından gelen onaylar yok sayılır.

Kullanım

openclaw acp # Uzak Gatewayopenclaw acp --url wss://gateway-host:18789 --token <token> # Uzak Gateway (dosyadan belirteç)openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token # Mevcut bir oturum anahtarına bağlanopenclaw acp --session agent:main:main # Etikete göre bağlan (önceden mevcut olmalıdır)openclaw acp --session-label "support inbox" # İlk istemden önce oturum anahtarını sıfırlaopenclaw acp --session agent:main:main --reset-session

ACP istemcisi (hata ayıklama)

Köprünün temel doğrulamasını IDE olmadan yapmak için yerleşik ACP istemcisini kullanın. ACP köprüsünü başlatır ve etkileşimli olarak istemler yazmanıza olanak tanır.

openclaw acp client # Başlatılan köprüyü uzak bir Gateway'e yönlendiropenclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token # Sunucu komutunu geçersiz kıl (varsayılan: openclaw)openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

İzin modeli (istemci hata ayıklama modu):

• Otomatik onay, izin listesine dayalıdır ve yalnızca güvenilir çekirdek araç kimliklerine uygulanır.
• read otomatik onayı geçerli çalışma diziniyle (--cwd ayarlandığında) sınırlıdır.
• ACP yalnızca dar salt okunur sınıfları otomatik onaylar: etkin cwd altındaki kapsamlı read çağrıları ve salt okunur arama araçları (search, web_search, memory_search). Bilinmeyen/çekirdek dışı araçlar, kapsam dışı okumalar, yürütme yetenekli araçlar, denetim düzlemi araçları, değişiklik yapan araçlar ve etkileşimli akışlar her zaman açık istem onayı gerektirir.
• Sunucu tarafından sağlanan toolCall.kind, yetkilendirme kaynağı değil, güvenilmeyen meta veri olarak değerlendirilir.
• Bu ACP köprüsü ilkesi, ACPX yürütme ortamı izinlerinden ayrıdır. OpenClaw'ı acpx arka ucu üzerinden çalıştırırsanız plugins.entries.acpx.config.permissionMode=approve-all, söz konusu yürütme ortamı oturumu için acil durum "yolo" anahtarıdır.

Protokol duman testi

Protokol düzeyinde hata ayıklama için yalıtılmış durumla bir Gateway başlatın ve ACP JSON-RPC istemcisiyle stdio üzerinden openclaw acp çalıştırın. Mutlak bir cwd ile initialize, session/new, session/list, session/resume, session/close, yinelenen kapatma ve eksik sürdürme durumlarını kapsayın.

Kanıt; duyurulan yaşam döngüsü yeteneklerini, Gateway destekli bir oturum satırını, güncelleme bildirimlerini ve Gateway sessions.list günlüğünü içermelidir:

{  "initialize": {    "protocolVersion": 1,    "agentCapabilities": {      "sessionCapabilities": {        "list": {},        "resume": {},        "close": {}      }    }  },  "listSessions": {    "sessions": [      {        "sessionId": "agent:main:acp-smoke",        "cwd": "/path/to/workspace",        "_meta": {          "sessionKey": "agent:main:acp-smoke",          "kind": "direct"        }      }    ],    "nextCursor": null  },  "notifications": ["session_info_update", "available_commands_update", "usage_update"],  "gatewayLogTail": ["[gateway] ready", "[ws] ⇄ res ✓ sessions.list 305ms"]}

Tek ACP kanıtı olarak openclaw gateway call sessions.list kullanmaktan kaçının. Bu CLI yolu, yeni belirteçli bir operatör kapsamı yükseltmesi isteyebilir; ACP köprüsünün doğruluğu, ACP stdio çerçeveleri ve Gateway sessions.list günlüğüyle kanıtlanır.

Nasıl kullanılır?

Bir IDE (veya başka bir istemci) Agent Client Protocol kullanıyorsa ve bu istemcinin bir OpenClaw Gateway oturumunu yönetmesini istiyorsanız ACP kullanın.

1. Gateway'in çalıştığından emin olun (yerel veya uzak).
2. Gateway hedefini yapılandırın (yapılandırma veya bayraklar).
3. IDE'nizi stdio üzerinden openclaw acp çalıştıracak şekilde ayarlayın.

Örnek yapılandırma (kalıcı):

openclaw config set gateway.remote.url wss://gateway-host:18789openclaw config set gateway.remote.token <token>

Doğrudan çalıştırma örneği (yapılandırmaya yazmaz):

openclaw acp --url wss://gateway-host:18789 --token <token># yerel işlem güvenliği için tercih ediliropenclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

Aracıları seçme

ACP, aracıları doğrudan seçmez. Gateway oturum anahtarına göre yönlendirme yapar. Belirli bir aracıyı hedeflemek için aracı kapsamlı oturum anahtarlarını kullanın:

openclaw acp --session agent:main:mainopenclaw acp --session agent:design:mainopenclaw acp --session agent:qa:bug-123

Her ACP oturumu tek bir Gateway oturum anahtarıyla eşlenir. Bir aracının birçok oturumu olabilir; anahtarı veya etiketi geçersiz kılmadığınız sürece ACP, varsayılan olarak yalıtılmış bir acp-bridge:<uuid> oturumu kullanır.

Oturum başına mcpServers, köprü modunda desteklenmez. Bir ACP istemcisi bunları newSession veya loadSession sırasında gönderirse köprü, sessizce yok saymak yerine açık bir hata döndürür.

ACPX destekli oturumların OpenClaw Plugin araçlarını veya cron gibi seçili yerleşik araçları görmesini istiyorsanız oturum başına mcpServers iletmeye çalışmak yerine Gateway tarafındaki ACPX MCP köprülerini etkinleştirin. Bkz. ACP Aracıları ve OpenClaw araçları MCP köprüsü.

acpx üzerinden kullanım (Codex, Claude ve diğer ACP istemcileri)

Codex veya Claude Code gibi bir kodlama aracısının ACP üzerinden OpenClaw botunuzla iletişim kurmasını istiyorsanız yerleşik openclaw hedefiyle birlikte acpx kullanın.

Tipik akış:

1. Gateway'i çalıştırın ve ACP köprüsünün ona erişebildiğinden emin olun.
2. acpx openclaw öğesini openclaw acp hedefine yönlendirin.
3. Kodlama aracısının kullanmasını istediğiniz OpenClaw oturum anahtarını hedefleyin.

Örnekler:

# Varsayılan OpenClaw ACP oturumunuza tek seferlik istekacpx openclaw exec "Etkin OpenClaw oturum durumunu özetle." # Sonraki etkileşimler için kalıcı, adlandırılmış oturumacpx openclaw sessions ensure --name codex-bridgeacpx openclaw -s codex-bridge --cwd /path/to/repo \  "OpenClaw çalışma aracımdan bu depoyla ilgili yakın tarihli bağlamı iste."

acpx openclaw öğesinin her seferinde belirli bir Gateway'i ve oturum anahtarını hedeflemesini istiyorsanız ~/.acpx/config.json içindeki openclaw aracı komutunu geçersiz kılın:

{  "agents": {    "openclaw": {      "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"    }  }}

Depoya yerel bir OpenClaw çalışma kopyası için ACP akışının temiz kalması amacıyla geliştirme çalıştırıcısı yerine doğrudan CLI giriş noktasını kullanın:

env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...

Bu, Codex, Claude Code veya ACP destekli başka bir istemcinin terminali taramadan bir OpenClaw aracısından bağlamsal bilgi almasını sağlamanın en kolay yoludur.

Zed düzenleyicisini ayarlama

~/.config/zed/settings.json içine özel bir ACP aracısı ekleyin (veya Zed'in Settings arayüzünü kullanın):

{  "agent_servers": {    "OpenClaw ACP": {      "type": "custom",      "command": "openclaw",      "args": ["acp"],      "env": {}    }  }}

Belirli bir Gateway'i veya aracıyı hedeflemek için:

{  "agent_servers": {    "OpenClaw ACP": {      "type": "custom",      "command": "openclaw",      "args": [        "acp",        "--url",        "wss://gateway-host:18789",        "--token",        "<token>",        "--session",        "agent:design:main"      ],      "env": {}    }  }}

Zed'de Agent panelini açın ve bir ileti dizisi başlatmak için "OpenClaw ACP" öğesini seçin.

Oturum eşleme

Varsayılan olarak ACP köprü oturumları, acp-bridge: ön ekine sahip yalıtılmış bir Gateway oturum anahtarı alır. Bu normal model köprü oturumları sentetik ve geçicidir: eski girdi temizliğine tabidir ve korunan insan konuşması yüzeyleri olarak değerlendirilmez. Bilinen bir oturumu yeniden kullanmak için bir oturum anahtarı veya etiketi iletin:

• --session <key>: belirli bir Gateway oturum anahtarı kullanır.
• --session-label <label>: mevcut bir oturumu etikete göre çözümler.
• --reset-session: bu anahtar için yeni bir oturum kimliği oluşturur (aynı anahtar, yeni döküm).

ACP istemciniz meta verileri destekliyorsa oturum başına geçersiz kılabilirsiniz:

{  "_meta": {    "sessionKey": "agent:main:main",    "sessionLabel": "support inbox",    "resetSession": true  }}

Oturum anahtarları hakkında daha fazla bilgi için bkz. /concepts/session.

Seçenekler

• --url <url>: Gateway WebSocket URL'si (yapılandırılmışsa varsayılan değer: gateway.remote.url).
• --token <token>: Gateway kimlik doğrulama belirteci.
• --token-file <path>: Gateway kimlik doğrulama belirtecini dosyadan okur.
• --password <password>: Gateway kimlik doğrulama parolası.
• --password-file <path>: Gateway kimlik doğrulama parolasını dosyadan okur.
• --session <key>: varsayılan oturum anahtarı.
• --session-label <label>: çözümlenecek varsayılan oturum etiketi.
• --require-existing: oturum anahtarı/etiketi yoksa başarısız olur.
• --reset-session: ilk kullanımdan önce oturum anahtarını sıfırlar.
• --no-prefix-cwd: istemlerin başına çalışma dizinini eklemez.
• --provenance <off|meta|meta+receipt>: ACP kaynak meta verilerini veya alındı bilgilerini içerir.
• --verbose, -v: stderr'e ayrıntılı günlük kaydı yapar.

Güvenlik notu:

• --token ve --password, bazı sistemlerde yerel işlem listelerinde görülebilir. --token-file/--password-file veya ortam değişkenlerini (OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD) tercih edin.
• Gateway kimlik doğrulama çözümlemesi, diğer Gateway istemcilerinin kullandığı ortak sözleşmeyi izler:
  • yerel mod: ortam (OPENCLAW_GATEWAY_*), ardından gateway.auth.*; yalnızca gateway.auth.* ayarlanmamışsa gateway.remote.* değerine geri döner (yapılandırılmış ancak çözümlenemeyen yerel SecretRef, sessizce geri dönmek yerine güvenli biçimde başarısız olur)
  • uzak mod: uzak öncelik kurallarına göre ortam/yapılandırma geri dönüşüyle gateway.remote.*
  • --url, geçersiz kılmaya karşı güvenlidir ve örtük yapılandırma/ortam kimlik bilgilerini yeniden kullanmaz; açıkça --token/--password (veya dosya çeşitlerini) iletin

acp client seçenekleri

• --cwd <dir>: ACP oturumunun çalışma dizini.
• --server <command>: ACP sunucu komutu (varsayılan: openclaw).
• --server-args <args...>: ACP sunucusuna iletilen ek bağımsız değişkenler.
• --server-verbose: ACP sunucusunda ayrıntılı günlük kaydını etkinleştirir.
• --verbose, -v: ayrıntılı istemci günlük kaydı.
• openclaw acp client, başlatılan köprü işleminde OPENCLAW_SHELL=acp-client değerini ayarlar; bu değer bağlama özgü kabuk/profil kuralları için kullanılabilir.

İlgili

• CLI başvurusu
• ACP aracıları