1. 핵심 문제 개요

OpenClaw 기반 AI 애플리케이션에서 자주 발생하는 세 가지 런타임 이슈:

• 컨텍스트 엔진 플러그인이 hook-only로 오분류됨
• ACP 세션에서 동일 메시지가 중복 전송됨
• Discord 스레드에서 thread_binding_invalid 오류 발생

patch-oc는 Deno 기반 핫픽스 도구로, OpenClaw의 dist/ 디렉터리를 직접 수정하여 즉각적인 문제 해결을 제공합니다. v1.0.8 버전은 세 가지 문제를 독립적으로 해결합니다.

2. 패치 작동 원리

2.1 플러그인 분류 수정

문제: 컨텍스트 엔진 플러그인이 잘못 분류되어 관리 인터페이스 오동작
원인: buildCapabilityEntries 함수의 컨텍스트 엔진 인식 누락
해결: 플러그인 종류(kind) 확인 후 컨텍스트 처리 능력 명시적 추가

2.2 메시지 중복 전송 수정

문제: ACP 응답 후 동일 내용 재전송
원인: shouldTreatDeliveredTextAsVisible 함수가 일반 블록을 "비가시"로 오판정
해결: 비도구(non-tool) 텍스트 블록을 가시 텍스트로 정확히 인식하도록 조건 수정

2.3 스레드 바인딩 오류 수정

문제: Discord 스레드에서 세션 바인딩 실패
원인: channel:<id> 형식의 대화 ID 처리 불가
해결: 스레드 바인딩 관리자에 ID 형식 정규화 로직 추가

3. 필수 환경 설정

3.1 Deno 런타임 설치

# macOS/Linux
curl -fsSL https://deno.land/install.sh | sh

# Homebrew
brew install deno

3.2 OpenClaw 전역 설치 확인

openclaw --version
# 미설치 시
npm install -g openclaw

3.3 파일 권한 검증

node_modules/openclaw/dist/ 디렉터리에 쓰기 권한 필요. sudo 설치 시 소유권 변경:

sudo chown -R $(whoami) /설치/경로/node_modules/openclaw

4. 패치 적용 절차

4.1 저장소 복제

git clone https://github.com/zhuisDEV/patch-oc.git
cd patch-oc

4.2 사전 점검 실행

./check.sh --part all --verbose

4.3 패치 적용

# 전체 적용
./apply.sh --part all

# 선택 적용 (예: 메시지 중복 패치)
./apply.sh --part 2

4.4 적용 결과 검증

• 분류 패치: openclaw plugins inspect <id> 실행 후 정확한 분류 확인
• 중복 메시지 패치: 이전 오류 발생 시나리오 테스트
• 스레드 바인딩 패치: Discord 스레드에서 ACP 세션 생성 시도

4.5 자동화 통합

mkdir -p ~/.openclaw/lws/vendor
git clone https://github.com/zhuisDEV/patch-oc.git ~/.openclaw/lws/vendor/patch-oc

에이전트 명령어: cd ~/.openclaw/lws/vendor/patch-oc && ./check.sh --part all && ./apply.sh --part all

5. 고급 사용법

5.1 Deno CLI 직접 실행

deno run -A ./patch_oc.ts --check --part context-engine-capability

5.2 사용자 정의 경로 지정

./apply.sh --part 1 --openclaw-root /사용자/정의/경로

5.3 문제 해결

• 권한 오류: OpenClaw 설치 경로 소유권 확인
• SKIPPED 상태: OpenClaw 버전 호환성 점검
• 적용 후 오류: .bak-* 백업 파일로 복원