OpenClaw ACP 브리지 설정: IDE와 게이트웨이 즉시 연결

OpenClaw Gateway와 통신하는 Agent Client Protocol (ACP) 브릿지를 실행해요.

이 명령어는 IDE를 위해 stdio를 통해 ACP로 통신하고, WebSocket을 통해 Gateway로 프롬프트를 전달해요. ACP 세션을 Gateway 세션 키에 매핑된 상태로 유지해 줍니다.

openclaw acp는 Gateway 기반의 ACP 브릿지이며, 완전한 ACP 네이티브 에디터 런타임은 아니에요. 세션 라우팅 및 프롬프트 전달과 더불어 기본적인 스트리밍 업데이트 기능에 집중하고 있어요.

ACP 하네스 세션을 호스팅하는 대신 외부 MCP 클라이언트가 OpenClaw 채널 대화와 직접 통신하게 하려면 openclaw mcp serve를 사용하세요.

호환성 매트릭스

ACP 영역	상태	참고 사항
`initialize`, `newSession`, `prompt`, `cancel`	구현됨	stdio를 통해 Gateway 채팅/전송 및 중단(abort)까지 이어지는 핵심 브릿지 흐름이에요.
`listSessions`, 슬래시 명령어	구현됨	세션 목록은 Gateway 세션 상태를 기준으로 작동하며, 명령어는 `available_commands_update`를 통해 안내돼요.
`loadSession`	부분 지원	ACP 세션을 Gateway 세션 키에 다시 바인딩하고 저장된 사용자 및 어시스턴트 텍스트 히스토리를 재생해요. 도구 및 시스템 히스토리는 아직 재구성되지 않아요.
프롬프트 콘텐츠 (`text`, 임베디드 `resource`, 이미지)	부분 지원	텍스트와 리소스는 채팅 입력으로 평탄화(flatten)되며, 이미지는 Gateway 첨부 파일이 돼요.
세션 모드	부분 지원	`session/set_mode`를 지원하며, 브릿지는 생각 수준(thought level), 도구 상세도(tool verbosity), 추론(reasoning), 사용량 상세 정보, 권한 상승 작업에 대한 초기 Gateway 기반 세션 컨트롤을 노출해요. 더 넓은 범위의 ACP 네이티브 모드 및 설정 영역은 아직 범위 밖이에요.
세션 정보 및 사용량 업데이트	부분 지원	브릿지는 캐시된 Gateway 세션 스냅샷을 바탕으로 `session_info_update`와 최선의 `usage_update` 알림을 보냅니다. 사용량은 근사치이며 Gateway 토큰 합계가 최신으로 표시될 때만 전송돼요.
도구 스트리밍	부분 지원	`tool_call` / `tool_call_update` 이벤트에는 원본 I/O와 텍스트 내용이 포함되며, Gateway 도구 인자나 결과에 노출된 경우 최선을 다해 파일 위치를 제공해요. 임베디드 터미널이나 더 풍부한 diff 네이티브 출력은 아직 노출되지 않아요.
세션별 MCP 서버 (`mcpServers`)	미지원	브릿지 모드는 세션별 MCP 서버 요청을 거부해요. 대신 OpenClaw Gateway나 에이전트에서 MCP를 설정하세요.
클라이언트 파일 시스템 메서드 (`fs/read_text_file`, `fs/write_text_file`)	미지원	브릿지는 ACP 클라이언트 파일 시스템 메서드를 호출하지 않아요.
클라이언트 터미널 메서드 (`terminal/*`)	미지원	브릿지는 ACP 클라이언트 터미널을 생성하거나 도구 호출을 통해 터미널 ID를 스트리밍하지 않아요.
세션 플랜 / 생각(thought) 스트리밍	미지원	브릿지는 현재 출력 텍스트와 도구 상태만 내보내며, ACP 플랜이나 생각 업데이트는 제공하지 않아요.

알려진 제한 사항

