메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

개요, 운영자 런북, 개념은 ACP 에이전트를 참조하세요. 아래 섹션에서는 acpx 하네스 구성, MCP 브리지용 Plugin 설정, 권한 구성을 다룹니다. ACP/acpx 경로를 설정할 때만 이 페이지를 사용하세요. 네이티브 Codex app-server 런타임 구성은 Codex 하네스를 사용하세요. OpenAI API 키 또는 Codex OAuth 모델 제공자 구성은 OpenAI를 사용하세요. Codex에는 두 가지 OpenClaw 경로가 있습니다.
경로구성/명령설정 페이지
네이티브 Codex app-server/codex ..., openai/gpt-* 에이전트 참조Codex 하네스
명시적 Codex ACP 어댑터/acp spawn codex, runtime: "acp", agentId: "codex"이 페이지
ACP/acpx 동작이 명시적으로 필요한 경우가 아니라면 네이티브 경로를 선호하세요.

​
acpx 하네스 지원(현재)

현재 acpx 기본 제공 하네스 별칭:
  • claude
  • codex
  • copilot
  • cursor (Cursor CLI: cursor-agent acp)
  • droid
  • gemini
  • iflow
  • kilocode
  • kimi
  • kiro
  • openclaw
  • opencode
  • pi
  • qwen
OpenClaw가 acpx 백엔드를 사용할 때는 acpx 구성에서 사용자 지정 에이전트 별칭을 정의하지 않는 한 agentId에 이 값들을 사용하는 것을 권장합니다. 로컬 Cursor 설치가 여전히 ACP를 agent acp로 노출한다면, 기본 제공 기본값을 변경하지 말고 acpx 구성에서 cursor 에이전트 명령을 재정의하세요. 직접 acpx CLI를 사용할 때는 --agent <command>로 임의의 어댑터를 대상으로 지정할 수도 있지만, 이 원시 탈출구는 acpx CLI 기능이며 일반적인 OpenClaw agentId 경로가 아닙니다. 모델 제어는 어댑터 기능에 따라 달라집니다. Codex ACP 모델 참조는 시작 전에 OpenClaw가 정규화합니다. 다른 하네스는 ACP models와 session/set_model 지원이 필요합니다. 하네스가 해당 ACP 기능도 자체 시작 모델 플래그도 노출하지 않으면 OpenClaw/acpx는 모델 선택을 강제할 수 없습니다.

​
필수 구성

핵심 ACP 기준 구성: 
{
  acp: {
    enabled: true,
    // Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: [
      "claude",
      "codex",
      "copilot",
      "cursor",
      "droid",
      "gemini",
      "iflow",
      "kilocode",
      "kimi",
      "kiro",
      "openclaw",
      "opencode",
      "pi",
      "qwen",
    ],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}
스레드 바인딩 구성은 채널 어댑터별로 다릅니다. Discord 예시: 
{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnSessions: true,
      },
    },
  },
}
스레드 바인딩 ACP 생성이 작동하지 않으면 먼저 어댑터 기능 플래그를 확인하세요.
  • Discord: channels.discord.threadBindings.spawnSessions=true
현재 대화 바인딩에는 하위 스레드 생성이 필요하지 않습니다. 활성 대화 컨텍스트와 ACP 대화 바인딩을 노출하는 채널 어댑터가 필요합니다. 구성 참조를 참조하세요.

​
acpx 백엔드용 Plugin 설정

패키지 설치는 ACP용 공식 @openclaw/acpx 런타임 Plugin을 사용합니다. ACP 하네스 세션을 사용하기 전에 설치하고 활성화하세요. 
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true
소스 체크아웃은 pnpm install 후 로컬 워크스페이스 Plugin도 사용할 수 있습니다. 다음으로 시작하세요. 
/acp doctor
acpx를 비활성화했거나, plugins.allow / plugins.deny로 거부했거나, 패키지 Plugin으로 되돌리려면 명시적 패키지 경로를 사용하세요. 
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true
개발 중 로컬 워크스페이스 설치: 
openclaw plugins install ./path/to/local/acpx-plugin
그런 다음 백엔드 상태를 확인하세요. 
/acp doctor

​
acpx 명령 및 버전 구성

기본적으로 acpx Plugin은 Gateway 시작 중 내장 ACP 백엔드를 프로브하고 Gateway ready 신호 전에 해당 프로브를 기다립니다. 시작 프로브를 건너뛰고 대신 백엔드를 지연 등록하려면 OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0을 설정하세요. 명시적 온디맨드 프로브에는 /acp doctor를 실행하세요. Plugin 구성에서 명령 또는 버전을 재정의하세요. 
{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}
  • command는 절대 경로, 상대 경로(OpenClaw 워크스페이스 기준으로 해석됨), 또는 명령 이름을 허용합니다.
  • expectedVersion: "any"는 엄격한 버전 일치를 비활성화합니다.
  • 사용자 지정 command 경로는 Plugin 로컬 자동 설치를 비활성화합니다.
경로나 플래그 값이 하나의 argv 토큰으로 유지되어야 할 때는 구조화된 인수로 개별 ACP 에이전트 명령을 재정의하세요. 
{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "agents": {
            "claude": {
              "command": "node",
              "args": ["/path/to/custom adapter.mjs", "--verbose"]
            }
          }
        }
      }
    }
  }
}
  • agents.<id>.command는 해당 ACP 에이전트의 실행 파일 또는 기존 명령 문자열입니다.
  • agents.<id>.args는 선택 사항입니다. OpenClaw가 현재 acpx 명령 문자열 레지스트리에 전달하기 전에 각 배열 항목은 셸 인용됩니다.
Plugins를 참조하세요.

​
자동 의존성 설치

