เอเจนต์ ACP

• หากตั้งค่า plugins.allow ไว้ ค่านี้คือรายการ Plugin แบบจำกัด และ ต้อง รวม acpx; มิฉะนั้นแบ็กเอนด์ ACP ที่ติดตั้งไว้จะถูกบล็อกโดยตั้งใจ และ /acp doctor จะรายงานรายการ allowlist ที่ขาดหายไป
• อะแดปเตอร์ Codex ACP ถูกจัดเตรียมพร้อมกับ Plugin acpx และจะถูกเปิดใช้งานภายในเครื่องเมื่อเป็นไปได้
• Codex ACP ทำงานด้วย CODEX_HOME ที่แยกออกมา; OpenClaw คัดลอกรายการโปรเจกต์ที่เชื่อถือได้พร้อมการกำหนดค่าการกำหนดเส้นทาง model/provider ที่ปลอดภัยจากการกำหนดค่า Codex ของโฮสต์ ขณะที่ auth, notifications และ hooks ยังคงอยู่ในการกำหนดค่าของโฮสต์
• อะแดปเตอร์ชุดทดสอบเป้าหมายอื่นๆ อาจยังถูกดึงมาเมื่อจำเป็นด้วย npx ในครั้งแรกที่คุณใช้งาน
• การยืนยันตัวตนของผู้ขายยังต้องมีอยู่บนโฮสต์สำหรับชุดทดสอบนั้น
• หากโฮสต์ไม่มี npm หรือการเข้าถึงเครือข่าย การดึงอะแดปเตอร์ครั้งแรกจะล้มเหลวจนกว่าจะเตรียมแคชไว้ล่วงหน้า หรือติดตั้งอะแดปเตอร์ด้วยวิธีอื่น

ACP เปิดใช้โปรเซสชุดทดสอบภายนอกจริง OpenClaw เป็นเจ้าของการกำหนดเส้นทาง สถานะงานเบื้องหลัง การส่งมอบ การผูก และนโยบาย ส่วนชุดทดสอบ เป็นเจ้าของการเข้าสู่ระบบ provider แค็ตตาล็อกโมเดล พฤติกรรมของระบบไฟล์ และ เครื่องมือ native ของตนเอง

ก่อนโทษ OpenClaw ให้ตรวจสอบว่า:

• /acp doctor รายงานว่าแบ็กเอนด์เปิดใช้งานอยู่และอยู่ในสถานะปกติ
• id เป้าหมายได้รับอนุญาตโดย acp.allowedAgents เมื่อตั้งค่ารายการอนุญาตนั้นไว้
• คำสั่งฮาร์เนสสามารถเริ่มทำงานบนโฮสต์ Gateway ได้
• มีการยืนยันตัวตนของผู้ให้บริการสำหรับฮาร์เนสนั้น (claude, codex, gemini, opencode, droid ฯลฯ)
• โมเดลที่เลือกมีอยู่สำหรับฮาร์เนสนั้น - id ของโมเดลไม่สามารถใช้ข้ามฮาร์เนสได้
• cwd ที่ร้องขอมีอยู่และเข้าถึงได้ หรือไม่ต้องระบุ cwd แล้วให้แบ็กเอนด์ใช้ค่าเริ่มต้นของตัวเอง
• โหมดสิทธิ์ตรงกับงาน เซสชันแบบไม่โต้ตอบไม่สามารถคลิกพรอมป์สิทธิ์ดั้งเดิมได้ ดังนั้นงานเขียนโค้ดที่เน้นการเขียน/รันคำสั่งมักต้องใช้โปรไฟล์สิทธิ์ ACPX ที่ดำเนินต่อแบบ headless ได้

