OpenClaw 코드 리팩토링 가이드: 600줄 이상의 코드 최적화

여러 플러그인을 개발하다 보면 비슷한 로직을 계속해서 작성하게 되는 경우가 많아요. 특히 설정이나 보안 관련 코드는 구조가 거의 똑같은데도 매번 새로 만들다 보니 유지보수가 힘들어지곤 하죠.

이런 중복 코드를 정리하면 프로젝트의 복잡도를 크게 낮출 수 있어요. 예상되는 코드 감소량(LOC), 안전성, 그리고 영향 범위를 기준으로 정리한 리팩토링 백로그를 공유해 드릴게요.

1. 채널 플러그인 설정 및 보안 스캐폴딩

가장 가치가 높은 클러스터예요. 여러 채널 플러그인에서 다음과 같은 형태가 반복되고 있어요.

config.listAccountIds
config.resolveAccount
config.defaultAccountId
config.setAccountEnabled
config.deleteAccount
config.describeAccount
security.resolveDmPolicy

참고하기 좋은 예시:

extensions/telegram/src/channel.ts
extensions/googlechat/src/channel.ts
extensions/slack/src/channel.ts
extensions/discord/src/channel.ts
extensions/matrix/src/channel.ts
extensions/irc/src/channel.ts
extensions/signal/src/channel.ts
extensions/mattermost/src/channel.ts

추출할 수 있는 형태:

buildChannelConfigAdapter(...)
buildMultiAccountConfigAdapter(...)
buildDmSecurityAdapter(...)

예상 절감 효과:

약 250-450 LOC

리스크:

중간. 각 채널마다 isConfigured 방식, 경고 메시지, 정규화 로직이 조금씩 달라요.

2. Extension runtime 싱글톤 보일러플레이트

매우 안전한 작업이에요. 거의 모든 extension이 동일한 runtime 홀더를 가지고 있어요.

let runtime: PluginRuntime | null = null
setXRuntime
getXRuntime

참고하기 좋은 예시:

extensions/telegram/src/runtime.ts
extensions/matrix/src/runtime.ts
extensions/slack/src/runtime.ts
extensions/discord/src/runtime.ts
extensions/whatsapp/src/runtime.ts
extensions/imessage/src/runtime.ts
extensions/twitch/src/runtime.ts

특수한 변형 사례:

extensions/bluebubbles/src/runtime.ts
extensions/line/src/runtime.ts
extensions/synology-chat/src/runtime.ts

추출할 수 있는 형태:

createPluginRuntimeStore<T>(errorMessage)

예상 절감 효과:

약 180-260 LOC

리스크:

낮음

3. 온보딩 프롬프트 및 설정 패치 단계

영향 범위가 넓은 영역이에요. 많은 온보딩 파일에서 다음 로직이 반복됩니다.

account id 확인
allowlist 항목 프롬프트
allowFrom 병합
DM 정책 설정
secrets 프롬프트
최상위 설정 vs 계정 범위 설정 패치

참고하기 좋은 예시:

extensions/bluebubbles/src/onboarding.ts
extensions/googlechat/src/onboarding.ts
extensions/msteams/src/onboarding.ts
extensions/zalo/src/onboarding.ts
extensions/zalouser/src/onboarding.ts
extensions/nextcloud-talk/src/onboarding.ts
extensions/matrix/src/onboarding.ts
extensions/irc/src/onboarding.ts

기존 헬퍼 위치:

src/channels/plugins/onboarding/helpers.ts

추출할 수 있는 형태:

promptAllowFromList(...)
buildDmPolicyAdapter(...)
applyScopedAccountPatch(...)
promptSecretFields(...)

예상 절감 효과:

약 300-600 LOC

리스크:

중간. 너무 과하게 일반화하기 쉬우니, 헬퍼를 좁은 범위에서 조합 가능한 형태로 유지해야 해요.

4. 다중 계정 설정 스키마 프래그먼트

