openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh ko translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-23 14:59:29 +00:00
parent effa7d3771
commit cf0de77e79
4 changed files with 783 additions and 782 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

126
docs/ko/ci.md
View File

@ -1,107 +1,101 @@
---
read_when:
- 특정 CI 작업이 왜 실행되었는지 또는 왜 실행되지 않았는지 이해해야 합니다.
- 실패한 GitHub Actions 체크를 디버깅하고 있습니다.
summary: CI 작업 그래프, 범위 게이트, 그리고 이에 대응하는 로컬 명령어들
- CI 작업이 실행되었거나 실행되지 않은 이유를 파악해야 합니다.
- 실패한 GitHub Actions 검사를 디버깅하고 있습니다.
summary: CI 작업 그래프, 범위 게이트, 및 로컬 명령어 대응 항목
title: CI 파이프라인
x-i18n:
generated_at: "2026-04-23T13:59:33Z"
generated_at: "2026-04-23T14:55:17Z"
model: gpt-5.4
provider: openai
source_hash: c5a8ea0d8e428826169b0e6aced1caeb993106fe79904002125ace86b48cae1f
source_hash: e9a03440ae28a15167fc08d9c66bb1fd719ddfa1517aaecb119c80f2ad826c0d
source_path: ci.md
workflow: 15
---
# CI 파이프라인
CI는 `main`에 대한 모든 push와 모든 pull request에서 실행됩니다. 관련 없는 영역만 변경된 경우 비용이 큰 작업을 건너뛰도록 스마트 스코핑을 사용합니다.
CI는 `main`에 대한 모든 푸시와 모든 pull request에서 실행됩니다. 스마트 범위 지정을 사용해 변경된 영역이 관련 없는 경우 비용이 큰 작업을 건너뜁니다.
QA Lab에는 메인 스마트 스코프 워크플로 밖에 전용 CI 레인이 있습니다.
`Parity gate` 워크플로는 일치하는 PR 변경과 수동 디스패치에서 실행되며,
비공개 QA 런타임을 빌드하고 mock GPT-5.4 및 Opus 4.6
agentic pack을 비교합니다. `QA-Lab - All Lanes` 워크플로는 `main`에서 매일 밤 실행되고
수동 디스패치로도 실행되며, mock parity gate, live Matrix 레인, live
Telegram 레인을 병렬 작업으로 팬아웃합니다. live 작업은 `qa-live-shared`
environment를 사용하고, Telegram 레인은 Convex lease를 사용합니다. `OpenClaw Release
Checks`도 릴리스 승인 전에 동일한 QA Lab 레인들을 실행합니다.
QA Lab에는 메인 스마트 범위 워크플로 밖에 전용 CI 레인이 있습니다. `Parity gate` 워크플로는 일치하는 PR 변경 사항과 수동 실행에서 동작하며, 비공개 QA 런타임을 빌드하고 mock GPT-5.4 및 Opus 4.6 agentic pack을 비교합니다. `QA-Lab - All Lanes` 워크플로는 `main`에서 매일 밤 실행되고 수동 실행도 가능하며, mock parity gate, live Matrix lane, live Telegram lane을 병렬 작업으로 fan-out합니다. live 작업은 `qa-live-shared` environment를 사용하고, Telegram lane은 Convex lease를 사용합니다. `OpenClaw Release Checks`도 릴리스 승인 전에 동일한 QA Lab 레인을 실행합니다.
## 작업 개요
| 작업 | 목적 | 실행 시점 |
| -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------ |
| `preflight` | docs-only 변경, 변경된 범위, 변경된 extension을 감지하고 CI manifest를 빌드 | 초안이 아닌 모든 push 및 PR에서 항상 |
| `security-scm-fast` | `zizmor`를 통한 private key 감지 및 워크플로 감사 | 초안이 아닌 모든 push 및 PR에서 항상 |
| `security-dependency-audit` | npm advisory에 대한 dependency-free 프로덕션 lockfile 감사 | 초안이 아닌 모든 push 및 PR에서 항상 |
| `security-fast` | 빠른 보안 작업을 위한 필수 aggregate | 초안이 아닌 모든 push 및 PR에서 항상 |
| `build-artifacts` | `dist/`, Control UI, 빌드 산출물 검사, 재사용 가능한 다운스트림 산출물 빌드 | Node 관련 변경 시 |
| `checks-fast-core` | bundled/plugin-contract/protocol 검사 같은 빠른 Linux 정확성 레인 | Node 관련 변경 시 |
| `checks-fast-contracts-channels` | 안정적인 aggregate 체크 결과를 위한 샤딩된 채널 contract 검사 | Node 관련 변경 시 |
| `checks-node-extensions` | extension 스위트 전반에 걸친 전체 bundled-plugin 테스트 샤드 | Node 관련 변경 시 |
| `checks-node-core-test` | 채널, bundled, contract, extension 레인을 제외한 코어 Node 테스트 샤드 | Node 관련 변경 시 |
| `extension-fast` | 변경된 bundled plugin만을 대상으로 한 집중 테스트 | extension 변경이 있는 pull request |
| `check` | 샤딩된 메인 로컬 게이트 대응: 프로덕션 타입, lint, 가드, 테스트 타입, 엄격한 smoke | Node 관련 변경 시 |
| `check-additional` | 아키텍처, 경계, extension-surface 가드, package-boundary, gateway-watch 샤드 | Node 관련 변경 시 |
| `build-smoke` | 빌드된 CLI smoke 테스트 및 시작 메모리 smoke | Node 관련 변경 시 |
| `checks` | 빌드 산출물 채널 테스트 및 push 전용 Node 22 호환성 검증기 | Node 관련 변경 시 |
| `check-docs` | 문서 포맷팅, lint, 깨진 링크 검사 | docs 변경 시 |
| `skills-python` | Python 기반 Skills에 대한 Ruff + pytest | Python skill 관련 변경 시 |
| `checks-windows` | Windows 전용 테스트 레인 | Windows 관련 변경 시 |
| `macos-node` | 공유 빌드 산출물을 사용하는 macOS TypeScript 테스트 레인 | macOS 관련 변경 시 |
| `macos-swift` | macOS 앱에 대한 Swift lint, 빌드, 테스트 | macOS 관련 변경 시 |
| `android` | 두 flavor 모두에 대한 Android 단위 테스트 및 디버그 APK 하나 빌드 | Android 관련 변경 시 |
| 작업 | 목적 | 실행 시점 |
| --------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------- |
| `preflight` | docs-only 변경, 변경된 범위, 변경된 extension을 감지하고 CI manifest를 빌드 | 초안이 아닌 모든 push 및 PR에서 항상 실행 |
| `security-scm-fast` | `zizmor`를 통한 private key 탐지 및 워크플로 감사 | 초안이 아닌 모든 push 및 PR에서 항상 실행 |
| `security-dependency-audit` | npm advisory에 대한 dependency-free 프로덕션 lockfile 감사 | 초안이 아닌 모든 push 및 PR에서 항상 실행 |
| `security-fast` | 빠른 보안 작업용 필수 aggregate | 초안이 아닌 모든 push 및 PR에서 항상 실행 |
| `build-artifacts` | `dist/`, Control UI, built-artifact 검사, 재사용 가능한 downstream artifact 빌드 | Node 관련 변경 |
| `checks-fast-core` | bundled/plugin-contract/protocol 검사 같은 빠른 Linux 정확성 레인 | Node 관련 변경 |
| `checks-fast-contracts-channels` | 안정적인 aggregate check 결과를 갖는 shard된 channel contract 검사 | Node 관련 변경 |
| `checks-node-extensions` | extension 전체에 대한 전체 bundled-plugin 테스트 shard | Node 관련 변경 |
| `checks-node-core-test` | channel, bundled, contract, extension 레인을 제외한 core Node 테스트 shard | Node 관련 변경 |
| `extension-fast` | 변경된 bundled plugin만 대상으로 하는 집중 테스트 | extension 변경이 있는 pull request |
| `check` | shard된 메인 로컬 게이트 대응 항목: 프로덕션 타입, lint, guard, 테스트 타입, strict smoke | Node 관련 변경 |
| `check-additional` | 아키텍처, 경계, extension-surface guard, package-boundary, gateway-watch shard | Node 관련 변경 |
| `build-smoke` | built-CLI smoke 테스트 및 startup-memory smoke | Node 관련 변경 |
| `checks` | built-artifact channel 테스트와 push 전용 Node 22 호환성에 대한 verifier | Node 관련 변경 |
| `check-docs` | 문서 포맷팅, lint, 깨진 링크 검사 | 문서 변경 |
| `skills-python` | Python 기반 Skills용 Ruff + pytest | Python Skills 관련 변경 |
| `checks-windows` | Windows 전용 테스트 레인 | Windows 관련 변경 |
| `macos-node` | 공유 built artifact를 사용하는 macOS TypeScript 테스트 레인 | macOS 관련 변경 |
| `macos-swift` | macOS 앱용 Swift lint, 빌드, 테스트 | macOS 관련 변경 |
| `android` | 두 flavor 모두에 대한 Android 단위 테스트와 하나의 debug APK 빌드 | Android 관련 변경 |
## Fail-Fast 순서
작업은 저렴한 검사가 비용이 큰 작업보다 먼저 실패하도록 정렬되어 있습니다.
작업은 비용이 큰 작업이 실행되기 전에 저렴한 검사가 먼저 실패하도록 순서가 지정되어 있습니다.
1. `preflight`가 어떤 레인이 아예 존재할지를 결정합니다. `docs-scope`와 `changed-scope` 로직은 독립 작업이 아니라 이 작업 내부의 step입니다.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs`, `skills-python`은 더 무거운 산출물 및 플랫폼 매트릭스 작업을 기다리지 않고 빠르게 실패합니다.
3. `build-artifacts`는 빠른 Linux 레인과 겹쳐 실행되므로 공유 빌드가 준비되는 즉시 다운스트림 소비자가 시작할 수 있습니다.
4. 그다음 더 무거운 플랫폼 및 런타임 레인이 팬아웃합니다: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, PR 전용 `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift`, `android`.
1. `preflight`가 어떤 레인이 실제로 존재할지 결정합니다. `docs-scope`와 `changed-scope` 로직은 독립적인 작업이 아니라 이 작업 내부의 단계입니다.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs`, `skills-python`은 더 무거운 artifact 및 플랫폼 매트릭스 작업을 기다리지 않고 빠르게 실패합니다.
3. `build-artifacts`는 빠른 Linux 레인과 겹쳐 실행되어 downstream consumer가 공유 빌드가 준비되는 즉시 시작할 수 있도록 합니다.
4. 그다음 더 무거운 플랫폼 및 런타임 레인이 fan-out됩니다: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, PR 전용 `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift`, `android`.
범위 로직은 `scripts/ci-changed-scope.mjs`에 있으며 `src/scripts/ci-changed-scope.test.ts`의 단위 테스트로 검증됩니다.
CI 워크플로 편집은 Node CI 그래프와 워크플로 linting은 검증하지만, 그 자체로 Windows, Android, macOS 네이티브 빌드를 강제하지는 않습니다. 이러한 플랫폼 레인은 계속 플랫폼 소스 변경에만 스코프됩니다.
Windows Node 체크는 Windows 전용 process/path wrapper, npm/pnpm/UI runner helper, package manager 구성, 그리고 해당 레인을 실행하는 CI 워크플로 surface에 스코프됩니다. 관련 없는 소스, plugin, install-smoke, test-only 변경은 일반 테스트 샤드에서 이미 커버되는 검증을 위해 16-vCPU Windows worker를 점유하지 않도록 Linux Node 레인에 남겨 둡니다.
별도의 `install-smoke` 워크플로는 자체 `preflight` 작업을 통해 같은 범위 스크립트를 재사용합니다. 더 좁은 changed-smoke 신호에서 `run_install_smoke`를 계산하므로, Docker/install smoke는 install, packaging, container 관련 변경, bundled extension 프로덕션 변경, 그리고 Docker smoke 작업이 실행하는 코어 plugin/channel/gateway/Plugin SDK surface에 대해 실행됩니다. test-only 및 docs-only 수정은 Docker worker를 점유하지 않습니다. 해당 QR package smoke는 BuildKit pnpm store 캐시는 유지하면서 Docker `pnpm install` 레이어를 강제로 다시 실행하므로, 매 실행마다 dependency를 다시 다운로드하지 않으면서도 설치를 계속 검증합니다. 해당 gateway-network e2e는 작업 초반에 빌드한 런타임 이미지를 재사용하므로, Docker 빌드를 하나 더 추가하지 않고도 실제 컨테이너 간 WebSocket 커버리지를 더합니다. 로컬 `test:docker:all`은 공유 live-test 이미지 하나와 공유 `scripts/e2e/Dockerfile` built-app 이미지 하나를 미리 빌드한 다음, `OPENCLAW_SKIP_DOCKER_BUILD=1`로 live/E2E smoke 레인을 병렬 실행합니다. 기본 동시성 4는 `OPENCLAW_DOCKER_ALL_PARALLELISM`으로 조정하세요. 로컬 aggregate는 기본적으로 첫 실패 이후 새 pooled 레인 스케줄링을 중단하며, 각 레인에는 120분 타임아웃이 있고 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`로 재정의할 수 있습니다. 시작 또는 provider에 민감한 레인은 병렬 풀 이후에 독점적으로 실행됩니다. 재사용 가능한 live/E2E 워크플로도 공유 이미지 패턴을 따르며, Docker 매트릭스 전에 SHA 태그가 붙은 GHCR Docker E2E 이미지를 하나 빌드 및 푸시한 다음 `OPENCLAW_SKIP_DOCKER_BUILD=1`로 매트릭스를 실행합니다. 예약된 live/E2E 워크플로는 전체 릴리스 경로 Docker 스위트를 매일 실행합니다. QR 및 installer Docker 테스트는 설치 중심의 자체 Dockerfile을 유지합니다. 별도의 `docker-e2e-fast` 작업은 120초 명령 타임아웃 하에서 범위가 제한된 bundled-plugin Docker 프로파일을 실행합니다: setup-entry dependency 복구와 synthetic bundled-loader 실패 격리입니다. 전체 bundled update/channel 매트릭스는 반복적인 실제 npm update 및 doctor repair 패스를 수행하므로 수동/전체 스위트로 유지됩니다.
CI 워크플로 편집은 Node CI 그래프와 워크플로 linting은 검증하지만, Windows, Android, macOS 네이티브 빌드를 그것만으로 강제하지는 않습니다. 해당 플랫폼 레인은 계속해서 플랫폼 소스 변경에만 범위가 지정됩니다.
Windows Node 검사는 Windows 전용 process/path wrapper, npm/pnpm/UI runner helper, 패키지 관리자 구성, 그리고 해당 레인을 실행하는 CI 워크플로 표면으로 범위가 지정됩니다. 관련 없는 소스, plugin, install-smoke, test-only 변경은 일반 테스트 shard로 이미 검증되는 범위를 위해 16-vCPU Windows worker를 예약하지 않도록 Linux Node 레인에 남습니다.
별도의 `install-smoke` 워크플로는 자체 `preflight` 작업을 통해 동일한 범위 스크립트를 재사용합니다. 더 좁은 changed-smoke 신호에서 `run_install_smoke`를 계산하므로, Docker/install smoke는 install, packaging, container 관련 변경, bundled extension 프로덕션 변경, 그리고 Docker smoke 작업이 실행하는 core plugin/channel/gateway/Plugin SDK 표면에 대해 실행됩니다. test-only 및 docs-only 편집은 Docker worker를 예약하지 않습니다. 해당 QR package smoke는 Docker `pnpm install` 레이어를 강제로 다시 실행하면서 BuildKit pnpm store 캐시는 유지하므로, 매 실행마다 dependency를 다시 다운로드하지 않으면서도 설치를 계속 검증합니다. gateway-network e2e는 작업 초기에 빌드된 런타임 이미지를 재사용하므로, 또 다른 Docker 빌드를 추가하지 않고 실제 container-to-container WebSocket 범위를 추가합니다. 로컬 `test:docker:all`은 공유 live-test 이미지 하나와 공유 `scripts/e2e/Dockerfile` built-app 이미지 하나를 미리 빌드한 뒤, `OPENCLAW_SKIP_DOCKER_BUILD=1`로 live/E2E smoke 레인을 병렬 실행합니다. 기본 동시성 4는 `OPENCLAW_DOCKER_ALL_PARALLELISM`으로 조정할 수 있습니다. 로컬 aggregate는 기본적으로 첫 번째 실패 후 새로운 pooled lane 예약을 중단하며, 각 lane에는 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`로 재정의 가능한 120분 타임아웃이 있습니다. startup 또는 provider 민감 레인은 병렬 풀 이후에 독점 실행됩니다. 재사용 가능한 live/E2E 워크플로는 Docker 매트릭스 전에 SHA 태그가 붙은 GHCR Docker E2E 이미지를 하나 빌드하고 푸시한 뒤, `OPENCLAW_SKIP_DOCKER_BUILD=1`로 매트릭스를 실행하는 동일한 shared-image 패턴을 따릅니다. 예약된 live/E2E 워크플로는 매일 전체 release-path Docker 제품군을 실행합니다. QR 및 installer Docker 테스트는 각자의 install 중심 Dockerfile을 유지합니다. 별도의 `docker-e2e-fast` 작업은 120초 명령 타임아웃 아래에서 제한된 bundled-plugin Docker 프로필을 실행합니다: setup-entry dependency repair 및 synthetic bundled-loader failure isolation입니다. 전체 bundled update/channel 매트릭스는 반복적인 실제 npm update 및 doctor repair 패스를 수행하므로 수동/전체 제품군으로 유지됩니다.
로컬 changed-lane 로직은 `scripts/changed-lanes.mjs`에 있으며 `scripts/check-changed.mjs`로 실행됩니다. 이 로컬 게이트는 넓은 CI 플랫폼 범위보다 아키텍처 경계에 더 엄격합니다. 코어 프로덕션 변경은 코어 프로덕션 typecheck와 코어 테스트를 실행하고, 코어 test-only 변경은 코어 테스트 typecheck/테스트만 실행하며, extension 프로덕션 변경은 extension 프로덕션 typecheck와 extension 테스트를 실행하고, extension test-only 변경은 extension 테스트 typecheck/테스트만 실행합니다. 공개 Plugin SDK 또는 plugin-contract 변경은 extension이 해당 코어 contract에 의존하므로 extension 검증으로 확장됩니다. 릴리스 메타데이터만 포함된 버전 증가 변경은 대상이 좁은 version/config/root-dependency 검사를 실행합니다. 알 수 없는 root/config 변경은 안전을 위해 모든 레인으로 실패 처리됩니다.
로컬 changed-lane 로직은 `scripts/changed-lanes.mjs`에 있으며 `scripts/check-changed.mjs`에 의해 실행됩니다. 이 로컬 게이트는 광범위한 CI 플랫폼 범위보다 아키텍처 경계에 더 엄격합니다. core 프로덕션 변경은 core 프로덕션 typecheck와 core 테스트를 실행하고, core test-only 변경은 core 테스트 typecheck/테스트만 실행하며, extension 프로덕션 변경은 extension 프로덕션 typecheck와 extension 테스트를 실행하고, extension test-only 변경은 extension 테스트 typecheck/테스트만 실행합니다. public Plugin SDK 또는 plugin-contract 변경은 extension이 이러한 core contract에 의존하므로 extension 검증까지 확장됩니다. 릴리스 메타데이터 전용 버전 범프는 대상이 좁은 version/config/root-dependency 검사를 실행합니다. 알 수 없는 root/config 변경은 안전하게 모든 레인으로 확장됩니다.
push에서는 `checks` 매트릭스에 push 전용 `compat-node22` 레인이 추가됩니다. pull request에서는 이 레인이 건너뛰어지고, 매트릭스는 일반 테스트/채널 레인에 집중합니다.
푸시에서는 `checks` 매트릭스가 push 전용 `compat-node22` 레인을 추가합니다. pull request에서는 해당 레인이 건너뛰어지고 매트릭스는 일반 테스트/channel 레인에 집중된 상태를 유지합니다.
가장 느린 Node 테스트 계열은 각 작업이 작게 유지되도록 분할 또는 균형 조정됩니다. 채널 contract는 registry와 코어 커버리지를 총 여섯 개의 가중 샤드로 분할하고, bundled plugin 테스트는 여섯 개의 extension worker에 균형 있게 배분되며, auto-reply는 여섯 개의 작은 worker 대신 균형 잡힌 세 개의 worker로 실행되고, agentic gateway/plugin config는 빌드 산출물을 기다리는 대신 기존 소스 전용 agentic Node 작업에 분산됩니다. 광범위한 browser, QA, media, 기타 plugin 테스트는 공유 plugin catch-all 대신 전용 Vitest config를 사용합니다. 광범위한 agents 레인은 단일 느린 테스트 파일이 소유하는 형태가 아니라 import/스케줄링 지배형이므로 공유 Vitest 파일 병렬 스케줄러를 사용합니다. `runtime-config`는 공유 런타임 샤드가 꼬리를 소유하지 않도록 infra core-runtime 샤드와 함께 실행됩니다. `check-additional`은 package-boundary compile/canary 작업을 함께 유지하고 런타임 topology 아키텍처를 gateway watch 커버리지와 분리합니다. boundary guard 샤드는 그 안의 작은 독립 가드를 하나의 작업 내부에서 동시에 실행합니다. Gateway watch, 채널 테스트, 코어 support-boundary 샤드는 `dist/`와 `dist-runtime/`이 이미 빌드된 뒤 `build-artifacts` 내부에서 동시에 실행되며, 두 개의 추가 Blacksmith worker와 두 번째 산출물 소비자 큐를 피하면서도 기존 체크 이름을 가벼운 verifier 작업으로 유지합니다.
Android CI는 `testPlayDebugUnitTest`와 `testThirdPartyDebugUnitTest`를 모두 실행한 다음 Play 디버그 APK를 빌드합니다. third-party flavor에는 별도의 소스 세트나 manifest가 없지만, 해당 단위 테스트 레인은 여전히 SMS/call-log BuildConfig 플래그로 그 flavor를 컴파일하면서도 모든 Android 관련 push마다 중복 디버그 APK 패키징 작업은 피합니다.
`extension-fast`는 push 실행이 이미 전체 bundled plugin 샤드를 수행하므로 PR 전용입니다. 이렇게 하면 리뷰 중 변경 plugin에 대한 피드백은 유지하면서도 `checks-node-extensions`에 이미 존재하는 커버리지를 위해 `main`에서 추가 Blacksmith worker를 예약하지 않게 됩니다.
가장 느린 Node 테스트 계열은 각 작업이 너무 커지지 않도록 분할 또는 균형 조정되어 있으며, 동시에 runner를 과도하게 예약하지 않도록 되어 있습니다. channel contract는 가중치 기반 shard 세 개로 실행되고, bundled plugin 테스트는 여섯 개의 extension worker에 걸쳐 균형 분산되며, 작은 core unit 레인은 짝지어지고, auto-reply는 여섯 개의 작은 worker 대신 균형 잡힌 세 개의 worker로 실행되며, agentic gateway/plugin config는 built artifact를 기다리지 않고 기존 source-only agentic Node 작업에 분산됩니다. 광범위한 browser, QA, media, 기타 plugin 테스트는 공유 plugin catch-all 대신 전용 Vitest 구성을 사용합니다. 광범위한 agents lane은 단일 느린 테스트 파일이 아니라 import/스케줄링이 지배적이므로 공유 Vitest 파일 병렬 스케줄러를 사용합니다. `runtime-config`는 공유 런타임 shard가 tail을 맡지 않도록 infra core-runtime shard와 함께 실행됩니다. `check-additional`은 package-boundary compile/canary 작업을 함께 유지하고, runtime topology architecture와 gateway watch 범위를 분리합니다. boundary guard shard는 하나의 작업 내에서 작은 독립 guard를 동시에 실행합니다. Gateway watch, channel 테스트, core support-boundary shard는 `dist/`와 `dist-runtime/`가 이미 빌드된 뒤 `build-artifacts` 내부에서 동시에 실행되며, 이전 check 이름은 가벼운 verifier 작업으로 유지하면서 추가 Blacksmith worker 두 개와 두 번째 artifact-consumer 큐는 피합니다.
Android CI는 `testPlayDebugUnitTest`와 `testThirdPartyDebugUnitTest`를 모두 실행한 뒤 Play debug APK를 빌드합니다. third-party flavor에는 별도의 소스 세트나 manifest가 없지만, 해당 단위 테스트 레인은 SMS/call-log BuildConfig 플래그를 사용해 그 flavor도 컴파일하면서 Android 관련 모든 푸시마다 중복 debug APK 패키징 작업이 실행되는 것은 피합니다.
`extension-fast`는 푸시 실행에서 이미 전체 bundled plugin shard를 수행하므로 PR 전용입니다. 이렇게 하면 리뷰를 위한 changed-plugin 피드백은 유지하면서, `checks-node-extensions`에 이미 포함된 범위를 위해 `main`에서 추가 Blacksmith worker를 예약하지 않아도 됩니다.
GitHub는 같은 PR 또는 `main` ref에 새 push가 들어오면 더 이상 최신이 아닌 작업을 `cancelled`로 표시할 수 있습니다. 같은 ref의 최신 실행도 실패 중이 아닌 한, 이를 CI 노이즈로 취급하세요. aggregate 샤드 체크는 `!cancelled() && always()`를 사용하므로 정상적인 샤드 실패는 계속 보고하지만, 전체 워크플로 자체가 이미 더 최신 실행으로 대체된 경우에는 큐에 들어가지 않습니다.
CI concurrency key는 버전이 지정되어 있습니다(`CI-v7-*`). 따라서 오래된 큐 그룹의 GitHub 측 zombie가 최신 main 실행을 무기한 차단할 수 없습니다.
GitHub는 같은 PR 또는 `main` ref에 더 새로운 푸시가 들어오면 대체된 작업을 `cancelled`로 표시할 수 있습니다. 같은 ref에 대한 최신 실행도 실패하는 경우가 아니라면 이를 CI 노이즈로 취급하세요. aggregate shard 검사는 `!cancelled() && always()`를 사용하므로 정상적인 shard 실패는 계속 보고하지만, 전체 워크플로가 이미 대체된 뒤에는 대기열에 들어가지 않습니다.
CI concurrency key는 버전 관리됩니다(`CI-v7-*`). 따라서 오래된 큐 그룹의 GitHub 측 zombie가 더 새로운 main 실행을 무기한 차단할 수 없습니다.
## 러너
| 러너 | 작업 |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, 빠른 보안 작업과 aggregate(`security-scm-fast`, `security-dependency-audit`, `security-fast`), 빠른 protocol/contract/bundled 검사, 샤딩된 채널 contract 검사, lint를 제외한 `check` 샤드, `check-additional` 샤드와 aggregate, Node 테스트 aggregate verifier, 문서 검사, Python Skills, workflow-sanity, labeler, auto-response. install-smoke preflight도 GitHub 호스팅 Ubuntu를 사용하므로 Blacksmith 매트릭스가 더 일찍 큐에 들어갈 수 있습니다 |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, Linux Node 테스트 샤드, bundled plugin 테스트 샤드, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` — 이 작업은 여전히 CPU 민감도가 높아 8 vCPU가 절약하는 것보다 더 많은 비용이 들었습니다. install-smoke Docker 빌드 — 여기서는 32-vCPU의 큐 대기 비용이 절약 효과보다 더 컸습니다 |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw`에서의 `macos-node`; fork에서는 `macos-latest`로 폴백 |
| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw`에서의 `macos-swift`; fork에서는 `macos-latest`로 폴백 |
| 러너 | 작업 |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ubuntu-24.04` | `preflight`, 빠른 보안 작업 및 aggregate (`security-scm-fast`, `security-dependency-audit`, `security-fast`), 빠른 protocol/contract/bundled 검사, shard된 channel contract 검사, lint를 제외한 `check` shard, `check-additional` shard 및 aggregate, Node 테스트 aggregate verifier, docs 검사, Python Skills, workflow-sanity, labeler, auto-response; install-smoke preflight도 Blacksmith 매트릭스가 더 일찍 대기열에 들어갈 수 있도록 GitHub 호스팅 Ubuntu를 사용합니다 |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, Linux Node 테스트 shard, bundled plugin 테스트 shard, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`. 이 작업은 여전히 CPU 민감도가 높아서 8 vCPU는 절약 효과보다 비용이 더 컸습니다. 또한 install-smoke Docker 빌드도 여기에 해당하며, 32-vCPU는 절약 효과보다 대기열 시간이 더 컸습니다 |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw`에서의 `macos-node`; fork는 `macos-latest`로 대체됩니다 |
| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw`에서의 `macos-swift`; fork는 `macos-latest`로 대체됩니다 |
## 로컬 대응 명령어
## 로컬 대응 항목
```bash
pnpm changed:lanes # origin/main...HEAD에 대한 로컬 changed-lane 분류기를 확인
pnpm check:changed # 스마트 로컬 게이트: 경계 레인별 변경 typecheck/lint/테스트
pnpm check # 빠른 로컬 게이트: 프로덕션 tsgo + 샤딩된 lint + 병렬 빠른 가드
pnpm changed:lanes # origin/main...HEAD에 대한 로컬 changed-lane 분류기 확인
pnpm check:changed # 스마트 로컬 게이트: 경계 레인별 변경된 typecheck/lint/테스트
pnpm check # 빠른 로컬 게이트: 프로덕션 tsgo + shard된 lint + 병렬 빠른 guard
pnpm check:test-types
pnpm check:timed # 단계별 시간 측정이 포함된 동일한 게이트
pnpm build:strict-smoke
pnpm check:architecture
pnpm test:gateway:watch-regression
pnpm test # Vitest 테스트
pnpm test # vitest 테스트
pnpm test:channels
pnpm test:contracts:channels
pnpm check:docs # 문서 포맷 + lint + 깨진 링크
pnpm check:docs # docs 형식 + lint + 깨진 링크
pnpm build # CI artifact/build-smoke 레인이 중요할 때 dist 빌드
node scripts/ci-run-timings.mjs <run-id> # 총 소요 시간, 큐 대기 시간, 가장 느린 작업 요약
node scripts/ci-run-timings.mjs <run-id> # 전체 시간, 대기열 시간, 가장 느린 작업 요약
node scripts/ci-run-timings.mjs --recent 10 # 최근 성공한 main CI 실행 비교
```

149
docs/ko/gateway/authentication.md
View File

@ -1,43 +1,43 @@
---
read_when:
- 모델 인증 또는 OAuth 만료를 디버깅할 때
- 인증 또는 자격 증명 저장소를 문서화할 때
summary: '모델 인증: OAuth, API 키, Claude CLI 재사용, 그리고 Anthropic setup-token'
- 모델 인증 또는 OAuth 만료 디버깅
- 인증 또는 자격 증명 저장 문서화
summary: '모델 인증: OAuth, API 키, Claude CLI 재사용, 및 Anthropic 설정 토큰'
title: 인증
x-i18n:
generated_at: "2026-04-07T05:55:51Z"
generated_at: "2026-04-23T14:55:31Z"
model: gpt-5.4
provider: openai
source_hash: 9db0ad9eccd7e3e3ca328adaad260bc4288a8ccdbe2dc0c24d9fd049b7ab9231
source_hash: 37a7c20872b915d1d079f0578c933e43cbdb97eca1c60d8c4e6e5137ca83f8b2
source_path: gateway/authentication.md
workflow: 15
---
# 인증 (모델 providers)
# 인증 (모델 제공자)
<Note>
이 페이지는 **모델 provider** 인증(API 키, OAuth, Claude CLI 재사용, Anthropic setup-token)을 다룹니다. **Gateway 연결** 인증(token, password, trusted-proxy)은 [구성](/ko/gateway/configuration) 및 [Trusted Proxy Auth](/ko/gateway/trusted-proxy-auth)를 참조하세요.
이 페이지는 **모델 제공자** 인증(API 키, OAuth, Claude CLI 재사용, Anthropic 설정 토큰)을 다룹니다. **Gateway 연결** 인증(토큰, 비밀번호, trusted-proxy)은 [구성](/ko/gateway/configuration) 및 [Trusted Proxy Auth](/ko/gateway/trusted-proxy-auth)를 참조하세요.
</Note>
OpenClaw는 모델 providers에 대해 OAuth와 API 키를 지원합니다. 항상 실행되는 Gateway
호스트에서는 일반적으로 API 키가 가장 예측 가능한 선택입니다. 구독/OAuth
흐름도 provider 계정 모델과 일치하는 경우 지원됩니다.
OpenClaw는 모델 제공자에 대해 OAuth와 API 키를 지원합니다. 항상 실행되는 Gateway
호스트에서는 일반적으로 API 키가 가장 예측 가능한 옵션입니다. 제공자 계정 모델에 맞는 경우 구독/OAuth
흐름도 지원됩니다.
전체 OAuth 흐름과 저장소
구조는 [/concepts/oauth](/ko/concepts/oauth)를 참조하세요.
SecretRef 기반 인증(`env`/`file`/`exec` providers)은 [Secrets Management](/ko/gateway/secrets)를 참조하세요.
`models status --probe`에서 사용하는 자격 증명 적격성/사유 코드 규칙은
[Auth Credential Semantics](/ko/auth-credential-semantics)를 참조하세요.
레이아웃은 [/concepts/oauth](/ko/concepts/oauth)를 참조하세요.
SecretRef 기반 인증(`env`/`file`/`exec` 제공자)은 [Secrets Management](/ko/gateway/secrets)를 참조하세요.
`models status --probe`에서 사용하는 자격 증명 적격성/이유 코드 규칙은
[인증 자격 증명 시맨틱](/ko/auth-credential-semantics)을 참조하세요.
## 권장 설정(API 키, 모든 provider)
## 권장 설정(API 키, 모든 제공자)
장시간 실행되는 Gateway를 운영하는 경우, 선택한
provider의 API 키로 시작하세요.
Anthropic의 경우 특히 API 키 인증이 여전히 가장 예측 가능한 서버
장기간 실행되는 Gateway를 사용 중이라면, 선택한
제공자용 API 키부터 시작하세요.
특히 Anthropic의 경우에도 API 키 인증이 여전히 가장 예측 가능한 서버
설정이지만, OpenClaw는 로컬 Claude CLI 로그인 재사용도 지원합니다.
1. provider 콘솔에서 API 키를 생성합니다.
2. 이를 **Gateway 호스트**(`openclaw gateway`를 실행하는 머신)에 배치합니다.
1. 제공자 콘솔에서 API 키를 만듭니다.
2. 이를 **Gateway 호스트**(`openclaw gateway`를 실행하는 머신)에 설정합니다.
```bash
export <PROVIDER>_API_KEY="..."
@ -45,7 +45,7 @@ openclaw models status
```
3. Gateway가 systemd/launchd 아래에서 실행되는 경우, 데몬이 읽을 수 있도록
키를 `~/.openclaw/.env`에 넣는 것을 권장합니다:
`~/.openclaw/.env`에 키를 두는 것을 권장합니다.
```bash
cat >> ~/.openclaw/.env <<'EOF'
@ -53,43 +53,60 @@ cat >> ~/.openclaw/.env <<'EOF'
EOF
```
그런 다음 데몬을 재시작(또는 Gateway 프로세스를 재시작)하고 다시 확인하세요:
그런 다음 데몬을 다시 시작하고(또는 Gateway 프로세스를 다시 시작하고) 다시 확인하세요.
```bash
openclaw models status
openclaw doctor
```
환경 변수를 직접 관리하고 싶지 않다면, 온보딩이 데몬 사용을 위해
API 키를 저장할 수 있습니다: `openclaw onboard`.
직접 env var를 관리하고 싶지 않다면, 온보딩에서
데몬용 API 키를 저장할 수 있습니다: `openclaw onboard`.
`env.shellEnv`,
`~/.openclaw/.env`, systemd/launchd의 환경 상속에 대한 자세한 내용은 [도움말](/ko/help)을 참조하세요.
`~/.openclaw/.env`, systemd/launchd의 env 상속에 대한 자세한 내용은 [도움말](/ko/help)을 참조하세요.
## Anthropic: Claude CLI 및 토큰 호환성
Anthropic setup-token 인증은 OpenClaw에서 여전히 지원되는 토큰
경로로 제공됩니다. 이후 Anthropic 담당자가 OpenClaw 스타일의 Claude CLI 사용이
다시 허용된다고 알려주었으므로, Anthropic이 새 정책을 발표하지 않는 한
OpenClaw는 Claude CLI 재사용과 `claude -p` 사용을 이 통합에 대해
허용된 방식으로 취급합니다. 호스트에서 Claude CLI 재사용이 가능하다면,
이제 그것이 선호되는 경로입니다.
Anthropic 설정 토큰 인증은 여전히 OpenClaw에서 지원되는 토큰
경로로 사용할 수 있습니다. 이후 Anthropic 직원이 OpenClaw 스타일 Claude CLI 사용이
다시 허용된다고 알려왔기 때문에, Anthropic이 새로운 정책을 발표하지 않는 한
OpenClaw는 이 통합에 대해 Claude CLI 재사용과 `claude -p` 사용을 허용된 방식으로 취급합니다. 호스트에서
Claude CLI 재사용이 가능한 경우, 이제 이것이 권장 경로입니다.
장시간 실행되는 Gateway 호스트에서는 Anthropic API 키가 여전히 가장 예측 가능한
장기간 실행되는 Gateway 호스트의 경우, Anthropic API 키가 여전히 가장 예측 가능한
설정입니다. 같은 호스트에서 기존 Claude 로그인을 재사용하려면,
온보딩/구성에서 Anthropic Claude CLI 경로를 사용하세요.
수동 토큰 입력(모든 provider, `auth-profiles.json` 기록 + config 업데이트):
Claude CLI 재사용을 위한 권장 호스트 설정:
```bash
# Gateway 호스트에서 실행
claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default
```
이것은 2단계 설정입니다.
1. Gateway 호스트에서 Claude Code 자체를 Anthropic에 로그인시킵니다.
2. OpenClaw에 Anthropic 모델 선택을 로컬 `claude-cli`
백엔드로 전환하고, 그에 맞는 OpenClaw 인증 프로필을 저장하도록 지시합니다.
`claude`가 `PATH`에 없다면, 먼저 Claude Code를 설치하거나
`agents.defaults.cliBackends.claude-cli.command`를 실제 바이너리 경로로 설정하세요.
수동 토큰 입력(모든 제공자; `auth-profiles.json` 작성 + config 업데이트):
```bash
openclaw models auth paste-token --provider openrouter
```
정적 자격 증명에는 인증 프로필 참조도 지원됩니다:
정적 자격 증명에 대해서도 인증 프로필 참조가 지원됩니다.
- `api_key` 자격 증명은 `keyRef: { source, provider, id }`를 사용할 수 있습니다
- `token` 자격 증명은 `tokenRef: { source, provider, id }`를 사용할 수 있습니다
- OAuth 모드 프로필은 SecretRef 자격 증명을 지원하지 않습니다. `auth.profiles.<id>.mode`가 `"oauth"`로 설정된 경우, 해당 프로필의 SecretRef 기반 `keyRef`/`tokenRef` 입력은 거부됩니다.
- `api_key` 자격 증명은 `keyRef: { source, provider, id }`를 사용할 수 있습니다.
- `token` 자격 증명은 `tokenRef: { source, provider, id }`를 사용할 수 있습니다.
- OAuth 모드 프로필은 SecretRef 자격 증명을 지원하지 않습니다. `auth.profiles.<id>.mode`가 `"oauth"`로 설정된 경우, 해당 프로필에 대한 SecretRef 기반 `keyRef`/`tokenRef` 입력은 거부됩니다.
자동화 친화적 확인(만료/누락 시 종료 코드 `1`, 만료 임박 시 `2`):
@ -97,7 +114,7 @@ openclaw models auth paste-token --provider openrouter
openclaw models status --check
```
실시간 인증 프로브:
라이브 인증 프로브:
```bash
openclaw models status --probe
@ -105,25 +122,26 @@ openclaw models status --probe
참고:
- 프로브 행은 인증 프로필, 환경 자격 증명, 또는 `models.json`에서 올 수 있습니다.
- 프로브 행은 인증 프로필, env 자격 증명 또는 `models.json`에서 올 수 있습니다.
- 명시적 `auth.order.<provider>`가 저장된 프로필을 생략하면, 프로브는
해당 프로필을 시도하는 대신 `excluded_by_auth_order`를 보고합니다.
- 인증이 존재하지만 OpenClaw가 해당 provider에 대해 프로브 가능한 모델 후보를
확인할 수 없으면, 프로브는 `status: no_model`을 보고합니다.
- 인증이 존재하지만 OpenClaw가 해당 제공자에 대해 프로브 가능한 모델 후보를 확인할 수 없는 경우,
프로브는 `status: no_model`을 보고합니다.
- rate-limit cooldown은 모델 범위일 수 있습니다. 한
모델에 대해 cooldown 상태인 프로필도 같은 provider의 다른 형제 모델에는 여전히 사용할 수 있습니다.
모델에 대해 cooldown 중인 프로필이 동일 제공자의 다른 형제 모델에서는 여전히 사용 가능할 수 있습니다.
선택적 운영 스크립트(systemd/Termux)는 여기에서 문서화되어 있습니다:
선택적 운영 스크립트(systemd/Termux)는 여기 문서화되어 있습니다:
[인증 모니터링 스크립트](/ko/help/scripts#auth-monitoring-scripts)
## Anthropic 참고
Anthropic `claude-cli` 백엔드는 다시 지원됩니다.
- Anthropic 담당자는 이 OpenClaw 통합 경로가 다시 허용된다고 알려주었습니다.
- 따라서 Anthropic이 새로운 정책을 발표하지 않는 한, OpenClaw는 Anthropic 기반 실행에 대해 Claude CLI 재사용과 `claude -p` 사용을 허용된 방식으로 취급합니다.
- Anthropic API 키는 장시간 실행되는 Gateway
호스트와 명시적인 서버 측 과금 제어를 위한 가장 예측 가능한 선택으로 남아 있습니다.
- Anthropic 직원이 이 OpenClaw 통합 경로가 다시 허용된다고 알려왔습니다.
- 따라서 Anthropic이 새로운 정책을 발표하지 않는 한, OpenClaw는
Anthropic 기반 실행에 대해 Claude CLI 재사용과 `claude -p` 사용을 허용된 방식으로 취급합니다.
- Anthropic API 키는 장기간 실행되는 Gateway
호스트와 명시적인 서버 측 과금 제어를 위해 여전히 가장 예측 가능한 선택입니다.
## 모델 인증 상태 확인
@ -132,36 +150,36 @@ openclaw models status
openclaw doctor
```
## API 키 교체 동작(Gateway)
## API 키 순환 동작(Gateway)
일부 providers는 API 호출이 provider rate limit에
도달했을 때 대체 키로 요청을 다시 시도하는 것을 지원합니다.
일부 제공자는 API 호출이 제공자 rate limit에
도달했을 때 대체 키로 요청을 재시도하는 것을 지원합니다.
- 우선순위:
- `OPENCLAW_LIVE_<PROVIDER>_KEY` (단일 override)
- `OPENCLAW_LIVE_<PROVIDER>_KEY`(단일 재정의)
- `<PROVIDER>_API_KEYS`
- `<PROVIDER>_API_KEY`
- `<PROVIDER>_API_KEY_*`
- Google providers는 추가 fallback으로 `GOOGLE_API_KEY`도 포함합니다.
- Google 제공자는 추가 폴백으로 `GOOGLE_API_KEY`도 포함합니다.
- 동일한 키 목록은 사용 전에 중복 제거됩니다.
- OpenClaw는 rate-limit 오류에 대해서만 다음 키로 재시도합니다(예:
`429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent
requests`, `ThrottlingException`, `concurrency limit reached`, 또는
`workers_ai ... quota limit exceeded`).
- rate-limit이 아닌 오류는 대체 키로 재시도하지 않습니다.
- 모든 키가 실패하면 마지막 시도의 최종 오류가 반환됩니다.
- 모든 키가 실패하면, 마지막 시도의 최종 오류가 반환됩니다.
## 어떤 자격 증명을 사용할지 제어하기
## 어떤 자격 증명을 사용할지 제어
### 세션별(채팅 명령)
현재 세션에서 특정 provider 자격 증명을 고정하려면 `/model <alias-or-id>@<profileId>`를 사용하세요(예시 프로필 ID: `anthropic:default`, `anthropic:work`).
현재 세션에 특정 제공자 자격 증명을 고정하려면 `/model <alias-or-id>@<profileId>`를 사용하세요(프로필 ID 예시: `anthropic:default`, `anthropic:work`).
간단한 선택기는 `/model`(또는 `/model list`)을 사용하고, 전체 보기(후보 + 다음 인증 프로필, 설정된 경우 provider 엔드포인트 세부 정보 포함)는 `/model status`를 사용하세요.
간단한 선택기는 `/model`(또는 `/model list`)을 사용하고, 전체 보기(후보 + 다음 인증 프로필, 구성된 경우 제공자 엔드포인트 세부 정보 포함)는 `/model status`를 사용하세요.
### 에이전트별(CLI override)
### 에이전트별(CLI 재정의)
에이전트에 대한 명시적 인증 프로필 순서 override를 설정합니다(해당 에이전트의 `auth-state.json`에 저장됨):
에이전트에 대한 명시적 인증 프로필 순서 재정의를 설정합니다(해당 에이전트의 `auth-state.json`에 저장됨).
```bash
openclaw models auth order get --provider anthropic
@ -169,17 +187,18 @@ openclaw models auth order set --provider anthropic anthropic:default
openclaw models auth order clear --provider anthropic
```
특정 에이전트를 대상으로 하려면 `--agent <id>`를 사용하고, 구성된 기본 에이전트를 사용하려면 이를 생략하세요.
순서 문제를 디버깅할 때 `openclaw models status --probe`는 생략된
특정 에이전트를 대상으로 하려면 `--agent <id>`를 사용하고, 구성된 기본 에이전트를 사용하려면 생략하세요.
순서 문제를 디버깅할 때는 `openclaw models status --probe`가 생략된
저장 프로필을 조용히 건너뛰는 대신 `excluded_by_auth_order`로 표시합니다.
cooldown 문제를 디버깅할 때는 rate-limit cooldown이
전체 provider 프로필이 아니라 하나의 모델 ID에 연결될 수 있다는 점을 기억하세요.
전체 제공자 프로필이 아니라 하나의 모델 ID에 연결될 수 있다는 점을 기억하세요.
## 문제 해결
### "No credentials found"
### "자격 증명을 찾을 수 없음"
Anthropic 프로필이 없으면 **Gateway 호스트**에 Anthropic API 키를 구성하거나 Anthropic setup-token 경로를 설정한 다음 다시 확인하세요:
Anthropic 프로필이 없으면,
**Gateway 호스트**에 Anthropic API 키를 구성하거나 Anthropic 설정 토큰 경로를 설정한 다음 다시 확인하세요.
```bash
openclaw models status
@ -187,4 +206,6 @@ openclaw models status
### 토큰 만료 임박/만료됨
어떤 프로필이 만료 중인지 확인하려면 `openclaw models status`를 실행하세요. Anthropic 토큰 프로필이 없거나 만료된 경우, setup-token을 통해 해당 설정을 새로 고치거나 Anthropic API 키로 마이그레이션하세요.
어떤 프로필이 만료 중인지 확인하려면 `openclaw models status`를 실행하세요. Anthropic 토큰 프로필이 없거나 만료된 경우,
setup-token으로 해당 설정을 새로 고치거나 Anthropic API 키로
마이그레이션하세요.

218
docs/ko/gateway/cli-backends.md
View File

@ -1,46 +1,41 @@
---
read_when:
- API provider가 실패할 때 신뢰할 수 있는 대체 경로를 원합니다
- Codex CLI 또는 기타 로컬 AI CLI를 실행 중이며 이를 재사용하려고 합니다
- CLI 백엔드 도구 액세스를 위한 MCP loopback 브리지를 이해하려고 합니다
summary: 'CLI 백엔드: 선택적 MCP 도구 브리지가 포함된 로컬 AI CLI 대체 경로'
- API 제공자가 실패할 때를 대비해 신뢰할 수 있는 대체 경로가 필요합니다
- Codex CLI 또는 다른 로컬 AI CLI를 실행 중이며 이를 재사용하려고 합니다
- CLI 백엔드 도구 액세스를 위한 MCP loopback 브리지를 이해하고 싶습니다
summary: 'CLI 백엔드: 선택적 MCP 도구 브리지를 사용하는 로컬 AI CLI 대체 경로'
title: CLI 백엔드
x-i18n:
generated_at: "2026-04-23T14:03:00Z"
generated_at: "2026-04-23T14:55:25Z"
model: gpt-5.4
provider: openai
source_hash: 475923b36e4580d3e4e57014ff2e6b89e9eb52c11b0a0ab1fc8241655b07836e
source_hash: ff7458d18b8a5b716930579241177917fd3edffcf7f6e211c7d570cf76519316
source_path: gateway/cli-backends.md
workflow: 15
---
# CLI 백엔드(대체 런타임)
OpenClaw은 API provider가 다운되었거나,
rate limit에 걸렸거나, 일시적으로 오동작할 때 **로컬 AI CLI**를 **텍스트 전용 대체 경로**로 실행할 수 있습니다. 이 경로는 의도적으로 보수적으로 설계되었습니다:
OpenClaw는 API 제공자가 다운되었거나, 속도 제한에 걸렸거나, 일시적으로 오작동할 때 **로컬 AI CLI**를 **텍스트 전용 대체 경로**로 실행할 수 있습니다. 이는 의도적으로 보수적으로 설계되었습니다.
- **OpenClaw 도구는 직접 주입되지 않지만**, `bundleMcp: true`인 백엔드는 loopback MCP 브리지를 통해 gateway 도구를 받을 수 있습니다.
- 이를 지원하는 CLI를 위한 **JSONL 스트리밍**.
- **세션 지원**(후속 턴의 일관성 유지).
- CLI가 이미지 경로를 받는다면 **이미지 전달 가능**.
- **OpenClaw 도구는 직접 주입되지 않지만**, `bundleMcp: true`가 설정된 백엔드는 loopback MCP 브리지를 통해 gateway 도구를 받을 수 있습니다.
- 이를 지원하는 CLI를 위한 **JSONL 스트리밍**
- **세션이 지원되므로** 후속 턴의 일관성이 유지됩니다.
- CLI가 이미지 경로를 받을 수 있다면 **이미지를 그대로 전달할 수 있습니다**.
이 기능은 기본 경로라기보다 **안전망**으로 설계되었습니다. 외부 API에 의존하지 않고
“항상 동작하는” 텍스트 응답을 원할 때 사용하세요.
이 기능은 주 경로라기보다 **안전망**으로 설계되었습니다. 외부 API에 의존하지 않고 “항상 작동하는” 텍스트 응답이 필요할 때 사용하세요.
ACP 세션 제어, 백그라운드 작업,
스레드/대화 바인딩, 영속적인 외부 코딩 세션이 있는 완전한 harness 런타임이 필요하다면
대신 [ACP Agents](/ko/tools/acp-agents)를 사용하세요. CLI 백엔드는 ACP가 아닙니다.
ACP 세션 제어, 백그라운드 작업, 스레드/대화 바인딩, 영구적인 외부 코딩 세션을 갖춘 전체 하네스 런타임이 필요하다면 대신 [ACP Agents](/ko/tools/acp-agents)를 사용하세요. CLI 백엔드는 ACP가 아닙니다.
## 초보자용 빠른 시작
Codex CLI는 **아무 구성 없이도** 사용할 수 있습니다(번들된 OpenAI plugin이
기본 백엔드를 등록합니다):
설정 없이도 Codex CLI를 사용할 수 있습니다(번들 OpenAI Plugin이 기본 백엔드를 등록합니다).
```bash
openclaw agent --message "hi" --model codex-cli/gpt-5.4
```
gateway가 launchd/systemd 아래에서 실행되고 PATH가 최소 구성이라면, 명령 경로만 추가하세요:
gateway가 launchd/systemd 아래에서 실행되고 PATH가 최소화되어 있다면, 명령 경로만 추가하세요.
```json5
{
@ -56,15 +51,13 @@ gateway가 launchd/systemd 아래에서 실행되고 PATH가 최소 구성이라
}
```
이것으로 충분합니다. CLI 자체 외에 별도의 키나 인증 구성은 필요하지 않습니다.
이것으로 충분합니다. CLI 자체에 필요한 것 외에는 키도, 추가 인증 설정도 필요하지 않습니다.
번들된 CLI 백엔드를 gateway 호스트에서 **기본 메시지 provider**로 사용하는 경우,
이제 OpenClaw은 구성에서 model ref 또는
`agents.defaults.cliBackends` 아래에 해당 백엔드를 명시적으로 참조하면 소유 번들 plugin을 자동으로 로드합니다.
gateway 호스트에서 번들 CLI 백엔드를 **기본 메시지 제공자**로 사용하는 경우, 이제 OpenClaw는 모델 ref 또는 `agents.defaults.cliBackends` 아래에서 해당 백엔드를 설정이 명시적으로 참조하면 소유 번들 Plugin을 자동으로 로드합니다.
## 대체 경로로 사용하기
CLI 백엔드를 대체 목록에 추가하면 기본 모델이 실패할 때만 실행됩니다:
기본 모델이 실패할 때만 실행되도록 대체 목록에 CLI 백엔드를 추가하세요.
```json5
{
@ -85,20 +78,19 @@ CLI 백엔드를 대체 목록에 추가하면 기본 모델이 실패할 때만
참고:
- `agents.defaults.models`(허용 목록)을 사용하는 경우, CLI 백엔드 모델도 여기에 포함해야 합니다.
- 기본 provider가 실패하면(인증, rate limit, timeout), OpenClaw은
다음으로 CLI 백엔드를 시도합니다.
- `agents.defaults.models`(허용 목록)를 사용하는 경우, 여기에 CLI 백엔드 모델도 포함해야 합니다.
- 기본 제공자가 실패하면(인증, 속도 제한, 타임아웃), OpenClaw가 다음으로 CLI 백엔드를 시도합니다.
## 구성 개요
모든 CLI 백엔드는 다음 아래에 있습니다:
모든 CLI 백엔드는 다음 아래에 있습니다.
```
agents.defaults.cliBackends
```
각 항목은 **provider id**(예: `codex-cli`, `my-cli`)를 키로 사용합니다.
provider id는 model ref의 왼쪽 부분이 됩니다:
provider id는 모델 ref의 왼쪽 부분이 됩니다.
```
<provider>/<model>
@ -142,92 +134,78 @@ provider id는 model ref의 왼쪽 부분이 됩니다:
}
```
## 동작 방식
## 작동 방식
1. provider 접두사(`codex-cli/...`)를 기준으로 **백엔드를 선택**합니다.
2. 동일한 OpenClaw 프롬프트 + 워크스페이스 컨텍스트를 사용해 **시스템 프롬프트를 구성**합니다.
3. CLI가 지원하면 세션 id와 함께 **CLI를 실행**하여 기록의 일관성을 유지합니다.
번들된 `claude-cli` 백엔드는 OpenClaw 세션별로 Claude stdio 프로세스를
유지하고 후속 턴을 stream-json stdin으로 보냅니다.
4. **출력을 파싱**(JSON 또는 일반 텍스트)하고 최종 텍스트를 반환합니다.
5. 백엔드별로 **세션 id를 영속화**하여 후속 요청이 같은 CLI 세션을 재사용하게 합니다.
1. provider 접두사(`codex-cli/...`)를 기준으로 **백엔드를 선택합니다**.
2. 동일한 OpenClaw 프롬프트 + 작업공간 컨텍스트를 사용해 **시스템 프롬프트를 구성합니다**.
3. 지원되는 경우 세션 id와 함께 **CLI를 실행하여** 기록의 일관성을 유지합니다.
번들 `claude-cli` 백엔드는 OpenClaw 세션마다 Claude stdio 프로세스를 유지하고 후속 턴을 stream-json stdin을 통해 전송합니다.
4. **출력을 파싱하고**(JSON 또는 일반 텍스트) 최종 텍스트를 반환합니다.
5. 백엔드별로 **세션 id를 유지**하므로 후속 요청에서 동일한 CLI 세션을 재사용합니다.
<Note>
번들된 Anthropic `claude-cli` 백엔드가 다시 지원됩니다. Anthropic 직원이
OpenClaw 스타일 Claude CLI 사용이 다시 허용된다고 알려주었기 때문에, Anthropic이 새 정책을 게시하기 전까지 OpenClaw은 이 통합에 대해
`claude -p` 사용을 허용된 것으로 취급합니다.
번들 Anthropic `claude-cli` 백엔드가 다시 지원됩니다. Anthropic 직원이 OpenClaw 스타일 Claude CLI 사용이 다시 허용된다고 알려왔기 때문에, Anthropic이 새로운 정책을 발표하지 않는 한 OpenClaw는 이 통합에 대해 `claude -p` 사용을 승인된 것으로 취급합니다.
</Note>
번들된 OpenAI `codex-cli` 백엔드는 OpenClaw의 시스템 프롬프트를
Codex의 `model_instructions_file` 구성 override(`-c
model_instructions_file="..."`)를 통해 전달합니다. Codex는 Claude 스타일의
`--append-system-prompt` 플래그를 제공하지 않으므로, OpenClaw은 새 Codex CLI 세션마다 조합된 프롬프트를 임시 파일에 기록합니다.
번들 OpenAI `codex-cli` 백엔드는 OpenClaw의 시스템 프롬프트를 Codex의 `model_instructions_file` 설정 오버라이드(`-c
model_instructions_file="..."`)를 통해 전달합니다. Codex는 Claude 스타일의 `--append-system-prompt` 플래그를 제공하지 않으므로, OpenClaw는 새 Codex CLI 세션마다 조합된 프롬프트를 임시 파일에 기록합니다.
번들된 Anthropic `claude-cli` 백엔드는 OpenClaw Skills 스냅샷을
두 가지 방식으로 받습니다: 추가된 시스템 프롬프트의 압축된 OpenClaw Skills 카탈로그, 그리고
`--plugin-dir`로 전달되는 임시 Claude Code plugin입니다. 이 plugin에는 해당 에이전트/세션에 적합한 Skills만 포함되므로, Claude Code의 네이티브 skill resolver는 OpenClaw이 프롬프트에서 광고했을 것과 동일한 필터링된 집합을 보게 됩니다. Skill env/API key override는 여전히 OpenClaw이 실행을 위해 child process 환경에 적용합니다.
번들 Anthropic `claude-cli` 백엔드는 OpenClaw Skills 스냅샷을 두 가지 방식으로 받습니다. 하나는 추가된 시스템 프롬프트의 간결한 OpenClaw Skills 카탈로그이고, 다른 하나는 `--plugin-dir`로 전달되는 임시 Claude Code Plugin입니다. 이 Plugin에는 해당 에이전트/세션에 적합한 Skills만 포함되므로, Claude Code의 네이티브 skill resolver는 OpenClaw가 프롬프트에서 광고했을 것과 동일한 필터링된 집합을 보게 됩니다. Skill env/API 키 오버라이드는 여전히 OpenClaw가 실행 시 자식 프로세스 환경에 적용합니다.
OpenClaw가 번들 `claude-cli` 백엔드를 사용하려면, Claude Code 자체가 이미 같은 호스트에서 로그인되어 있어야 합니다.
```bash
claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default
```
`claude` 바이너리가 이미 `PATH`에 없을 때만 `agents.defaults.cliBackends.claude-cli.command`를 사용하세요.
## 세션
- CLI가 세션을 지원하면 `sessionArg`(예: `--session-id`) 또는
ID를 여러 플래그에 삽입해야 할 때 `sessionArgs`(placeholder `{sessionId}`)를 설정하세요.
- CLI가 다른 플래그를 사용하는 **resume 하위 명령**을 쓴다면
`resumeArgs`(재개 시 `args`를 대체)와 선택적으로 `resumeOutput`
(JSON이 아닌 재개용)를 설정하세요.
- CLI가 세션을 지원하면 `sessionArg`(예: `--session-id`) 또는, ID를 여러 플래그에 삽입해야 할 때 `sessionArgs`(플레이스홀더 `{sessionId}`)를 설정하세요.
- CLI가 서로 다른 플래그를 가진 **resume 하위 명령**을 사용한다면, `resumeArgs`(`args`를 대체)를 설정하고 필요하다면 `resumeOutput`(JSON이 아닌 resume용)을 설정하세요.
- `sessionMode`:
- `always`: 항상 세션 id를 전송(저장된 값이 없으면 새 UUID).
- `existing`: 이전에 저장된 세션 id가 있을 때만 전송.
- `none`: 세션 id를 전송하지 않음.
- `claude-cli`의 기본값은 `liveSession: "claude-stdio"`, `output: "jsonl"`,
`input: "stdin"`이므로 후속 턴은 활성 상태일 때 라이브 Claude 프로세스를 재사용합니다.
이제 warm stdio가 기본값이며, transport 필드를 생략한 사용자 지정 구성에도 적용됩니다.
Gateway가 재시작되거나 유휴 프로세스가 종료되면,
OpenClaw은 저장된 Claude 세션 id로 재개합니다. 저장된 세션
id는 재개 전에 읽을 수 있는 기존 프로젝트 transcript와 대조 검증되므로,
phantom 바인딩은 `--resume` 아래에서 조용히 새 Claude CLI 세션을 시작하는 대신 `reason=transcript-missing`과 함께 제거됩니다.
- 저장된 CLI 세션은 provider 소유 연속성입니다. 암시적인 일일 세션
재설정은 이를 끊지 않으며, `/reset`과 명시적인 `session.reset` 정책은 끊습니다.
- `always`: 항상 세션 id를 전송합니다(저장된 값이 없으면 새 UUID 생성).
- `existing`: 이전에 저장된 세션 id가 있을 때만 전송합니다.
- `none`: 세션 id를 전송하지 않습니다.
- `claude-cli`는 기본값으로 `liveSession: "claude-stdio"`, `output: "jsonl"`, `input: "stdin"`을 사용하므로 후속 턴에서 활성 상태의 Claude 프로세스를 재사용합니다. 이제 따뜻한 stdio가 기본값이며, 전송 필드를 생략한 사용자 정의 구성에도 적용됩니다. Gateway가 재시작되거나 유휴 프로세스가 종료되면 OpenClaw는 저장된 Claude 세션 id에서 재개합니다. 저장된 세션 id는 재개 전에 기존의 읽을 수 있는 프로젝트 transcript와 대조하여 검증되므로, 허상 바인딩은 `--resume`으로 조용히 새 Claude CLI 세션을 시작하는 대신 `reason=transcript-missing`과 함께 정리됩니다.
- 저장된 CLI 세션은 provider가 소유하는 연속성입니다. 암묵적인 일일 세션 재설정은 이를 끊지 않으며, `/reset` 및 명시적 `session.reset` 정책만 끊습니다.
직렬화 참고:
직렬화 관련 참고:
- `serialize: true`는 같은 lane의 실행 순서를 유지합니다.
- `serialize: true`는 동일 lane의 실행 순서를 유지합니다.
- 대부분의 CLI는 하나의 provider lane에서 직렬화합니다.
- OpenClaw은 선택된 인증 식별자가 바뀌면 저장된 CLI 세션 재사용을 중단합니다.
여기에는 변경된 auth profile id, 정적 API key, 정적 토큰,
또는 CLI가 이를 노출하는 경우 OAuth 계정 식별자가 포함됩니다. OAuth access 및 refresh token
회전은 저장된 CLI 세션을 끊지 않습니다. CLI가 안정적인 OAuth 계정 id를 노출하지 않는다면, OpenClaw은 해당 CLI가 재개 권한을 강제하도록 둡니다.
- OpenClaw는 선택된 인증 ID가 변경되면 저장된 CLI 세션 재사용을 중단합니다. 여기에는 auth profile id 변경, 정적 API 키, 정적 토큰, 또는 CLI가 이를 노출하는 경우 OAuth 계정 ID 변경이 포함됩니다. OAuth 액세스 및 리프레시 토큰 순환은 저장된 CLI 세션을 끊지 않습니다. CLI가 안정적인 OAuth 계정 id를 노출하지 않으면, OpenClaw는 해당 CLI가 resume 권한을 강제하도록 둡니다.
## 이미지(전달)
## 이미지(패스스루)
CLI가 이미지 경로를 받을 수 있다면 `imageArg`를 설정하세요:
CLI가 이미지 경로를 받을 수 있다면 `imageArg`를 설정하세요.
```json5
imageArg: "--image",
imageMode: "repeat"
```
OpenClaw은 base64 이미지를 임시 파일로 기록합니다. `imageArg`가 설정되어 있으면 해당
경로가 CLI 인수로 전달됩니다. `imageArg`가 없으면 OpenClaw은
파일 경로를 프롬프트에 추가(path injection)하며, 이는 일반 경로에서 로컬 파일을 자동 로드하는 CLI에는 충분합니다.
OpenClaw는 base64 이미지를 임시 파일에 기록합니다. `imageArg`가 설정되어 있으면 해당 경로가 CLI 인수로 전달됩니다. `imageArg`가 없으면 OpenClaw는 파일 경로를 프롬프트에 추가(path injection)하며, 이는 일반 경로로부터 로컬 파일을 자동 로드하는 CLI에는 충분합니다.
## 입력 / 출력
- `output: "json"`(기본값)은 JSON을 파싱하고 텍스트 + 세션 id를 추출하려고 시도합니다.
- Gemini CLI JSON 출력의 경우, OpenClaw은 `usage`가 없거나 비어 있을 때
`response`에서 답글 텍스트를, `stats`에서 사용량을 읽습니다.
- `output: "jsonl"`은 JSONL 스트림(예: Codex CLI `--json`)을 파싱하고 최종 agent 메시지와
존재하는 경우 세션 식별자를 추출합니다.
- Gemini CLI JSON 출력의 경우, `usage`가 없거나 비어 있으면 OpenClaw는 `response`에서 응답 텍스트를, `stats`에서 사용량을 읽습니다.
- `output: "jsonl"`은 JSONL 스트림(예: Codex CLI `--json`)을 파싱하고 존재할 경우 최종 에이전트 메시지와 세션 식별자를 추출합니다.
- `output: "text"`는 stdout을 최종 응답으로 취급합니다.
입력 모드:
- `input: "arg"`(기본값)은 프롬프트를 마지막 CLI 인수로 전달합니다.
- `input: "stdin"`은 프롬프트를 stdin으로 보냅니다.
- `input: "stdin"`은 프롬프트를 stdin으로 전송합니다.
- 프롬프트가 매우 길고 `maxPromptArgChars`가 설정되어 있으면 stdin이 사용됩니다.
## 기본값(plugin 소유)
## 기본값(Plugin 소유)
번들된 OpenAI plugin은 `codex-cli`에 대한 기본값도 등록합니다:
번들 OpenAI Plugin은 `codex-cli`에 대한 기본값도 등록합니다.
- `command: "codex"`
- `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
@ -238,7 +216,7 @@ OpenClaw은 base64 이미지를 임시 파일로 기록합니다. `imageArg`가
- `imageArg: "--image"`
- `sessionMode: "existing"`
번들된 Google plugin도 `google-gemini-cli`에 대한 기본값을 등록합니다:
번들 Google Plugin은 `google-gemini-cli`에 대한 기본값도 등록합니다.
- `command: "gemini"`
- `args: ["--output-format", "json", "--prompt", "{prompt}"]`
@ -249,31 +227,27 @@ OpenClaw은 base64 이미지를 임시 파일로 기록합니다. `imageArg`가
- `sessionMode: "existing"`
- `sessionIdFields: ["session_id", "sessionId"]`
전제 조건: 로컬 Gemini CLI가 설치되어 있어야 하며
PATH에서 `gemini`로 사용할 수 있어야 합니다(`brew install gemini-cli` 또는
`npm install -g @google/gemini-cli`).
전제 조건: 로컬 Gemini CLI가 설치되어 있고 `PATH`에서 `gemini`로 사용할 수 있어야 합니다(`brew install gemini-cli` 또는 `npm install -g @google/gemini-cli`).
Gemini CLI JSON 참고:
- 답글 텍스트는 JSON `response` 필드에서 읽습니다.
- `usage`가 없거나 비어 있으면 사용량은 `stats`로 대체됩니다.
- 응답 텍스트는 JSON `response` 필드에서 읽습니다.
- 사용량은 `usage`가 없거나 비어 있을 때 `stats`로 대체됩니다.
- `stats.cached`는 OpenClaw `cacheRead`로 정규화됩니다.
- `stats.input`이 없으면 OpenClaw은
`stats.input_tokens - stats.cached`에서 입력 토큰을 계산합니다.
- `stats.input`이 없으면 OpenClaw는 `stats.input_tokens - stats.cached`에서 입력 토큰 수를 도출합니다.
필요한 경우에만 override하세요(일반적인 경우: 절대 `command` 경로).
필요한 경우에만 오버라이드하세요(일반적으로는 절대 `command` 경로).
## plugin 소유 기본값
## Plugin 소유 기본값
CLI 백엔드 기본값은 이제 plugin 표면의 일부입니다:
이제 CLI 백엔드 기본값은 Plugin 표면의 일부입니다.
- Plugins는 `api.registerCliBackend(...)`로 이를 등록합니다.
- 백엔드 `id`는 model ref의 provider 접두사가 됩니다.
- `agents.defaults.cliBackends.<id>` 아래의 사용자 구성은 여전히 plugin 기본값을 override합니다.
- 백엔드별 구성 정리는 선택적
`normalizeConfig` hook을 통해 plugin 소유로 유지됩니다.
- 백엔드 `id`는 모델 ref의 provider 접두사가 됩니다.
- `agents.defaults.cliBackends.<id>`의 사용자 구성은 여전히 Plugin 기본값을 오버라이드합니다.
- 백엔드별 구성 정리는 선택적 `normalizeConfig` 훅을 통해 Plugin이 계속 소유합니다.
작은 프롬프트/메시지 호환성 shim이 필요한 plugins는 provider나 CLI 백엔드를 교체하지 않고도 양방향 텍스트 변환을 선언할 수 있습니다:
작은 프롬프트/메시지 호환성 shim이 필요한 Plugins는 provider나 CLI 백엔드를 교체하지 않고 양방향 텍스트 변환을 선언할 수 있습니다.
```typescript
api.registerTextTransforms({
@ -290,49 +264,41 @@ api.registerTextTransforms({
});
```
`input`은 CLI에 전달되는 시스템 프롬프트와 사용자 프롬프트를 재작성합니다. `output`은 OpenClaw이 자체 제어 마커와 채널 전달을 처리하기 전에 스트리밍된 assistant delta와 파싱된 최종 텍스트를 재작성합니다.
`input`은 CLI에 전달되는 시스템 프롬프트와 사용자 프롬프트를 다시 씁니다. `output`은 OpenClaw가 자체 제어 마커와 채널 전달을 처리하기 전에 스트리밍된 어시스턴트 델타와 파싱된 최종 텍스트를 다시 씁니다.
Claude Code stream-json 호환 JSONL을 출력하는 CLI의 경우,
해당 백엔드 구성에 `jsonlDialect: "claude-stream-json"`를 설정하세요.
Claude Code stream-json 호환 JSONL을 출력하는 CLI의 경우, 해당 백엔드 구성에 `jsonlDialect: "claude-stream-json"`를 설정하세요.
## 번들 MCP 오버레이
CLI 백엔드는 OpenClaw 도구 호출을 **직접** 받지 않지만, 백엔드는
`bundleMcp: true`로 생성된 MCP 구성 오버레이에 옵트인할 수 있습니다.
CLI 백엔드는 OpenClaw 도구 호출을 **직접** 받지 않지만, 백엔드는 `bundleMcp: true`로 생성된 MCP 구성 오버레이를 선택적으로 사용할 수 있습니다.
현재 번들 동작:
- `claude-cli`: 생성된 strict MCP 구성 파일
- `codex-cli`: `mcp_servers`용 인라인 구성 override
- `google-gemini-cli`: 생성된 Gemini 시스템 설정 파일
- `claude-cli`: 생성된 strict MCP config 파일
- `codex-cli`: `mcp_servers`에 대한 인라인 config 오버라이드
- `google-gemini-cli`: 생성된 Gemini 시스템 settings 파일
bundle MCP가 활성화되면 OpenClaw은:
bundle MCP가 활성화되면, OpenClaw는 다음을 수행합니다.
- gateway 도구를 CLI 프로세스에 노출하는 loopback HTTP MCP 서버를 실행합니다
- 세션별 토큰(`OPENCLAW_MCP_TOKEN`)으로 브리지를 인증합니다
- 현재 세션, 계정, 채널 컨텍스트로 도구 액세스를 제한합니다
- 현재 워크스페이스에 대해 활성화된 bundle-MCP 서버를 로드합니다
- 이를 기존 백엔드 MCP 구성/설정 형태와 병합합니다
- 소유 extension의 백엔드 소유 통합 모드를 사용해 실행 구성을 재작성합니다
- CLI 프로세스에 gateway 도구를 노출하는 loopback HTTP MCP 서버를 시작합니다.
- 세션별 토큰(`OPENCLAW_MCP_TOKEN`)으로 브리지를 인증합니다.
- 도구 액세스를 현재 세션, 계정, 채널 컨텍스트로 제한합니다.
- 현재 작업공간에 대해 활성화된 bundle-MCP 서버를 로드합니다.
- 기존 백엔드 MCP config/settings 형태와 병합합니다.
- 소유 extension의 백엔드 소유 통합 모드를 사용해 실행 구성을 다시 씁니다.
활성화된 MCP 서버가 없더라도, 백엔드가 bundle MCP에 옵트인한 경우
백그라운드 실행이 격리된 상태를 유지하도록 OpenClaw은 여전히 strict 구성을 주입합니다.
활성화된 MCP 서버가 없더라도, 백엔드가 bundle MCP를 선택하면 OpenClaw는 백그라운드 실행이 격리된 상태를 유지하도록 여전히 strict config를 주입합니다.
## 제한 사항
- **직접적인 OpenClaw 도구 호출은 없습니다.** OpenClaw은 CLI 백엔드 프로토콜에
도구 호출을 주입하지 않습니다. 백엔드는 `bundleMcp: true`에 옵트인한 경우에만
gateway 도구를 볼 수 있습니다.
- **스트리밍은 백엔드별입니다.** 일부 백엔드는 JSONL을 스트리밍하고, 다른 백엔드는
종료 시점까지 버퍼링합니다.
- **직접적인 OpenClaw 도구 호출은 없습니다.** OpenClaw는 CLI 백엔드 프로토콜에 도구 호출을 주입하지 않습니다. 백엔드는 `bundleMcp: true`를 선택한 경우에만 gateway 도구를 볼 수 있습니다.
- **스트리밍은 백엔드마다 다릅니다.** 일부 백엔드는 JSONL을 스트리밍하고, 다른 백엔드는 종료될 때까지 버퍼링합니다.
- **구조화된 출력**은 CLI의 JSON 형식에 따라 달라집니다.
- **Codex CLI 세션**은 텍스트 출력으로 재개되며(JSONL 아님), 이는 초기 `--json` 실행보다
구조화 수준이 낮습니다. OpenClaw 세션 자체는 여전히 정상적으로 동작합니다.
- **Codex CLI 세션**은 텍스트 출력으로 재개되며(JSONL 없음), 이는 초기 `--json` 실행보다 구조화 수준이 낮습니다. OpenClaw 세션은 여전히 정상적으로 동작합니다.
## 문제 해결
- **CLI를 찾을 수 없음**: `command`를 전체 경로로 설정하세요.
- **잘못된 모델 이름**: `modelAliases`를 사용해 `provider/model` → CLI 모델로 매핑하세요.
- **세션 연속성이 없음**: `sessionArg`가 설정되어 있고 `sessionMode`가
`none`이 아닌지 확인하세요(Codex CLI는 현재 JSON 출력으로 재개할 수 없습니다).
- **이미지가 무시됨**: `imageArg`를 설정하세요(그리고 CLI가 파일 경로를 지원하는지 확인하세요).
- **세션 연속성이 없음**: `sessionArg`가 설정되어 있고 `sessionMode`가 `none`이 아닌지 확인하세요(Codex CLI는 현재 JSON 출력으로 재개할 수 없습니다).
- **이미지가 무시됨**: `imageArg`를 설정하고(그리고 CLI가 파일 경로를 지원하는지 확인하세요).

1072
docs/ko/help/testing.md
View File

File diff suppressed because it is too large Load Diff