• Spawn สร้างหรือดำเนินเซสชัน runtime ของ ACP ต่อ บันทึกเมทาดาทา ACP ในที่เก็บเซสชัน OpenClaw และอาจสร้างงานเบื้องหลังเมื่อรันนั้นมี parent เป็นเจ้าของ
• เซสชัน ACP ที่ parent เป็นเจ้าของจะถูกถือว่าเป็นงานเบื้องหลัง แม้เมื่อเซสชัน runtime เป็นแบบคงอยู่ก็ตาม การเสร็จสิ้นและการส่งข้ามพื้นผิวจะผ่านตัวแจ้งเตือนงานของ parent แทนที่จะทำตัวเหมือนเซสชันแชตปกติที่ผู้ใช้เห็น
• การบำรุงรักษางานจะปิดเซสชัน ACP แบบ one-shot ที่ parent เป็นเจ้าของซึ่งสิ้นสุดแล้วหรือกำพร้า เซสชัน ACP แบบคงอยู่จะถูกเก็บไว้ตราบใดที่ยังมีการผูกบทสนทนาที่ใช้งานอยู่ เซสชันแบบคงอยู่ที่ค้างอยู่โดยไม่มีการผูกที่ใช้งานอยู่จะถูกปิด เพื่อไม่ให้กลับมาดำเนินต่ออย่างเงียบ ๆ หลังจากงานที่เป็นเจ้าของเสร็จสิ้นแล้วหรือระเบียนงานหายไป
• ข้อความติดตามผลที่ผูกไว้จะไปยังเซสชัน ACP โดยตรงจนกว่าการผูกจะถูกปิด เลิกโฟกัส รีเซ็ต หรือหมดอายุ
• คำสั่ง Gateway จะอยู่ในเครื่องเสมอ /acp ..., /status และ /unfocus จะไม่ถูกส่งเป็นข้อความพรอมป์ปกติไปยังฮาร์เนส ACP ที่ผูกไว้
• cancel ยกเลิกเทิร์นที่ใช้งานอยู่เมื่อแบ็กเอนด์รองรับการยกเลิก แต่ไม่ได้ลบการผูกหรือเมทาดาทาเซสชัน
• close จบเซสชัน ACP จากมุมมองของ OpenClaw และลบการผูก ฮาร์เนสอาจยังเก็บประวัติ upstream ของตัวเองไว้หากรองรับการดำเนินต่อ
• Plugin acpx ทำความสะอาดต้นไม้โปรเซส wrapper และอะแดปเตอร์ที่ OpenClaw เป็นเจ้าของหลังจาก close และเก็บกวาด orphan ACPX ที่ OpenClaw เป็นเจ้าของและค้างอยู่ระหว่างการเริ่มต้น Gateway
• worker runtime ที่ไม่ได้ใช้งานมีสิทธิ์ถูกทำความสะอาดหลังจาก acp.runtime.ttlMinutes; เมทาดาทาเซสชันที่จัดเก็บไว้ยังคงพร้อมใช้งานสำหรับ /acp sessions

ตัวกระตุ้นภาษาธรรมชาติที่ควรกำหนดเส้นทางไปยัง Plugin Codex ดั้งเดิม เมื่อเปิดใช้งานอยู่:

• "ผูกช่อง Discord นี้กับ Codex"
• "แนบแชตนี้เข้ากับเธรด Codex <id>"
• "แสดงเธรด Codex แล้วผูกเธรดนี้"

การผูกการสนทนา Codex แบบเนทีฟเป็นเส้นทางควบคุมแชทเริ่มต้น เครื่องมือแบบไดนามิกของ OpenClaw ยังคงดำเนินการผ่าน OpenClaw ขณะที่ เครื่องมือเนทีฟของ Codex เช่น shell/apply-patch ดำเนินการภายใน Codex สำหรับเหตุการณ์เครื่องมือเนทีฟของ Codex OpenClaw จะแทรกรีเลย์ฮุกเนทีฟ ต่อหนึ่งเทิร์น เพื่อให้ฮุกของ Plugin สามารถบล็อก before_tool_call, สังเกต after_tool_call, และกำหนดเส้นทางเหตุการณ์ PermissionRequest ของ Codex ผ่านการอนุมัติของ OpenClaw ฮุก Stop ของ Codex จะถูกรีเลย์ไปยัง before_agent_finalize ของ OpenClaw ซึ่ง Plugin สามารถขอให้โมเดลทำงานอีก หนึ่งรอบก่อนที่ Codex จะสรุปคำตอบ รีเลย์นี้ยังคงตั้งใจให้ระมัดระวัง: ไม่เปลี่ยนอาร์กิวเมนต์ของเครื่องมือเนทีฟของ Codex หรือเขียนระเบียนเธรดของ Codex ใหม่ ใช้ ACP แบบชัดเจนเฉพาะ เมื่อต้องการโมเดลรันไทม์/เซสชันของ ACP เท่านั้น ขอบเขตการรองรับ Codex แบบฝังตัวมีเอกสารอยู่ใน สัญญาการรองรับ Codex harness v1.

