ACP aracıları — kurulum

Genel bakış, operatör çalışma kılavuzu ve kavramlar için ACP agent'ları bölümüne bakın.

Bu sayfa, acpx harness yapılandırmasını, MCP köprüleri için plugin kurulumunu ve izin yapılandırmasını kapsar.

Bu sayfayı yalnızca ACP/acpx rotasını ayarlarken kullanın. Yerel Codex app-server çalışma zamanı yapılandırması için Codex harness sayfasını kullanın. OpenAI API anahtarları veya Codex OAuth model sağlayıcısı yapılandırması için OpenAI sayfasını kullanın.

Codex'in iki OpenClaw rotası vardır:

ACP/acpx davranışına açıkça ihtiyaç duymadığınız sürece yerel rotayı tercih edin.

acpx harness desteği (güncel)

Yerleşik acpx harness takma adları (sabitlenmiş acpx bağımlılığından):

factory-droid ve factorydroid de yerleşik droid bağdaştırıcısına çözümlenir.

OpenClaw acpx arka ucunu kullandığında, acpx yapılandırmanız özel agent takma adları tanımlamıyorsa agentId için bu değerleri tercih edin. Yerel Cursor kurulumunuz ACP'yi hâlâ agent acp olarak sunuyorsa yerleşik varsayılanı değiştirmek yerine acpx yapılandırmanızdaki cursor agent komutunu geçersiz kılın.

Doğrudan acpx CLI kullanımı, --agent <command> aracılığıyla rastgele bağdaştırıcıları da hedefleyebilir; ancak bu ham kaçış yolu bir acpx CLI özelliğidir (normal OpenClaw agentId yolu değildir).

Model denetimi, bağdaştırıcı yeteneğine bağlıdır. Codex ACP model referansları başlatılmadan önce OpenClaw tarafından normalleştirilir. Diğer harness'ler ACP models ile session/set_model desteğine ihtiyaç duyar; bir harness ne bu ACP yeteneğini ne de kendi başlangıç model bayrağını sunuyorsa OpenClaw/acpx model seçimini zorlayamaz.

Gerekli yapılandırma

Temel ACP yapılandırması:

{  acp: {    enabled: true,    // İsteğe bağlı. Varsayılan değer true'dur; /acp denetimlerini korurken ACP yönlendirmesini duraklatmak için false olarak ayarlayın.    dispatch: { enabled: true },    backend: "acpx",    defaultAgent: "codex",    allowedAgents: [      "claude",      "codex",      "copilot",      "cursor",      "droid",      "gemini",      "iflow",      "kilocode",      "kimi",      "kiro",      "openclaw",      "opencode",      "qwen",    ],    maxConcurrentSessions: 8,    stream: {      // Varsayılanlar coalesceIdleMs: 350, maxChunkChars: 1800 değerleridir; burada açıkça gösterilmiştir.      coalesceIdleMs: 350,      maxChunkChars: 1800,    },    runtime: {      ttlMinutes: 120,    },  },}

İş parçacığı bağlama yapılandırması, kanal bağdaştırıcısına özeldir. Discord örneği:

{  session: {    threadBindings: {      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },  },  channels: {    discord: {      threadBindings: {        enabled: true,        // Varsayılan değer zaten true'dur; burada açıkça gösterilmiştir.        spawnSessions: true,      },    },  },}

İş parçacığına bağlı ACP oluşturma çalışmıyorsa önce bağdaştırıcı özellik bayrağını doğrulayın:

• Discord: channels.discord.threadBindings.spawnSessions=true

Geçerli konuşma bağlamaları, alt iş parçacığı oluşturulmasını gerektirmez. Etkin bir konuşma bağlamı ve ACP konuşma bağlamalarını sunan bir kanal bağdaştırıcısı gerektirir.

Yapılandırma Referansı bölümüne bakın.

acpx arka ucu için plugin kurulumu

Paketlenmiş kurulumlar, ACP için resmî @openclaw/acpx çalışma zamanı plugin'ini kullanır. ACP harness oturumlarını kullanmadan önce bunu kurun ve etkinleştirin:

openclaw plugins install @openclaw/acpxopenclaw config set plugins.entries.acpx.enabled true

Kaynak kod teslim almaları da pnpm install sonrasında yerel çalışma alanı plugin'ini kullanabilir.

Şununla başlayın:

/acp doctor

acpx özelliğini devre dışı bıraktıysanız, plugins.allow / plugins.deny aracılığıyla reddettiyseniz veya paketlenmiş plugin'e geri dönmek istiyorsanız açık paket yolunu kullanın:

openclaw plugins install @openclaw/acpxopenclaw config set plugins.entries.acpx.enabled true

Geliştirme sırasında yerel çalışma alanı kurulumu:

openclaw plugins install ./path/to/local/acpx-plugin

Ardından arka uç durumunu doğrulayın:

/acp doctor

acpx çalışma zamanı başlangıç yoklaması

acpx plugin'i ACP çalışma zamanını doğrudan gömer (yapılandırılacak ayrı bir acpx ikili dosyası veya sürümü yoktur). Varsayılan olarak gömülü arka ucu Gateway başlatılırken kaydeder ve gateway ready sinyalinden önce bir başlangıç yoklamasını bekler. OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 veya OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1 değerlerini yalnızca başlangıç yoklamasını bilerek devre dışı tutan betikler veya ortamlar için ayarlayın. Açık bir isteğe bağlı yoklama için /acp doctor komutunu çalıştırın.

Bir yolun veya bayrak değerinin tek bir argv belirteci olarak kalması gerektiğinde, tek bir ACP agent komutunu yapılandırılmış bağımsız değişkenlerle geçersiz kılın:

{  "plugins": {    "entries": {      "acpx": {        "enabled": true,        "config": {          "agents": {            "claude": {              "command": "node",              "args": ["/path/to/custom adapter.mjs", "--verbose"]            }          }        }      }    }  }}

• agents.<id>.command, bu ACP agent'ının yürütülebilir dosyası veya mevcut komut dizesidir.
• agents.<id>.args isteğe bağlıdır. OpenClaw her dizi öğesini geçerli acpx komut dizesi kayıt defteri üzerinden geçirmeden önce kabuk için tırnak içine alır.

Plugin'ler bölümüne bakın.

Otomatik bağdaştırıcı indirme

acpx, ACP bağdaştırıcılarını (örneğin Claude ve Codex ACP köprülerini) ilk kullanımda npx aracılığıyla otomatik olarak indirir. Bağdaştırıcı paketlerini elle kurmanız gerekmez ve OpenClaw'ın kendisi için ayrı bir kurulum sonrası adımı yoktur. Bir bağdaştırıcı indirme veya oluşturma işlemi başarısız olursa /acp doctor hatayı bildirir.

Plugin araçları MCP köprüsü

Varsayılan olarak ACPX oturumları, OpenClaw plugin'leri tarafından kaydedilen araçları ACP harness'ine sunmaz.

Codex veya Claude Code gibi ACP agent'larının bellek geri çağırma/depolama gibi kurulu OpenClaw plugin araçlarını çağırmasını istiyorsanız özel köprüyü etkinleştirin:

openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true

Bunun yaptıkları:

• ACPX oturum başlangıcına openclaw-plugin-tools adlı yerleşik bir MCP sunucusu ekler.
• Kurulu ve etkin OpenClaw plugin'leri tarafından zaten kaydedilmiş plugin araçlarını sunar.
• Etkin ACP oturum kimliğini plugin araç fabrikalarına iletir; böylece agent kapsamındaki araçlar ilgili agent'ın ad alanında kalır.
• Özelliği açıkça etkinleştirilebilir ve varsayılan olarak kapalı tutar.

Güvenlik ve güven notları:

• Bu, ACP harness araç yüzeyini genişletir.
• ACP agent'ları yalnızca gateway'de zaten etkin olan plugin araçlarına erişebilir.
• Bunu, söz konusu plugin'lerin OpenClaw'ın kendisinde yürütülmesine izin vermekle aynı güven sınırı olarak değerlendirin.
• Etkinleştirmeden önce kurulu plugin'leri inceleyin.

Özel mcpServers daha önce olduğu gibi çalışmaya devam eder. Yerleşik plugin araçları köprüsü, genel MCP sunucusu yapılandırmasının yerine geçen bir özellik değil, ek ve isteğe bağlı bir kolaylıktır.

OpenClaw araçları MCP köprüsü

Varsayılan olarak ACPX oturumları, yerleşik OpenClaw araçlarını da MCP üzerinden sunmaz. Bir ACP agent'ının cron gibi seçilmiş yerleşik araçlara ihtiyacı olduğunda ayrı temel araçlar köprüsünü etkinleştirin:

openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true

Bunun yaptıkları:

• ACPX oturum başlangıcına openclaw-tools adlı yerleşik bir MCP sunucusu ekler.
• Seçilmiş yerleşik OpenClaw araçlarını sunar. İlk sunucu cron aracını sunar.
• Temel araçların sunulmasını açıkça etkinleştirilebilir ve varsayılan olarak kapalı tutar.

Çalışma zamanı işlemi zaman aşımı yapılandırması

acpx plugin'i, gömülü çalışma zamanı başlangıç ve denetim işlemlerine varsayılan olarak 120 saniye tanır. Bu, Gemini CLI gibi daha yavaş harness'lere ACP başlangıç ve ilklendirme işlemlerini tamamlamaları için yeterli süre verir. Ana makineniz farklı bir işlem sınırına ihtiyaç duyuyorsa bu değeri geçersiz kılın:

openclaw config set plugins.entries.acpx.config.timeoutSeconds 180

Çalışma zamanı turları, /acp timeout dâhil olmak üzere OpenClaw agent/çalıştırma zaman aşımlarını kullanır. sessions_spawn çağrı başına zaman aşımı geçersiz kılmalarını kabul etmez; operatör yolu agents.defaults.subagents.runTimeoutSeconds şeklindedir. timeoutSeconds değerini değiştirdikten sonra gateway'i yeniden başlatın.

Durum yoklaması agent yapılandırması

/acp doctor veya başlangıç yoklaması arka ucu denetlediğinde, paketle birlikte gelen acpx plugin'i bir harness agent'ını yoklar. acp.allowedAgents ayarlanmışsa varsayılan olarak izin verilen ilk agent'ı kullanır; aksi takdirde varsayılan değer codex olur. Dağıtımınız durum denetimleri için farklı bir ACP agent'ına ihtiyaç duyuyorsa yoklama agent'ını açıkça ayarlayın:

openclaw config set plugins.entries.acpx.config.probeAgent claude

Bu değeri değiştirdikten sonra gateway'i yeniden başlatın.

İzin yapılandırması

ACP oturumları etkileşimsiz çalışır — dosya yazma ve kabuk yürütme izin istemlerini onaylamak veya reddetmek için TTY yoktur. acpx Plugin'i, izinlerin nasıl işleneceğini denetleyen iki yapılandırma anahtarı sağlar:

Bu ACPX çalıştırma düzeneği izinleri, OpenClaw yürütme onaylarından ve Claude CLI --permission-mode bypassPermissions gibi CLI arka ucu sağlayıcılarının atlama bayraklarından ayrıdır. ACPX approve-all, ACP oturumları için çalıştırma düzeneği düzeyindeki acil durum anahtarıdır.

OpenClaw tools.exec.mode, Codex Guardian onayları ve ACPX çalıştırma düzeneği izinleri arasındaki daha kapsamlı karşılaştırma için İzin modları bölümüne bakın.

permissionMode

Çalıştırma düzeneği aracısının istem göstermeden hangi işlemleri gerçekleştirebileceğini denetler.

nonInteractivePermissions

Bir izin isteminin gösterilmesi gerektiğinde ancak etkileşimli TTY bulunmadığında (ACP oturumlarında her zaman böyledir) ne olacağını denetler.

Yapılandırma

Plugin yapılandırması aracılığıyla ayarlayın:

openclaw config set plugins.entries.acpx.config.permissionMode approve-allopenclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

Bu değerleri değiştirdikten sonra Gateway'i yeniden başlatın.

İlgili

• ACP aracıları — genel bakış, operatör çalışma kılavuzu, kavramlar
• Alt aracılar
• Çok aracılı yönlendirme