ACP 에이전트 — 설정

개요, 운영자 런북 및 개념은 ACP 에이전트를 참조하세요.

이 페이지에서는 acpx 하네스 구성, MCP 브리지용 Plugin 설정 및 권한 구성을 다룹니다.

ACP/acpx 경로를 설정할 때만 이 페이지를 사용하세요. 네이티브 Codex 앱 서버 런타임 구성은 Codex 하네스를 사용하세요. OpenAI API 키 또는 Codex OAuth 모델 공급자 구성은 OpenAI를 사용하세요.

Codex에는 두 가지 OpenClaw 경로가 있습니다.

ACP/acpx 동작이 명시적으로 필요한 경우가 아니라면 네이티브 경로를 우선 사용하세요.

acpx 하네스 지원(현재)

내장 acpx 하네스 별칭(고정된 acpx 종속성에서 제공):

factory-droid와 factorydroid도 내장 droid 어댑터로 해석됩니다.

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,    // 선택 사항. 기본값은 true입니다. /acp 제어를 유지하면서 ACP 디스패치를 일시 중지하려면 false로 설정합니다.    dispatch: { enabled: true },    backend: "acpx",    defaultAgent: "codex",    allowedAgents: [      "claude",      "codex",      "copilot",      "cursor",      "droid",      "gemini",      "iflow",      "kilocode",      "kimi",      "kiro",      "openclaw",      "opencode",      "qwen",    ],    maxConcurrentSessions: 8,    stream: {      // 기본값은 coalesceIdleMs: 350, maxChunkChars: 1800이며, 여기서는 명시적으로 표시합니다.      coalesceIdleMs: 350,      maxChunkChars: 1800,    },    runtime: {      ttlMinutes: 120,    },  },}

스레드 바인딩 구성은 채널 어댑터마다 다릅니다. Discord 예시:

{  session: {    threadBindings: {      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },  },  channels: {    discord: {      threadBindings: {        enabled: true,        // 기본값은 이미 true이며, 여기서는 명시적으로 표시합니다.        spawnSessions: true,      },    },  },}

스레드에 바인딩된 ACP 생성이 작동하지 않으면 먼저 어댑터 기능 플래그를 확인하세요.

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

현재 대화 바인딩에는 하위 스레드 생성이 필요하지 않습니다. 활성 대화 컨텍스트와 ACP 대화 바인딩을 노출하는 채널 어댑터가 필요합니다.

구성 참조를 참조하세요.

acpx 백엔드용 Plugin 설정

패키지 설치에서는 ACP용 공식 @openclaw/acpx 런타임 Plugin을 사용합니다. ACP 하네스 세션을 사용하기 전에 설치하고 활성화하세요.

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

소스 체크아웃에서는 pnpm install 후 로컬 워크스페이스 Plugin도 사용할 수 있습니다.

다음으로 시작하세요.

/acp doctor

acpx를 비활성화했거나 plugins.allow / plugins.deny를 통해 거부했거나 패키지 Plugin으로 다시 전환하려면 명시적 패키지 경로를 사용하세요.

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

개발 중 로컬 워크스페이스 설치:

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

그런 다음 백엔드 상태를 확인하세요.

/acp doctor

acpx 런타임 시작 프로브

acpx Plugin은 ACP 런타임을 직접 내장합니다(별도로 구성할 acpx 바이너리나 버전이 없음). 기본적으로 Gateway 시작 중에 내장 백엔드를 등록하고 Gateway ready 신호 전에 시작 프로브를 기다립니다. 시작 프로브를 의도적으로 비활성화하는 스크립트나 환경에서만 OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 또는 OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1을 설정하세요. 명시적인 온디맨드 프로브에는 /acp doctor를 실행하세요.

경로나 플래그 값을 하나의 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 명령 문자열 레지스트리를 통해 전달하기 전에 각 배열 항목을 셸 인용 처리합니다.

Plugin을 참조하세요.

자동 어댑터 다운로드

acpx는 처음 사용할 때 npx를 통해 ACP 어댑터(예: Claude 및 Codex ACP 브리지)를 자동으로 다운로드합니다. 어댑터 패키지를 수동으로 설치할 필요가 없으며 OpenClaw 자체에도 별도의 설치 후 단계가 없습니다. 어댑터 다운로드 또는 생성에 실패하면 /acp doctor에서 실패를 보고합니다.

Plugin 도구 MCP 브리지

기본적으로 ACPX 세션은 OpenClaw Plugin에서 등록한 도구를 ACP 하네스에 노출하지 않습니다.

Codex 또는 Claude Code 같은 ACP 에이전트가 메모리 조회/저장 등의 설치된 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은 호출별 시간 제한 재정의를 허용하지 않습니다. 운영자용 경로는 agents.defaults.subagents.runTimeoutSeconds입니다. timeoutSeconds를 변경한 후 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 세션용 하네스 수준의 비상 전환 스위치입니다.

OpenClaw tools.exec.mode, Codex Guardian 승인 및 ACPX 하네스 권한의 포괄적인 비교는 권한 모드를 참조하세요.

permissionMode

하네스 에이전트가 프롬프트 없이 수행할 수 있는 작업을 제어합니다.

nonInteractivePermissions

권한 요청을 표시해야 하지만 대화형 TTY를 사용할 수 없을 때의 동작을 제어합니다(ACP 세션은 항상 이에 해당합니다).

구성

Plugin 구성으로 설정합니다.

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

이 값을 변경한 후 Gateway를 다시 시작합니다.

관련 항목

• ACP 에이전트 — 개요, 운영자 실행 지침, 개념
• 하위 에이전트
• 다중 에이전트 라우팅