loadSession은 저장된 사용자 및 어시스턴트 텍스트 히스토리를 재생하지만, 과거의 도구 호출 및 시스템 알림, 또는 더 풍부한 ACP 네이티브 이벤트 유형을 재구성하지는 않아요.
여러 ACP 클라이언트가 동일한 Gateway 세션 키를 공유하는 경우, 이벤트 및 취소 라우팅은 클라이언트별로 엄격하게 격리되기보다는 최선형(best-effort)으로 작동해요. 깨끗한 에디터 로컬 턴이 필요한 경우에는 기본으로 제공되는 격리된 acp:<uuid> 세션을 사용하는 것이 좋아요.
Gateway 중단 상태는 ACP 중단 사유로 변환되지만, 이 매핑은 완전한 ACP 네이티브 런타임보다는 표현력이 부족할 수 있어요.
초기 세션 컨트롤은 현재 Gateway 설정의 핵심 하위 집합인 생각 수준, 도구 상세도, 추론, 사용량 상세 정보, 권한 상승 작업만을 노출해요. 모델 선택 및 실행 호스트 컨트롤은 아직 ACP 설정 옵션으로 노출되지 않았어요.
session_info_update 및 usage_update는 실시간 ACP 네이티브 런타임 계정이 아니라 Gateway 세션 스냅샷에서 파생돼요. 사용량은 근사치이며 비용 데이터를 포함하지 않고, Gateway가 전체 토큰 데이터를 최신으로 표시할 때만 내보내져요.
도구 따라가기(follow-along) 데이터는 최선형으로 제공돼요. 브릿지는 알려진 도구 인자나 결과에 나타나는 파일 경로를 노출할 수 있지만, 아직 ACP 터미널이나 구조화된 파일 diff를 내보내지는 않아요.

사용법

openclaw acp

# Remote Gateway
openclaw acp --url wss://gateway-host:18789 --token <token>

# Remote Gateway (token from file)
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Attach to an existing session key
openclaw acp --session agent:main:main

# Attach by label (must already exist)
openclaw acp --session-label "support inbox"

# Reset the session key before the first prompt
openclaw acp --session agent:main:main --reset-session

ACP client (디버그)

IDE 없이 브릿지가 정상적으로 작동하는지 확인하고 싶다면 내장된 ACP client를 사용해 보세요. ACP 브릿지를 실행하고 대화형으로 프롬프트를 직접 입력할 수 있어요.

openclaw acp client

# Point the spawned bridge at a remote Gateway
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Override the server command (default: openclaw)
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

클라이언트 디버그 모드에서의 권한 모델(Permission model)은 다음과 같이 작동해요:

자동 승인(Auto-approval)은 allowlist 기반이며, 신뢰할 수 있는 핵심 tool ID에만 적용돼요.
read 자동 승인은 현재 작업 디렉토리(--cwd 설정 시 해당 경로)로 범위가 제한돼요.
ACP는 좁은 범위의 읽기 전용 클래스만 자동으로 승인해요. 활성화된 cwd 내의 read 호출과 읽기 전용 검색 도구(search, web_search, memory_search)가 여기에 해당해요. 알 수 없거나 핵심 도구가 아닌 경우, 범위를 벗어난 읽기, 실행(exec) 가능 도구, 제어 평면(control-plane) 도구, 변경(mutating) 도구, 그리고 대화형 흐름은 항상 명시적인 프롬프트 승인이 필요해요.
서버에서 제공하는 toolCall.kind는 신뢰할 수 없는 메타데이터로 취급되며, 권한 인증 소스로 사용하지 않아요.
이 ACP 브릿지 정책은 ACPX harness 권한과는 별개예요. 만약 acpx 백엔드를 통해 OpenClaw를 실행한다면, plugins.entries.acpx.config.permissionMode=approve-all 설정이 해당 harness 세션에 대한 비상용 스위치 역할을 해요.

사용 방법

IDE(또는 다른 클라이언트)가 Agent Client Protocol을 지원하고, 이를 통해 OpenClaw Gateway 세션을 구동하고 싶을 때 ACP를 사용하세요.

