메인 콘텐츠로 건너뛰기
개요, 운영자 런북, 개념은 ACP 에이전트를 참조하세요. 아래 섹션에서는 acpx 하네스 구성, MCP 브리지용 Plugin 설정, 권한 구성을 다룹니다. ACP/acpx 경로를 설정할 때만 이 페이지를 사용하세요. 네이티브 Codex 앱 서버 런타임 구성은 Codex 하네스를 사용하세요. OpenAI API 키 또는 Codex OAuth 모델 제공자 구성은 OpenAI를 사용하세요. Codex에는 두 가지 OpenClaw 경로가 있습니다.
경로구성/명령설정 페이지
네이티브 Codex 앱 서버/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
  • 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",
      "openclaw",
      "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 또는 OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1을 설정하세요. 명시적 온디맨드 프로브는 /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
이 기능이 하는 일:
  • openclaw-plugin-tools라는 내장 MCP 서버를 ACPX 세션 부트스트랩에 주입합니다.
  • 설치되고 활성화된 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
이 기능이 하는 일:
  • openclaw-tools라는 내장 MCP 서버를 ACPX 세션 부트스트랩에 주입합니다.
  • 선택된 내장 OpenClaw 도구를 노출합니다. 초기 서버는 cron을 노출합니다.
  • 핵심 도구 노출을 명시적이고 기본적으로 꺼진 상태로 유지합니다.

​
런타임 작업 타임아웃 구성

acpx Plugin은 기본적으로 내장 런타임 시작 및 제어 작업에 120초를 부여합니다. 이를 통해 Gemini CLI 같은 느린 하네스가 ACP 시작과 초기화를 완료할 충분한 시간을 갖습니다. 호스트에 다른 작업 제한이 필요하면 재정의하세요. 
openclaw config set plugins.entries.acpx.config.timeoutSeconds 180
런타임 턴은 /acp timeout을 포함한 OpenClaw 에이전트/실행 타임아웃을 사용합니다. sessions_spawn은 호출별 타임아웃 재정의를 허용하지 않습니다. 이 값을 변경한 후 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 exec 승인과 별개이며, Claude CLI --permission-mode bypassPermissions 같은 CLI 백엔드 공급업체 우회 플래그와도 별개입니다. ACPX approve-all은 ACP 세션을 위한 하네스 수준의 비상 스위치입니다. OpenClaw tools.exec.mode, Codex Guardian 승인, ACPX 하네스 권한 간의 더 넓은 비교는 권한 모드를 참조하세요.

​
permissionMode

하네스 에이전트가 프롬프트 없이 수행할 수 있는 작업을 제어합니다.
값동작
approve-all모든 파일 쓰기와 셸 명령을 자동 승인합니다.
approve-reads읽기만 자동 승인하며, 쓰기와 exec에는 프롬프트가 필요합니다.
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 세션에서는 권한 프롬프트를 트리거하는 모든 쓰기 또는 exec가 AcpRuntimeError: Permission prompt unavailable in non-interactive mode로 실패할 수 있습니다.권한을 제한해야 한다면 세션이 충돌하는 대신 우아하게 성능 저하되도록 nonInteractivePermissions를 deny로 설정하세요.

​
관련 항목