npm install -g openclaw로 OpenClaw를 전역 설치하면 acpx 런타임 의존성(플랫폼별 바이너리)이 postinstall 훅을 통해 자동으로 설치됩니다. 자동 설치가 실패해도 Gateway는 정상적으로 시작되며 openclaw acp doctor를 통해 누락된 의존성을 보고합니다.

​
Plugin 도구 MCP 브리지

기본적으로 ACPX 세션은 OpenClaw Plugin 등록 도구를 ACP 하네스에 노출하지 않습니다. Codex 또는 Claude Code 같은 ACP 에이전트가 메모리 recall/store 같은 설치된 OpenClaw Plugin 도구를 호출하도록 하려면 전용 브리지를 활성화하세요. 
openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
이 기능이 하는 일:
  • ACPX 세션 부트스트랩에 openclaw-plugin-tools라는 기본 제공 MCP 서버를 주입합니다.
  • 설치되고 활성화된 OpenClaw Plugin이 이미 등록한 Plugin 도구를 노출합니다.
  • 기능을 명시적이며 기본값 비활성 상태로 유지합니다.
보안 및 신뢰 참고 사항:
  • 이는 ACP 하네스 도구 표면을 확장합니다.
  • ACP 에이전트는 Gateway에서 이미 활성 상태인 Plugin 도구에만 접근합니다.
  • 이를 해당 Plugin들이 OpenClaw 자체에서 실행되도록 허용하는 것과 동일한 신뢰 경계로 취급하세요.
  • 활성화하기 전에 설치된 Plugin을 검토하세요.
사용자 지정 mcpServers는 이전처럼 계속 작동합니다. 기본 제공 Plugin 도구 브리지는 일반 MCP 서버 구성을 대체하는 것이 아니라 추가로 선택할 수 있는 편의 기능입니다.

​
OpenClaw 도구 MCP 브리지

기본적으로 ACPX 세션은 기본 제공 OpenClaw 도구도 MCP를 통해 노출하지 않습니다. ACP 에이전트에 cron 같은 선택된 기본 제공 도구가 필요할 때는 별도의 핵심 도구 브리지를 활성화하세요. 
openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true
이 기능이 하는 일:
  • ACPX 세션 부트스트랩에 openclaw-tools라는 기본 제공 MCP 서버를 주입합니다.
  • 선택된 기본 제공 OpenClaw 도구를 노출합니다. 초기 서버는 cron을 노출합니다.
  • 핵심 도구 노출을 명시적이며 기본값 비활성 상태로 유지합니다.

​
런타임 제한 시간 구성

acpx Plugin은 내장 런타임 턴의 기본 제한 시간을 120초로 설정합니다. 이는 Gemini CLI 같은 느린 하네스가 ACP 시작과 초기화를 완료할 충분한 시간을 제공합니다. 호스트에 다른 런타임 제한이 필요하면 이를 재정의하세요. 
openclaw config set plugins.entries.acpx.config.timeoutSeconds 180
이 값을 변경한 뒤 Gateway를 다시 시작하세요.

​
상태 프로브 에이전트 구성

/acp doctor 또는 시작 프로브가 백엔드를 확인할 때 번들 acpx Plugin은 하나의 하네스 에이전트를 프로브합니다. acp.allowedAgents가 설정되어 있으면 기본값은 첫 번째 허용 에이전트입니다. 그렇지 않으면 기본값은 codex입니다. 배포에서 상태 확인에 다른 ACP 에이전트가 필요하다면 프로브 에이전트를 명시적으로 설정하세요. 
openclaw config set plugins.entries.acpx.config.probeAgent claude
이 값을 변경한 뒤 Gateway를 다시 시작하세요.

​
권한 구성

ACP 세션은 비대화식으로 실행됩니다. 파일 쓰기 및 셸 실행 권한 프롬프트를 승인하거나 거부할 TTY가 없습니다. acpx Plugin은 권한 처리 방식을 제어하는 두 가지 구성 키를 제공합니다. 이 ACPX 하네스 권한은 OpenClaw 실행 승인과 별개이며, Claude CLI --permission-mode bypassPermissions 같은 CLI 백엔드 벤더 우회 플래그와도 별개입니다. ACPX approve-all은 ACP 세션용 하네스 수준 비상 전환 스위치입니다.

​
permissionMode

하네스 에이전트가 프롬프트 없이 수행할 수 있는 작업을 제어합니다.
값동작
approve-all모든 파일 쓰기와 셸 명령을 자동 승인합니다.
approve-reads읽기만 자동 승인합니다. 쓰기와 실행에는 프롬프트가 필요합니다.
deny-all모든 권한 프롬프트를 거부합니다.

​
nonInteractivePermissions

권한 프롬프트가 표시되어야 하지만 대화형 TTY를 사용할 수 없을 때 발생하는 동작을 제어합니다. ACP 세션에서는 항상 이 경우에 해당합니다.
값동작
failAcpRuntimeError로 세션을 중단합니다. (기본값)
deny권한을 조용히 거부하고 계속 진행합니다(우아한 기능 저하).

​
구성

Plugin 구성으로 설정하세요. 
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
이 값들을 변경한 뒤 Gateway를 다시 시작하세요.
OpenClaw의 기본값은 permissionMode=approve-reads 및 nonInteractivePermissions=fail입니다. 비대화식 ACP 세션에서 권한 프롬프트를 트리거하는 쓰기 또는 실행은 AcpRuntimeError: Permission prompt unavailable in non-interactive mode로 실패할 수 있습니다.권한을 제한해야 하는 경우, 세션이 충돌하는 대신 우아하게 기능 저하되도록 nonInteractivePermissions를 deny로 설정하세요.

​
관련 항목