• การอ้างอิงโมเดล Codex เดิม - เส้นทางโมเดล OAuth/การสมัครสมาชิก Codex เดิมที่ซ่อมแซมโดย doctor
• openai/* - รันไทม์ app-server ฝังตัวของ Codex แบบเนทีฟสำหรับเทิร์นเอเจนต์ OpenAI
• /codex ... - การควบคุมการสนทนา Codex แบบเนทีฟ
• /acp ... หรือ runtime: "acp" - การควบคุม ACP/acpx แบบชัดเจน

ทริกเกอร์ที่ควรกำหนดเส้นทางไปยังรันไทม์ ACP:

• "เรียกใช้สิ่งนี้เป็นเซสชัน Claude Code ACP แบบครั้งเดียว แล้วสรุปผลลัพธ์"
• "ใช้ Gemini CLI สำหรับงานนี้ในเธรด แล้วเก็บการติดตามผลไว้ในเธรดเดียวกันนั้น"
• "เรียกใช้ Codex ผ่าน ACP ในเธรดเบื้องหลัง"

OpenClaw เลือก runtime: "acp", resolve agentId ของ harness, ผูกกับการสนทนาหรือเธรดปัจจุบันเมื่อรองรับ และ กำหนดเส้นทางการติดตามผลไปยังเซสชันนั้นจนกว่าจะปิด/หมดอายุ Codex จะ ไปตามเส้นทางนี้เฉพาะเมื่อมีการระบุ ACP/acpx อย่างชัดเจน หรือ Plugin Codex แบบเนทีฟไม่พร้อมใช้งานสำหรับการดำเนินการที่ร้องขอ

สำหรับ sessions_spawn จะโฆษณา runtime: "acp" เฉพาะเมื่อ ACP เปิดใช้งานอยู่ ผู้ร้องขอไม่ได้อยู่ใน sandbox และโหลดแบ็กเอนด์รันไทม์ ACP แล้ว acp.dispatch.enabled=false จะหยุดการ dispatch เธรด ACP อัตโนมัติชั่วคราว แต่ไม่ซ่อนหรือบล็อกการเรียก sessions_spawn({ runtime: "acp" }) แบบชัดเจน ซึ่งกำหนดเป้าหมายไปยัง id ของ ACP harness เช่น codex, claude, droid, gemini, หรือ opencode อย่าส่ง id เอเจนต์ config ปกติของ OpenClaw จาก agents_list เว้นแต่รายการนั้นจะ ถูกกำหนดค่าอย่างชัดเจนด้วย agents.list[].runtime.type="acp"; มิฉะนั้นให้ใช้รันไทม์ sub-agent เริ่มต้น เมื่อเอเจนต์ OpenClaw ถูกกำหนดค่าด้วย runtime.type="acp" OpenClaw จะใช้ runtime.acp.agent เป็น id ของ harness พื้นฐาน

• --bind here และ --thread ... ใช้ร่วมกันไม่ได้
• --bind here ทำงานเฉพาะกับช่องที่ประกาศการรองรับการผูกการสนทนาปัจจุบัน; มิฉะนั้น OpenClaw จะส่งข้อความไม่รองรับที่ชัดเจน การผูกคงอยู่ข้ามการรีสตาร์ท Gateway
• บน Discord, spawnSessions ควบคุมการสร้างเธรดลูกสำหรับ --thread auto|here - ไม่ใช่ --bind here
• หากคุณ spawn ไปยังเอเจนต์ ACP อื่นโดยไม่มี --cwd OpenClaw จะสืบทอดพื้นที่ทำงานของ เอเจนต์เป้าหมาย โดยค่าเริ่มต้น พาธที่สืบทอดซึ่งหายไป (ENOENT/ENOTDIR) จะ fallback ไปยังค่าเริ่มต้นของแบ็กเอนด์; ข้อผิดพลาดการเข้าถึงอื่น ๆ (เช่น EACCES) จะแสดงเป็นข้อผิดพลาดการ spawn
• คำสั่งจัดการ Gateway ยังคงเป็น local ในการสนทนาที่ผูกไว้ - คำสั่ง /acp ... จะถูกจัดการโดย OpenClaw แม้เมื่อข้อความติดตามผลปกติถูกกำหนดเส้นทางไปยังเซสชัน ACP ที่ผูกไว้; /status และ /unfocus ยังอยู่ local เมื่อใดก็ตามที่เปิดใช้งานการจัดการคำสั่งสำหรับพื้นผิวนั้น

เมื่อเปิดใช้งานการผูกเธรดสำหรับอะแดปเตอร์ช่อง:

• OpenClaw ผูกเธรดกับเซสชัน ACP เป้าหมาย
• ข้อความติดตามผลในเธรดนั้นถูกกำหนดเส้นทางไปยังเซสชัน ACP ที่ผูกไว้
• เอาต์พุต ACP ถูกส่งกลับไปยังเธรดเดียวกัน
• การ unfocus/ปิด/archive/หมดเวลา idle หรือการหมดอายุ max-age จะลบการผูก
• /acp close, /acp cancel, /acp status, /status, และ /unfocus เป็นคำสั่ง Gateway ไม่ใช่ prompt ไปยัง ACP harness

feature flag ที่จำเป็นสำหรับ ACP ที่ผูกกับเธรด:

• acp.enabled=true
• acp.dispatch.enabled เปิดอยู่โดยค่าเริ่มต้น (ตั้งค่า false เพื่อหยุดการ dispatch เธรด ACP อัตโนมัติชั่วคราว; การเรียก sessions_spawn({ runtime: "acp" }) แบบชัดเจนยังคงทำงาน)
• เปิดใช้งานการ spawn เซสชันเธรดของ channel-adapter (ค่าเริ่มต้น: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

การรองรับการผูกเธรดขึ้นอยู่กับอะแดปเตอร์ หากอะแดปเตอร์ช่องที่ใช้งานอยู่ ไม่รองรับการผูกเธรด OpenClaw จะส่งข้อความไม่รองรับ/ไม่พร้อมใช้งาน ที่ชัดเจน

• อะแดปเตอร์ช่องใด ๆ ที่เปิดเผยความสามารถการผูกเซสชัน/เธรด
• การรองรับในตัวปัจจุบัน: เธรด/ช่อง Discord, หัวข้อ Telegram (หัวข้อฟอรัมในกลุ่ม/supergroups และหัวข้อ DM)
• ช่อง Plugin สามารถเพิ่มการรองรับผ่านอินเทอร์เฟซการผูกเดียวกัน

เซสชันแบบโต้ตอบมีไว้เพื่อสนทนาต่อบนพื้นผิวแชต ที่มองเห็นได้:

• /acp spawn ... --bind here ผูกบทสนทนาปัจจุบันกับเซสชัน ACP
• /acp spawn ... --thread ... ผูกเธรด/หัวข้อของช่องทางกับเซสชัน ACP
• bindings[].type="acp" ที่กำหนดค่าไว้แบบถาวรจะกำหนดเส้นทางบทสนทนาที่ตรงกันไปยังเซสชัน ACP เดิม

ข้อความติดตามผลในบทสนทนาที่ผูกไว้จะถูกส่งตรงไปยัง เซสชัน ACP และเอาต์พุต ACP จะถูกส่งกลับไปยัง ช่องทาง/เธรด/หัวข้อเดียวกันนั้น

สิ่งที่ OpenClaw ส่งไปยังฮาร์เนส:

• การติดตามผลที่ผูกตามปกติจะถูกส่งเป็นข้อความพรอมป์ พร้อมไฟล์แนบเฉพาะเมื่อฮาร์เนส/แบ็กเอนด์รองรับเท่านั้น
• คำสั่งจัดการ /acp และคำสั่ง Gateway ภายในจะถูกดักก่อนส่งต่อไปยัง ACP
• เหตุการณ์เสร็จสิ้นที่สร้างโดยรันไทม์จะถูกทำให้เป็นรูปธรรมตามเป้าหมาย เอเจนต์ OpenClaw จะได้รับซอง runtime-context ภายในของ OpenClaw; ฮาร์เนส ACP ภายนอกจะได้รับพรอมป์ธรรมดาพร้อมผลลัพธ์ลูกและคำสั่ง ซองดิบ <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> ไม่ควรถูกส่งไปยังฮาร์เนสภายนอกหรือถูกคงอยู่เป็นข้อความทรานสคริปต์ผู้ใช้ ACP
• รายการทรานสคริปต์ ACP ใช้ข้อความทริกเกอร์ที่ผู้ใช้เห็นหรือพรอมป์การเสร็จสิ้นแบบธรรมดา เมตาดาตาเหตุการณ์ภายในยังคงมีโครงสร้างใน OpenClaw เมื่อทำได้ และไม่ถือเป็นเนื้อหาแชตที่ผู้ใช้เขียน

เซสชัน ACP แบบครั้งเดียวที่ถูกสร้างโดยการรันของเอเจนต์อีกตัวเป็นลูก เบื้องหลัง คล้ายกับ sub-agent:

• พาเรนต์ขอให้ทำงานด้วย sessions_spawn({ runtime: "acp", mode: "run" })
• ลูกทำงานในเซสชันฮาร์เนส ACP ของตนเอง
• เทิร์นลูกทำงานบนเลนเบื้องหลังเดียวกับที่ใช้โดยการสร้าง sub-agent แบบเนทีฟ ดังนั้นฮาร์เนส ACP ที่ช้าจะไม่บล็อกงานเซสชันหลักที่ไม่เกี่ยวข้อง
• รายงานการเสร็จสิ้นกลับผ่านเส้นทางประกาศ task-completion OpenClaw แปลงเมตาดาตาการเสร็จสิ้นภายในเป็นพรอมป์ ACP แบบธรรมดาก่อนส่งไปยังฮาร์เนสภายนอก ดังนั้นฮาร์เนสจะไม่เห็นเครื่องหมายบริบทรันไทม์ที่มีเฉพาะ OpenClaw
• พาเรนต์เขียนผลลัพธ์ลูกใหม่ด้วยเสียงผู้ช่วยตามปกติเมื่อการตอบกลับที่ผู้ใช้เห็นมีประโยชน์

อย่า ถือว่าเส้นทางนี้เป็นแชตแบบเพียร์ทูเพียร์ระหว่างพาเรนต์ และลูก ลูกมีช่องทางการเสร็จสิ้นกลับไปยัง พาเรนต์อยู่แล้ว

sessions_send สามารถกำหนดเป้าหมายไปยังเซสชันอื่นหลังจากสร้างแล้ว สำหรับเซสชัน เพียร์ปกติ OpenClaw ใช้เส้นทางติดตามผล agent-to-agent (A2A) หลังจากฉีดข้อความ:

• รอการตอบกลับของเซสชันเป้าหมาย
• อนุญาตให้ผู้ร้องขอและเป้าหมายแลกเปลี่ยนเทิร์นติดตามผลในจำนวนจำกัดได้ตามต้องการ
• ขอให้เป้าหมายสร้างข้อความประกาศ
• ส่งประกาศนั้นไปยังช่องทางหรือเธรดที่มองเห็นได้

เส้นทาง A2A นั้นเป็น fallback สำหรับการส่งแบบเพียร์ที่ผู้ส่งต้องการ การติดตามผลที่มองเห็นได้ โดยยังคงเปิดใช้งานเมื่อเซสชันที่ไม่เกี่ยวข้อง สามารถเห็นและส่งข้อความหาเป้าหมาย ACP ได้ เช่น ภายใต้การตั้งค่า tools.sessions.visibility แบบกว้าง

OpenClaw จะข้ามการติดตามผลแบบ A2A เฉพาะเมื่อผู้ร้องขอเป็น parent ของ ACP child แบบ one-shot ที่ parent ของตนเป็นเจ้าของ ในกรณีนั้น การเรียกใช้ A2A ทับบนการทำงานของ task ที่เสร็จแล้วอาจปลุก parent ด้วย ผลลัพธ์ของ child, ส่งต่อคำตอบของ parent กลับเข้าไปใน child, และ สร้างลูปสะท้อนกลับ parent/child ได้ ผลลัพธ์ sessions_send รายงาน delivery.status="skipped" สำหรับกรณี owned-child นั้น เพราะเส้นทาง completion รับผิดชอบผลลัพธ์อยู่แล้ว

ใช้ resumeSessionId เพื่อดำเนิน ACP session ก่อนหน้าต่อแทนการ เริ่มใหม่ Agent จะเล่นประวัติการสนทนาของตนซ้ำผ่าน session/load จึงกลับมาทำงานพร้อมบริบทเต็มของสิ่งที่เกิดขึ้นก่อนหน้า

{  "task": "Continue where we left off - fix the remaining test failures",  "runtime": "acp",  "agentId": "codex",  "resumeSessionId": "<previous-session-id>"}

กรณีใช้งานทั่วไป:

• ส่งต่อ Codex session จากแล็ปท็อปของคุณไปยังโทรศัพท์ของคุณ - บอก Agent ของคุณให้ทำต่อจากจุดที่คุณค้างไว้
• ดำเนิน coding session ที่คุณเริ่มแบบโต้ตอบใน CLI ต่อ โดยตอนนี้ให้ทำแบบ headless ผ่าน Agent ของคุณ
• ทำงานต่อจากจุดที่ถูกขัดจังหวะโดยการรีสตาร์ท Gateway หรือ idle timeout

หมายเหตุ:

• resumeSessionId ใช้ได้เฉพาะเมื่อ runtime: "acp"; sub-agent runtime เริ่มต้นจะละเว้นฟิลด์เฉพาะ ACP นี้
• streamTo ใช้ได้เฉพาะเมื่อ runtime: "acp"; sub-agent runtime เริ่มต้นจะละเว้นฟิลด์เฉพาะ ACP นี้
• resumeSessionId เป็น host-local ACP/harness resume id ไม่ใช่คีย์ channel session ของ OpenClaw; OpenClaw ยังคงตรวจสอบนโยบาย ACP spawn และนโยบาย target agent ก่อน dispatch ขณะที่ ACP backend หรือ harness เป็นเจ้าของ authorization สำหรับการโหลด upstream id นั้น
• resumeSessionId กู้คืนประวัติการสนทนา ACP upstream; thread และ mode ยังคงใช้กับ OpenClaw session ใหม่ที่คุณกำลังสร้างตามปกติ ดังนั้น mode: "session" ยังต้องใช้ thread: true
• target agent ต้องรองรับ session/load (Codex และ Claude Code รองรับ)
• หากไม่พบ session id การ spawn จะล้มเหลวพร้อมข้อผิดพลาดที่ชัดเจน - ไม่มี silent fallback ไปยัง session ใหม่

หลัง deploy Gateway ให้รันการตรวจสอบ end-to-end แบบ live แทนการ เชื่อถือ unit tests:

1. ตรวจสอบเวอร์ชัน Gateway ที่ deploy แล้วและ commit บน target host
2. เปิด ACPX bridge session ชั่วคราวไปยัง Agent แบบ live
3. ขอให้ Agent นั้นเรียก sessions_spawn ด้วย runtime: "acp", agentId: "codex", mode: "run", และ task Reply with exactly LIVE-ACP-SPAWN-OK
4. ตรวจสอบ accepted=yes, childSessionKey จริง, และไม่มี validator error
5. ล้าง bridge session ชั่วคราว

คง gate ไว้ที่ mode: "run" และข้าม streamTo: "parent" - mode: "session" ที่ผูกกับ thread และเส้นทาง stream-relay เป็น integration pass ที่ครบถ้วนกว่าอีกชุดหนึ่ง