Gateway가 실행 중인지 확인하세요 (로컬 또는 원격).
Gateway 타겟을 설정하세요 (config 또는 flags).
IDE가 stdio를 통해 openclaw acp를 실행하도록 설정하세요.

설정 예시 (저장됨):

openclaw config set gateway.remote.url wss://gateway-host:18789
openclaw config set gateway.remote.token <token>

직접 실행 예시 (설정 저장 안 함):

openclaw acp --url wss://gateway-host:18789 --token <token>
# preferred for local process safety
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

에이전트 선택하기

ACP는 에이전트를 직접 선택하지 않아요. 대신 Gateway session key를 통해 라우팅을 처리합니다.

특정 에이전트를 타겟팅하려면 에이전트 범위의 session keys를 사용하세요:

openclaw acp --session agent:main:main
openclaw acp --session agent:design:main
openclaw acp --session agent:qa:bug-123

각 ACP 세션은 단일 Gateway session key에 매핑됩니다. 하나의 에이전트가 여러 세션을 가질 수 있으며, key나 label을 별도로 지정하지 않으면 ACP는 기본적으로 격리된 acp:<uuid> 세션을 사용합니다.

브릿지 모드에서는 세션별 mcpServers를 지원하지 않아요. 만약 ACP 클라이언트가 newSession이나 loadSession 중에 이를 전송하면, 브릿지는 이를 조용히 무시하는 대신 명확한 에러를 반환합니다.

ACPX 기반 세션에서 OpenClaw 플러그인 도구를 사용하고 싶다면, 세션마다 mcpServers를 전달하려고 시도하는 대신 Gateway 측의 ACPX 플러그인 브릿지를 활성화하세요. ACP Agents를 참고하세요.

`acpx`에서 사용하기 (Codex, Claude, 기타 ACP 클라이언트)

Codex나 Claude Code 같은 코딩 에이전트가 ACP를 통해 OpenClaw 봇과 통신하게 하고 싶다면, acpx의 내장 openclaw 타겟을 사용하면 돼요.

일반적인 흐름은 다음과 같습니다:

Gateway를 실행하고 ACP 브릿지가 연결 가능한지 확인하세요.
acpx openclaw가 openclaw acp를 가리키도록 설정합니다.
코딩 에이전트가 사용할 OpenClaw 세션 키를 지정하세요.

예시:

# One-shot request into your default OpenClaw ACP session
acpx openclaw exec "Summarize the active OpenClaw session state."

# Persistent named session for follow-up turns
acpx openclaw sessions ensure --name codex-bridge
acpx openclaw -s codex-bridge --cwd /path/to/repo \
  "Ask my OpenClaw work agent for recent context relevant to this repo."

만약 acpx openclaw가 매번 특정 Gateway와 세션 키를 타겟팅하도록 설정하고 싶다면, ~/.acpx/config.json에서 openclaw 에이전트 명령어를 덮어쓰면 됩니다:

{
  "agents": {
    "openclaw": {
      "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"
    }
  }
}

로컬 레포지토리에 OpenClaw를 체크아웃해서 사용하는 경우에는 ACP 스트림을 깨끗하게 유지할 수 있도록 dev runner 대신 직접 CLI 엔트리포인트를 사용하세요. 예를 들면 다음과 같습니다:

env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...

이 방법은 Codex, Claude Code 또는 다른 ACP 지원 클라이언트가 터미널을 스크래핑하지 않고도 OpenClaw 에이전트로부터 컨텍스트 정보를 가져올 수 있는 가장 쉬운 방법이에요.

Zed 에디터 설정

~/.config/zed/settings.json에 커스텀 ACP 에이전트를 추가하거나 Zed의 설정 UI를 사용해 보세요:

{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": ["acp"],
      "env": {}
    }
  }
}

특정 Gateway나 에이전트를 타겟팅하려면 다음과 같이 설정합니다:

{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": [
        "acp",
        "--url",
        "wss://gateway-host:18789",
        "--token",
        "<token>",
        "--session",
        "agent:design:main"
      ],
      "env": {}
    }
  }
}

Zed에서 에이전트 패널을 열고 “OpenClaw ACP”를 선택하면 새로운 스레드를 시작할 수 있어요.

AI Setup Assistant

세션 매핑

기본적으로 ACP 세션은 acp: 접두사가 붙은 격리된 Gateway 세션 키를 할당받아요. 기존 세션을 다시 사용하고 싶다면 세션 키나 라벨을 전달하면 돼요.

--session <key>: 특정 Gateway 세션 키를 사용해요.
--session-label <label>: 라벨을 통해 기존 세션을 찾아요.
--reset-session: 해당 키에 대해 새로운 세션 ID를 생성해요 (키는 같지만 새로운 트랜스크립트가 시작돼요).

ACP 클라이언트가 메타데이터를 지원한다면 세션별로 설정을 덮어쓸 수 있어요.

{
  "_meta": {
    "sessionKey": "agent:main:main",
    "sessionLabel": "support inbox",
    "resetSession": true
  }
}

세션 키에 대해 더 자세히 알고 싶다면 /concepts/session을 확인해 보세요.

옵션

--url <url>: Gateway WebSocket URL이에요 (설정된 경우 기본값은 gateway.remote.url이에요).
--token <token>: Gateway 인증 토큰이에요.
--token-file <path>: 파일에서 Gateway 인증 토큰을 읽어와요.
--password <password>: Gateway 인증 비밀번호예요.
--password-file <path>: 파일에서 Gateway 인증 비밀번호를 읽어와요.
--session <key>: 기본 세션 키예요.
--session-label <label>: 찾으려는 기본 세션 라벨이에요.
--require-existing: 세션 키나 라벨이 존재하지 않으면 실패 처리를 해요.
--reset-session: 처음 사용하기 전에 세션 키를 초기화해요.
--no-prefix-cwd: 프롬프트에 작업 디렉토리 접두사를 붙이지 않아요.
--verbose, -v: stderr로 상세 로그를 출력해요.

보안 주의 사항이에요.

--token과 --password는 일부 시스템의 로컬 프로세스 목록에서 노출될 수 있어요.
--token-file/--password-file이나 환경 변수(OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD)를 사용하는 게 좋아요.
Gateway 인증 해결 방식은 다른 Gateway 클라이언트와 동일한 규칙을 따라요.
- 로컬 모드: 환경 변수(OPENCLAW_GATEWAY_*) -> gateway.auth.* -> gateway.remote.* 순서로 적용되며, gateway.auth.*가 설정되지 않은 경우에만 fallback이 작동해요 (설정되었지만 해결되지 않은 로컬 SecretRefs는 실패로 간주해요).
- 원격 모드: 원격 우선순위 규칙에 따라 환경 변수/설정 fallback이 포함된 gateway.remote.*를 사용해요.
- --url은 덮어쓰기에 안전하며 암시적인 설정이나 환경 변수 자격 증명을 재사용하지 않아요. 명시적으로 --token/--password(또는 파일 변체)를 전달해야 해요.
ACP 런타임 백엔드 자식 프로세스는 OPENCLAW_SHELL=acp를 전달받아요. 이를 통해 컨텍스트별 쉘/프로필 규칙을 설정할 수 있어요.
openclaw acp client는 생성된 브리지 프로세스에 OPENCLAW_SHELL=acp-client를 설정해요.

`acp client` 옵션

--cwd <dir>: ACP 세션의 작업 디렉토리예요.
--server <command>: ACP 서버 명령어예요 (기본값: openclaw).
--server-args <args...>: ACP 서버에 전달할 추가 인자들이에요.
--server-verbose: ACP 서버에서 상세 로깅을 활성화해요.
--verbose, -v: 상세 클라이언트 로그를 출력해요.

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.