acp

OpenClaw 게이트웨이와 통신하는 Agent Client Protocol (ACP) 브리지를 실행합니다.

이 명령어는 stdio를 통해 IDE와 ACP로 통신하며, 프롬프트를 WebSocket을 통해 게이트웨이로 전달합니다. ACP 세션을 게이트웨이 세션 키에 매핑하여 관리합니다.

openclaw acp는 게이트웨이 기반 ACP 브리지이며, 완전한 ACP 네이티브 에디터 런타임이 아닙니다. 세션 라우팅, 프롬프트 전달, 기본적인 스트리밍 업데이트에 초점을 맞추고 있습니다.

호환성 매트릭스

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

알려진 제한 사항

  • loadSession은 저장된 사용자 및 어시스턴트 텍스트 히스토리를 재생하지만, 과거 도구 호출, 시스템 알림, 또는 더 풍부한 ACP 네이티브 이벤트 유형은 복원하지 않습니다.
  • 여러 ACP 클라이언트가 동일한 게이트웨이 세션 키를 공유하는 경우, 이벤트 및 취소 라우팅은 클라이언트별로 엄격하게 격리되지 않고 최선 노력으로 처리됩니다. 깔끔한 에디터 로컬 턴이 필요하다면 기본 격리된 acp:<uuid> 세션을 사용하세요.
  • 게이트웨이 정지 상태는 ACP 정지 사유로 변환되지만, 완전한 ACP 네이티브 런타임보다 표현력이 제한적입니다.
  • 초기 세션 제어는 현재 게이트웨이 설정의 집중된 하위 집합만 노출합니다: 사고 수준, 도구 상세도, 추론, 사용량 세부정보, 상승된 작업. 모델 선택과 실행 호스트 제어는 아직 ACP 구성 옵션으로 노출되지 않습니다.
  • session_info_update와 usage_update는 실시간 ACP 네이티브 런타임 계산이 아닌 게이트웨이 세션 스냅샷에서 파생됩니다. 사용량은 근사치이며, 비용 데이터를 포함하지 않고, 게이트웨이가 총 토큰 데이터를 최신으로 표시할 때만 전송됩니다.
  • 도구 추적 데이터는 최선 노력입니다. 브리지는 알려진 도구 인수/결과에 나타나는 파일 경로를 표시할 수 있지만, ACP 터미널이나 구조화된 파일 diff는 아직 전송하지 않습니다.

사용법

openclaw acp

# 원격 게이트웨이
openclaw acp --url wss://gateway-host:18789 --token <token>

# 원격 게이트웨이 (파일에서 토큰 읽기)
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# 기존 세션 키에 연결
openclaw acp --session agent:main:main

# 라벨로 연결 (이미 존재해야 함)
openclaw acp --session-label "support inbox"

# 첫 번째 프롬프트 전에 세션 키 재설정
openclaw acp --session agent:main:main --reset-session

ACP 클라이언트 (디버그)

내장 ACP 클라이언트를 사용하여 IDE 없이 브리지를 점검할 수 있습니다. ACP 브리지를 생성하고 대화형으로 프롬프트를 입력할 수 있습니다.

openclaw acp client

# 생성된 브리지를 원격 게이트웨이로 지정
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# 서버 명령어 오버라이드 (기본값: openclaw)
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

권한 모델 (클라이언트 디버그 모드):

  • 자동 승인은 허용 목록 기반이며 신뢰할 수 있는 핵심 도구 ID에만 적용됩니다.
  • read 자동 승인은 현재 작업 디렉토리(--cwd 설정 시)로 범위가 제한됩니다.
  • 알 수 없거나 핵심이 아닌 도구 이름, 범위 밖의 읽기, 위험한 도구는 항상 명시적 프롬프트 승인이 필요합니다.
  • 서버 제공 toolCall.kind는 신뢰하지 않는 메타데이터로 취급됩니다(인가 소스가 아님).

사용 방법

IDE(또는 다른 클라이언트)가 Agent Client Protocol을 사용하고 OpenClaw 게이트웨이 세션을 구동하려는 경우 ACP를 사용하세요.

  1. 게이트웨이가 실행 중인지 확인합니다(로컬 또는 원격).
  2. 게이트웨이 대상을 구성합니다(설정 또는 플래그).
  3. IDE에서 openclaw acp를 stdio를 통해 실행하도록 설정합니다.