여러 extension에 걸쳐 스키마 프래그먼트가 반복되고 있어요.

공통 패턴:

const allowFromEntry = z.union([z.string(), z.number()])
계정 스키마 및 추가 항목:
- accounts: z.object({}).catchall(accountSchema).optional()
- defaultAccount: z.string().optional()
반복되는 DM/그룹 필드
반복되는 markdown/tool 정책 필드

참고하기 좋은 예시:

extensions/bluebubbles/src/config-schema.ts
extensions/zalo/src/config-schema.ts
extensions/zalouser/src/config-schema.ts
extensions/matrix/src/config-schema.ts
extensions/nostr/src/config-schema.ts

추출할 수 있는 형태:

AllowFromEntrySchema
buildMultiAccountChannelSchema(accountSchema)
buildCommonDmGroupFields(...)

예상 절감 효과:

약 120-220 LOC

리스크:

낮음에서 중간 사이. 일부 스키마는 단순하지만 일부는 특수해요.

5. Webhook 및 모니터 라이프사이클 시작

중간 정도의 가치를 지닌 클러스터예요. 반복되는 startAccount 및 모니터 설정 패턴은 다음과 같아요.

계정 확인
webhook 경로 계산
시작 로그 기록
모니터 시작
abort 대기
정리 작업
상태 싱크 업데이트

참고하기 좋은 예시:

extensions/googlechat/src/channel.ts
extensions/bluebubbles/src/channel.ts
extensions/zalo/src/channel.ts
extensions/telegram/src/channel.ts
extensions/nextcloud-talk/src/channel.ts

기존 헬퍼 위치:

src/plugin-sdk/channel-lifecycle.ts

추출할 수 있는 형태:

계정 모니터 라이프사이클용 헬퍼
webhook 기반 계정 시작용 헬퍼

예상 절감 효과:

약 150-300 LOC

리스크:

중간에서 높음 사이. Transport 세부 사항이 급격히 달라질 수 있어요.

6. 소규모 코드 복제 정리

리스크가 낮은 정리 작업들이에요.

예시:

중복된 gateway argv 감지:
- src/infra/gateway-lock.ts
- src/cli/daemon-cli/lifecycle.ts
중복된 포트 진단 렌더링:
- src/cli/daemon-cli/restart-health.ts
중복된 session-key 생성:
- src/web/auto-reply/monitor/broadcast.ts

예상 절감 효과:

약 30-60 LOC

리스크:

낮음

테스트 클러스터

LINE webhook 이벤트 피스처

참고하기 좋은 예시:

src/line/bot-handlers.test.ts

추출 가능한 항목:

makeLineEvent(...)
runLineEvent(...)
makeLineAccount(...)

예상 절감 효과:

약 120-180 LOC

Telegram 네이티브 커맨드 권한 매트릭스

참고하기 좋은 예시:

src/telegram/bot-native-commands.group-auth.test.ts
src/telegram/bot-native-commands.plugin-auth.test.ts

추출 가능한 항목:

forum context 빌더
거부 메시지 assertion 헬퍼
테이블 기반 권한 케이스

예상 절감 효과:

약 80-140 LOC

Zalo 라이프사이클 설정

참고하기 좋은 예시:

extensions/zalo/src/monitor.lifecycle.test.ts

추출 가능한 항목:

공유 모니터 설정 하네스

예상 절감 효과:

약 50-90 LOC

Brave llm-context 지원하지 않는 옵션 테스트

참고하기 좋은 예시:

src/agents/tools/web-tools.enabled-defaults.test.ts

추출 가능한 항목:

it.each(...) 매트릭스

예상 절감 효과:

약 30-50 LOC

권장 순서

Runtime 싱글톤 보일러플레이트
소규모 코드 복제 정리
설정 및 보안 빌더 추출
테스트 헬퍼 추출
온보딩 단계 추출
모니터 라이프사이클 헬퍼 추출

AI Setup Assistant

다음 단계

OpenClaw Expert

아직 막혀 있나요?

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