> ## 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 에이전트 — 설정

개요, 운영자 런북, 개념은 [ACP 에이전트](/ko/tools/acp-agents)를 참조하세요.

아래 섹션에서는 acpx 하네스 구성, MCP 브리지용 Plugin 설정, 권한 구성을 다룹니다.

ACP/acpx 경로를 설정할 때만 이 페이지를 사용하세요. 네이티브 Codex
앱 서버 런타임 구성은 [Codex 하네스](/ko/plugins/codex-harness)를 사용하세요.
OpenAI API 키 또는 Codex OAuth 모델 제공자 구성은
[OpenAI](/ko/providers/openai)를 사용하세요.

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

| 경로                | 구성/명령                                                  | 설정 페이지                                 |
| ----------------- | ------------------------------------------------------ | -------------------------------------- |
| 네이티브 Codex 앱 서버   | `/codex ...`, `openai/gpt-*` 에이전트 참조                   | [Codex 하네스](/ko/plugins/codex-harness) |
| 명시적 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 기준:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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 예시:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnSessions: true,
      },
    },
  },
}
```

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

* Discord: `channels.discord.threadBindings.spawnSessions=true`

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

[구성 참조](/ko/gateway/configuration-reference)를 참조하세요.

## acpx 백엔드용 Plugin 설정

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true
```

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

다음으로 시작하세요.

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
/acp doctor
```

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true
```

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install ./path/to/local/acpx-plugin
```

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

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
/acp doctor
```

### acpx 명령 및 버전 구성

기본적으로 `acpx` Plugin은 Gateway 시작 중 내장 ACP 백엔드를 등록하고,
Gateway `ready` 신호 전에 내장 런타임 시작 프로브를 기다립니다.
시작 프로브를 의도적으로 비활성화한 상태로 유지하는 스크립트나 환경에서만
`OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0` 또는
`OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1`을 설정하세요. 명시적 온디맨드 프로브는
`/acp doctor`를 실행하세요.

Plugin 구성에서 명령 또는 버전을 재정의하세요.

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}
```

* `command`는 절대 경로, 상대 경로(OpenClaw 워크스페이스 기준으로 해석), 또는 명령 이름을 허용합니다.
* `expectedVersion: "any"`는 엄격한 버전 일치를 비활성화합니다.
* 사용자 지정 `command` 경로는 Plugin 로컬 자동 설치를 비활성화합니다.

경로나 플래그 값이 하나의 argv 토큰으로 유지되어야 할 때는 구조화된 인수로 개별 ACP 에이전트 명령을 재정의하세요.

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "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](/ko/tools/plugin)를 참조하세요.

### 자동 의존성 설치

`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 도구를 호출하도록 하려면 전용 브리지를 활성화하세요.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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` 같은 선택된 내장 도구를
필요로 할 때 별도의 핵심 도구 브리지를 활성화하세요.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true
```

이 기능이 하는 일:

* `openclaw-tools`라는 내장 MCP 서버를 ACPX 세션
  부트스트랩에 주입합니다.
* 선택된 내장 OpenClaw 도구를 노출합니다. 초기 서버는 `cron`을 노출합니다.
* 핵심 도구 노출을 명시적이고 기본적으로 꺼진 상태로 유지합니다.

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

`acpx` Plugin은 기본적으로 내장 런타임 시작 및 제어 작업에 120초를 부여합니다.
이를 통해 Gemini CLI 같은 느린 하네스가 ACP 시작과 초기화를 완료할 충분한 시간을 갖습니다.
호스트에 다른 작업 제한이 필요하면 재정의하세요.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw config set plugins.entries.acpx.config.timeoutSeconds 180
```

런타임 턴은 `/acp timeout`을 포함한 OpenClaw 에이전트/실행 타임아웃을 사용합니다.
`sessions_spawn`은 호출별 타임아웃 재정의를 허용하지 않습니다. 이 값을 변경한 후
Gateway를 다시 시작하세요.

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 하네스 권한 간의
더 넓은 비교는 [권한 모드](/ko/tools/permission-modes)를 참조하세요.

### `permissionMode`

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

| 값               | 동작                                   |
| --------------- | ------------------------------------ |
| `approve-all`   | 모든 파일 쓰기와 셸 명령을 자동 승인합니다.            |
| `approve-reads` | 읽기만 자동 승인하며, 쓰기와 exec에는 프롬프트가 필요합니다. |
| `deny-all`      | 모든 권한 프롬프트를 거부합니다.                   |

### `nonInteractivePermissions`

권한 프롬프트가 표시되어야 하지만 대화형 TTY를 사용할 수 없을 때(ACP 세션에서는 항상 해당) 발생하는 일을 제어합니다.

| 값      | 동작                                      |
| ------ | --------------------------------------- |
| `fail` | `AcpRuntimeError`로 세션을 중단합니다. **(기본값)** |
| `deny` | 권한을 조용히 거부하고 계속합니다(우아한 성능 저하).          |

### 구성

Plugin 구성으로 설정하세요.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
```

이 값을 변경한 후 Gateway를 다시 시작하세요.

<Warning>
  OpenClaw의 기본값은 `permissionMode=approve-reads` 및 `nonInteractivePermissions=fail`입니다. 비대화형 ACP 세션에서는 권한 프롬프트를 트리거하는 모든 쓰기 또는 exec가 `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`로 실패할 수 있습니다.

  권한을 제한해야 한다면 세션이 충돌하는 대신 우아하게 성능 저하되도록 `nonInteractivePermissions`를 `deny`로 설정하세요.
</Warning>

## 관련 항목

* [ACP 에이전트](/ko/tools/acp-agents) — 개요, 운영자 런북, 개념
* [하위 에이전트](/ko/tools/subagents)
* [다중 에이전트 라우팅](/ko/concepts/multi-agent)