설정 예시 (영구 저장):

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>
# 로컬 프로세스 안전을 위해 권장
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

에이전트 선택

ACP는 에이전트를 직접 선택하지 않습니다. 게이트웨이 세션 키로 라우팅합니다.

에이전트 범위 세션 키를 사용하여 특정 에이전트를 대상으로 지정하세요:

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

각 ACP 세션은 단일 게이트웨이 세션 키에 매핑됩니다. 하나의 에이전트에 여러 세션이 있을 수 있으며, 키나 라벨을 오버라이드하지 않는 한 ACP는 기본적으로 격리된 acp:<uuid> 세션을 사용합니다.

세션별 mcpServers는 브리지 모드에서 지원되지 않습니다. ACP 클라이언트가 newSession 또는 loadSession 중에 이를 전송하면, 브리지는 무시하지 않고 명확한 오류를 반환합니다.

acpx에서 사용 (Codex, Claude 등 ACP 클라이언트)

Codex나 Claude Code 같은 코딩 에이전트가 ACP를 통해 OpenClaw 봇과 통신하게 하려면, 내장 openclaw 타겟이 포함된 acpx를 사용하세요.

일반적인 흐름:

  1. 게이트웨이를 실행하고 ACP 브리지가 접근할 수 있는지 확인합니다.
  2. acpx openclaw을 openclaw acp로 지정합니다.
  3. 코딩 에이전트가 사용할 OpenClaw 세션 키를 대상으로 지정합니다.

예시:

# 기본 OpenClaw ACP 세션으로 일회성 요청
acpx openclaw exec "Summarize the active OpenClaw session state."

# 후속 턴을 위한 영구 이름 세션
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이 매번 특정 게이트웨이와 세션 키를 대상으로 하도록 하려면, ~/.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 스트림을 깔끔하게 유지하기 위해 개발 러너 대신 직접 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": {}
    }
  }
}

특정 게이트웨이 또는 에이전트를 대상으로 하려면:

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

Zed에서 Agent 패널을 열고 “OpenClaw ACP”를 선택하여 스레드를 시작하세요.

세션 매핑

기본적으로 ACP 세션은 acp: 접두사가 붙은 격리된 게이트웨이 세션 키를 받습니다. 알려진 세션을 재사용하려면 세션 키 또는 라벨을 전달하세요:

  • --session <key>: 특정 게이트웨이 세션 키를 사용합니다.
  • --session-label <label>: 라벨로 기존 세션을 확인합니다.
  • --reset-session: 해당 키에 대해 새로운 세션 ID를 생성합니다(같은 키, 새 트랜스크립트).

ACP 클라이언트가 메타데이터를 지원하는 경우 세션별로 오버라이드할 수 있습니다:

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

세션 키에 대해 더 알아보려면 /concepts/session을 참조하세요.

옵션

  • --url <url>: 게이트웨이 WebSocket URL (구성된 경우 gateway.remote.url이 기본값).
  • --token <token>: 게이트웨이 인증 토큰.
  • --token-file <path>: 파일에서 게이트웨이 인증 토큰 읽기.
  • --password <password>: 게이트웨이 인증 비밀번호.
  • --password-file <path>: 파일에서 게이트웨이 인증 비밀번호 읽기.
  • --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)를 사용하는 것이 좋습니다.
  • 게이트웨이 인증 해석은 다른 게이트웨이 클라이언트에서 사용하는 공유 계약을 따릅니다:
    • 로컬 모드: env (OPENCLAW_GATEWAY_*) -> gateway.auth.* -> gateway.remote.*는 gateway.auth.*가 설정되지 않은 경우에만 폴백 (구성되었지만 해석되지 않은 로컬 SecretRef는 닫힌 상태로 실패)
    • 원격 모드: gateway.remote.*와 원격 우선순위 규칙에 따른 env/config 폴백
    • --url은 오버라이드에 안전하며 암묵적 config/env 자격 증명을 재사용하지 않습니다; 명시적 --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: 클라이언트 상세 로깅.
arrow_back
이전
Cli
다음
Agent
arrow_forward