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-30 20:10:49 +00:00
parent f7c6432fa2
commit 9ffba1b1d4
6 changed files with 1131 additions and 1247 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
docs/ko/cli/doctor.md
View File

@ -1,21 +1,21 @@
---
read_when:
- 연결/인증 문제가 있고 안내에 따라 해결하고 싶은 경우
- 업데이트한 후 정상 동작 확인이 필요합니다
summary: '`openclaw doctor`에 대한 CLI 참조 (상태 점검 + 안내형 복구)'
- 연결/인증 문제가 있으며 단계별 수정 안내가 필요한 경우
- 업데이트한 뒤 정상 동작을 확인하고 싶다면
summary: '`openclaw doctor`의 CLI 참조(상태 확인 + 안내식 복구)'
title: 진단
x-i18n:
generated_at: "2026-04-30T06:22:41Z"
generated_at: "2026-04-30T20:05:25Z"
model: gpt-5.5
provider: openai
source_hash: 9985c84d23861dd9468a4659ee00519573fe6d540c436548da0a68067dbabc4c
source_hash: 265d82a10da086cf89687886e491be018a720b70021e0b26bd8f39b25a907e14
source_path: cli/doctor.md
workflow: 16
---
# `openclaw doctor`
Gateway와 채널의 상태 점검 + 빠른 수정입니다.
Gateway와 채널을 위한 상태 확인 + 빠른 수정.
관련:
@ -34,39 +34,40 @@ openclaw doctor --generate-gateway-token
## 옵션
- `--no-workspace-suggestions`: 워크스페이스 메모리/검색 제안을 비활성화합니다
- `--yes`: 확인 없이 기본값을 수락합니다
- `--repair`: 확인 없이 권장 복구를 적용합니다
- `--fix`: `--repair`의 별칭입니다
- `--force`: 필요할 때 사용자 지정 서비스 구성을 덮어쓰는 것을 포함해 적극적인 복구를 적용합니다
- `--non-interactive`: 프롬프트 없이 실행합니다. 안전한 마이그레이션만 수행합니다
- `--generate-gateway-token`: Gateway 토큰을 생성하고 구성합니다
- `--deep`: 추가 Gateway 설치를 찾기 위해 시스템 서비스를 스캔합니다
- `--no-workspace-suggestions`: 작업 영역 메모리/검색 제안 비활성화
- `--yes`: 프롬프트 없이 기본값 수락
- `--repair`: 프롬프트 없이 권장 복구 적용
- `--fix`: `--repair`의 별칭
- `--force`: 필요 시 사용자 지정 서비스 구성을 덮어쓰는 것을 포함해 적극적인 복구 적용
- `--non-interactive`: 프롬프트 없이 실행, 안전한 마이그레이션만 수행
- `--generate-gateway-token`: Gateway 토큰 생성 및 구성
- `--deep`: 추가 Gateway 설치를 찾기 위해 시스템 서비스 스캔
참고:
- 대화형 프롬프트(예: 키체인/OAuth 수정)는 stdin이 TTY이고 `--non-interactive`가 설정되지 **않은** 경우에만 실행됩니다. 헤드리스 실행(cron, Telegram, 터미널 없음)은 프롬프트를 건너뜁니다.
- 성능: 비대화형 `doctor` 실행은 헤드리스 상태 점검이 빠르게 유지되도록 즉시 Plugin 로드를 건너뜁니다. 대화형 세션은 검사에 Plugin 기여가 필요할 때 여전히 Plugin을 완전히 로드합니다.
- `--fix`(`--repair`의 별칭)는 `~/.openclaw/openclaw.json.bak`에 백업을 쓰고, 알 수 없는 구성 키를 삭제하며 각 제거 항목을 나열합니다.
- 상태 무결성 검사는 이제 세션 디렉터리의 고아 트랜스크립트 파일을 감지합니다. 이를 `.deleted.<timestamp>`로 보관하려면 대화형 확인이 필요합니다. `--fix`, `--yes`, 헤드리스 실행은 이를 그대로 둡니다.
- Doctor는 레거시 cron 작업 형태를 찾기 위해 `~/.openclaw/cron/jobs.json`(또는 `cron.store`)도 스캔하며, 스케줄러가 런타임에 자동 정규화해야 하기 전에 이를 제자리에서 다시 쓸 수 있습니다.
- Doctor는 패키징된 전역 설치에 쓰지 않고 누락된 번들 Plugin 런타임 의존성을 복구합니다. root 소유 npm 설치 또는 강화된 systemd 유닛의 경우 `OPENCLAW_PLUGIN_STAGE_DIR`을 `/var/lib/openclaw/plugin-runtime-deps` 같은 쓰기 가능한 디렉터리로 설정하세요. `/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps` 같은 경로 목록도 사용할 수 있으며, 앞쪽 루트는 읽기 전용 조회 계층이고 마지막 루트가 복구 대상입니다.
- Doctor는 Plugin 검색이 정상일 때 `plugins.allow`/`plugins.entries`에서 누락된 Plugin ID를 제거하고, 일치하는 매달린 채널 구성, Heartbeat 대상, 채널 모델 재정의도 제거하여 오래된 Plugin 구성을 복구합니다.
- Doctor는 영향을 받는 `plugins.entries.<id>` 항목을 비활성화하고 잘못된 `config` 페이로드를 제거하여 잘못된 Plugin 구성을 격리합니다. Gateway 시작은 이미 해당 잘못된 Plugin만 건너뛰므로 다른 Plugin과 채널은 계속 실행될 수 있습니다.
- 다른 슈퍼바이저가 Gateway 수명 주기를 소유하는 경우 `OPENCLAW_SERVICE_REPAIR_POLICY=external`을 설정하세요. Doctor는 여전히 Gateway/서비스 상태를 보고하고 비서비스 복구를 적용하지만, 서비스 설치/시작/재시작/부트스트랩 및 레거시 서비스 정리는 건너뜁니다.
- Linux에서 doctor는 비활성 상태인 추가 Gateway 유사 systemd 유닛을 무시하며, 복구 중 실행 중인 systemd Gateway 서비스의 명령/진입점 메타데이터를 다시 쓰지 않습니다. 활성 런처를 의도적으로 교체하려면 먼저 서비스를 중지하거나 `openclaw gateway install --force`를 사용하세요.
- Doctor는 레거시 평면 Talk 구성(`talk.voiceId`, `talk.modelId` 등)을 `talk.provider` + `talk.providers.<provider>`로 자동 마이그레이션합니다.
- `doctor --fix`를 반복 실행해도 유일한 차이가 객체 키 순서뿐이면 더 이상 Talk 정규화를 보고/적용하지 않습니다.
- Doctor에는 메모리 검색 준비 상태 검사가 포함되며, 임베딩 자격 증명이 없을 때 `openclaw configure --section model`을 권장할 수 있습니다.
- Doctor는 명령 소유자가 구성되지 않았을 때 경고합니다. 명령 소유자는 소유자 전용 명령을 실행하고 위험한 작업을 승인할 수 있는 인간 운영자 계정입니다. DM 페어링은 누군가가 봇과 대화할 수 있게 해줄 뿐입니다. 첫 소유자 부트스트랩이 생기기 전에 발신자를 승인했다면 `commands.ownerAllowFrom`을 명시적으로 설정하세요.
- 샌드박스 모드가 활성화되어 있지만 Docker를 사용할 수 없으면 doctor는 해결 방법(`install Docker` 또는 `openclaw config set agents.defaults.sandbox.mode off`)과 함께 신호가 높은 경고를 보고합니다.
- `gateway.auth.token`/`gateway.auth.password`가 SecretRef로 관리되고 현재 명령 경로에서 사용할 수 없으면 doctor는 읽기 전용 경고를 보고하고 평문 대체 자격 증명을 쓰지 않습니다.
- 수정 경로에서 채널 SecretRef 검사가 실패하면 doctor는 조기 종료하지 않고 계속 진행하며 경고를 보고합니다.
- Telegram `allowFrom` 사용자 이름 자동 확인(`doctor --fix`)에는 현재 명령 경로에서 확인 가능한 Telegram 토큰이 필요합니다. 토큰 검사를 사용할 수 없으면 doctor는 경고를 보고하고 해당 실행의 자동 확인을 건너뜁니다.
- 대화형 프롬프트(예: keychain/OAuth 수정)는 stdin이 TTY이고 `--non-interactive`가 설정되어 **있지 않을 때만** 실행됩니다. 헤드리스 실행(cron, Telegram, 터미널 없음)은 프롬프트를 건너뜁니다.
- 성능: 비대화형 `doctor` 실행은 헤드리스 상태 확인이 빠르게 유지되도록 적극적인 Plugin 로딩을 건너뜁니다. 대화형 세션은 확인에 Plugin 기여가 필요할 때 여전히 Plugin을 완전히 로드합니다.
- `--fix`(`--repair`의 별칭)는 백업을 `~/.openclaw/openclaw.json.bak`에 쓰고 알 수 없는 구성 키를 삭제하며, 각 제거 항목을 나열합니다.
- 상태 무결성 검사는 이제 세션 디렉터리에서 고아 transcript 파일을 감지합니다. 이를 `.deleted.<timestamp>`로 보관하려면 대화형 확인이 필요합니다. `--fix`, `--yes`, 헤드리스 실행은 해당 파일을 그대로 둡니다.
- Doctor는 레거시 Cron 작업 형태를 찾기 위해 `~/.openclaw/cron/jobs.json`(또는 `cron.store`)도 스캔하며, 스케줄러가 런타임에 자동 정규화해야 하기 전에 제자리에서 다시 쓸 수 있습니다.
- Doctor는 패키징된 전역 설치에 쓰지 않고 누락된 번들 Plugin 런타임 의존성을 복구합니다. root 소유 npm 설치 또는 강화된 systemd unit의 경우 `OPENCLAW_PLUGIN_STAGE_DIR`를 `/var/lib/openclaw/plugin-runtime-deps` 같은 쓰기 가능한 디렉터리로 설정하세요. `/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps` 같은 경로 목록일 수도 있으며, 앞쪽 루트는 읽기 전용 조회 계층이고 마지막 루트가 복구 대상입니다.
- Doctor는 Plugin 검색이 정상일 때 `plugins.allow`/`plugins.entries`에서 누락된 Plugin ID와 일치하는 매달린 채널 구성, Heartbeat 대상, 채널 모델 재정의를 제거하여 오래된 Plugin 구성을 복구합니다.
- Doctor는 영향을 받은 `plugins.entries.<id>` 항목을 비활성화하고 유효하지 않은 `config` 페이로드를 제거하여 잘못된 Plugin 구성을 격리합니다. Gateway 시작은 이미 해당 잘못된 Plugin만 건너뛰므로 다른 Plugin과 채널은 계속 실행될 수 있습니다.
- 다른 supervisor가 Gateway 수명 주기를 소유하는 경우 `OPENCLAW_SERVICE_REPAIR_POLICY=external`을 설정하세요. Doctor는 여전히 Gateway/서비스 상태를 보고하고 비서비스 복구를 적용하지만, 서비스 설치/시작/재시작/bootstrap 및 레거시 서비스 정리는 건너뜁니다.
- Linux에서 doctor는 비활성 추가 Gateway 유사 systemd unit을 무시하며, 복구 중 실행 중인 systemd Gateway 서비스의 command/entrypoint 메타데이터를 다시 쓰지 않습니다. 활성 launcher를 의도적으로 교체하려면 먼저 서비스를 중지하거나 `openclaw gateway install --force`를 사용하세요.
- Doctor는 레거시 플랫 Talk 구성(`talk.voiceId`, `talk.modelId` 및 관련 항목)을 `talk.provider` + `talk.providers.<provider>`로 자동 마이그레이션합니다.
- 반복되는 `doctor --fix` 실행은 유일한 차이가 객체 키 순서뿐인 경우 더 이상 Talk 정규화를 보고/적용하지 않습니다.
- Doctor에는 메모리 검색 준비 상태 확인이 포함되며 embedding 자격 증명이 없을 때 `openclaw configure --section model`을 권장할 수 있습니다.
- Doctor는 명령 소유자가 구성되어 있지 않으면 경고합니다. 명령 소유자는 소유자 전용 명령을 실행하고 위험한 작업을 승인할 수 있는 인간 운영자 계정입니다. DM 페어링은 누군가가 bot과 대화할 수 있게 할 뿐입니다. 첫 소유자 bootstrap이 생기기 전에 보낸 사람을 승인했다면 `commands.ownerAllowFrom`를 명시적으로 설정하세요.
- Doctor는 Codex 모드 agent가 구성되어 있고 운영자의 Codex 홈에 개인 Codex CLI 자산이 있으면 경고합니다. 로컬 Codex app-server 실행은 agent별 격리된 홈을 사용하므로, 의도적으로 승격해야 하는 자산의 인벤토리를 작성하려면 `openclaw migrate codex --dry-run`을 사용하세요.
- sandbox 모드가 활성화되어 있지만 Docker를 사용할 수 없으면 doctor는 해결 방법(`install Docker` 또는 `openclaw config set agents.defaults.sandbox.mode off`)이 포함된 높은 신호의 경고를 보고합니다.
- `gateway.auth.token`/`gateway.auth.password`가 SecretRef로 관리되고 현재 명령 경로에서 사용할 수 없으면 doctor는 읽기 전용 경고를 보고하고 plaintext 대체 자격 증명을 쓰지 않습니다.
- 수정 경로에서 채널 SecretRef 검사가 실패하면 doctor는 조기 종료하지 않고 계속 진행한 뒤 경고를 보고합니다.
- Telegram `allowFrom` 사용자 이름 자동 확인(`doctor --fix`)에는 현재 명령 경로에서 확인 가능한 Telegram 토큰이 필요합니다. 토큰 검사를 사용할 수 없으면 doctor는 경고를 보고하고 해당 실행에서 자동 확인을 건너뜁니다.
## macOS: `launchctl` 환경 재정의
이전에 `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`(또는 `...PASSWORD`)를 실행했다면 해당 값이 구성 파일을 재정의하여 지속적인 “unauthorized” 오류를 일으킬 수 있습니다.
이전에 `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`(또는 `...PASSWORD`)를 실행했다면, 해당 값이 구성 파일을 재정의하여 지속적인 “unauthorized” 오류를 일으킬 수 있습니다.
```bash
launchctl getenv OPENCLAW_GATEWAY_TOKEN

123
docs/ko/cli/migrate.md
View File

@ -1,24 +1,24 @@
---
read_when:
- Hermes 또는 다른 에이전트 시스템에서 OpenClaw로 마이그레이션하려는 경우
- Hermes나 다른 에이전트 시스템에서 OpenClaw로 마이그레이션하려는 경우
- Plugin 소유 마이그레이션 제공자를 추가하고 있습니다
summary: '`openclaw migrate`의 CLI 참조(다른 에이전트 시스템에서 상태 가져오기)'
summary: '`openclaw migrate`에 대한 CLI 참조(다른 에이전트 시스템에서 상태 가져오기)'
title: 마이그레이션
x-i18n:
generated_at: "2026-04-30T06:23:56Z"
generated_at: "2026-04-30T20:05:26Z"
model: gpt-5.5
provider: openai
source_hash: d3db14c16b8f9dcbf86a4f12558cf4e8555aa9a255637034fb804148996a225e
source_hash: ffcd9e874bdaa0a5195e712d4fccd7b3d53034cb362c7f7462e9c7df72477b1a
source_path: cli/migrate.md
workflow: 16
---
# `openclaw migrate`
Plugin 소유 마이그레이션 제공자를 통해 다른 에이전트 시스템의 상태를 가져옵니다. 번들 제공자는 [Claude](/ko/install/migrating-claude)와 [Hermes](/ko/install/migrating-hermes)를 지원하며, 서드파티 Plugin은 추가 제공자를 등록할 수 있습니다.
Plugin 소유 마이그레이션 제공자를 통해 다른 에이전트 시스템의 상태를 가져옵니다. 번들 제공자는 Codex CLI 상태, [Claude](/ko/install/migrating-claude), [Hermes](/ko/install/migrating-hermes)를 포함하며, 서드파티 plugins는 추가 제공자를 등록할 수 있습니다.
<Tip>
사용자 대상 안내는 [Claude에서 마이그레이션](/ko/install/migrating-claude) 및 [Hermes에서 마이그레이션](/ko/install/migrating-hermes)을 참조하세요. [마이그레이션 허브](/ko/install/migrating)는 모든 경로를 나열합니다.
사용자 대상 안내는 [Claude에서 마이그레이션](/ko/install/migrating-claude) 및 [Hermes에서 마이그레이션](/ko/install/migrating-hermes)를 참조하세요. [마이그레이션 허브](/ko/install/migrating)는 모든 경로를 나열합니다.
</Tip>
## 명령
@ -26,8 +26,12 @@ Plugin 소유 마이그레이션 제공자를 통해 다른 에이전트 시스
```bash
openclaw migrate list
openclaw migrate claude --dry-run
openclaw migrate codex --dry-run
openclaw migrate codex --skill gog-vault77-google-workspace
openclaw migrate hermes --dry-run
openclaw migrate hermes
openclaw migrate apply codex --yes --skill gog-vault77-google-workspace
openclaw migrate apply codex --yes
openclaw migrate apply claude --yes
openclaw migrate apply hermes --yes
openclaw migrate apply hermes --include-secrets --yes
@ -43,43 +47,46 @@ openclaw onboard --import-from hermes --import-source ~/.hermes
계획을 만들고 상태를 변경하지 않은 채 종료합니다.
</ParamField>
<ParamField path="--from <path>" type="string">
원본 상태 디렉터리를 재정의합니다. Hermes의 기본값은 `~/.hermes`입니다.
소스 상태 디렉터리를 재정의합니다. Hermes 기본값은 `~/.hermes`입니다.
</ParamField>
<ParamField path="--include-secrets" type="boolean">
지원되는 자격 증명을 가져옵니다. 기본적으로 꺼져 있습니다.
지원되는 자격 증명을 가져옵니다. 기본값은 꺼짐입니다.
</ParamField>
<ParamField path="--overwrite" type="boolean">
계획에서 충돌을 보고할 때 적용 작업이 기존 대상을 대체하도록 허용합니다.
계획에서 충돌을 보고할 때 apply가 기존 대상을 교체하도록 허용합니다.
</ParamField>
<ParamField path="--yes" type="boolean">
확인 프롬프트를 건너뜁니다. 비대화형 모드에서 필요합니다.
</ParamField>
<ParamField path="--skill <name>" type="string">
skill 이름 또는 항목 id로 하나의 skill 복사 항목을 선택합니다. 여러 skills를 마이그레이션하려면 플래그를 반복하세요. 생략하면 대화형 Codex 마이그레이션은 체크박스 선택기를 표시하고 비대화형 마이그레이션은 계획된 모든 skills를 유지합니다.
</ParamField>
<ParamField path="--no-backup" type="boolean">
적용 전 백업을 건너뜁니다. 로컬 OpenClaw 상태가 있을 때는 `--force`가 필요합니다.
적용 전 백업을 건너뜁니다. 로컬 OpenClaw 상태가 있으면 `--force`가 필요합니다.
</ParamField>
<ParamField path="--force" type="boolean">
적용 작업이 백업 건너뛰기를 거부할 상황에서 `--no-backup`과 함께 필요합니다.
apply가 원래 백업 건너뛰기를 거부할 상황에서 `--no-backup`과 함께 필요합니다.
</ParamField>
<ParamField path="--json" type="boolean">
계획 또는 적용 결과를 JSON으로 출력합니다. `--json`이 있고 `--yes`가 없으면 적용 작업은 계획을 출력하고 상태를 변경하지 않습니다.
계획 또는 apply 결과를 JSON으로 출력합니다. `--json`을 사용하고 `--yes`가 없으면 apply는 계획을 출력하고 상태를 변경하지 않습니다.
</ParamField>
## 안전 모델
`openclaw migrate`는 미리보기 우선 방식입니다.
`openclaw migrate`는 미리보기 우선입니다.
<AccordionGroup>
<Accordion title="적용 전 미리보기">
제공자는 변경 전에 충돌, 건너뛴 항목, 민감한 항목을 포함한 항목별 계획을 반환합니다. JSON 계획, 적용 출력, 마이그레이션 보고서는 API 키, 토큰, 권한 부여 헤더, 쿠키, 비밀번호처럼 secret처럼 보이는 중첩 키를 마스킹합니다.
제공자는 변경 전에 항목별 계획을 반환하며, 여기에는 충돌, 건너뛴 항목, 민감한 항목이 포함됩니다. JSON 계획, apply 출력, 마이그레이션 보고서는 API 키, 토큰, 인증 헤더, 쿠키, 비밀번호처럼 secret으로 보이는 중첩 키를 마스킹합니다.
`openclaw migrate apply <provider>`는 `--yes`가 설정되지 않은 한 계획을 미리 보여 주고 상태 변경 전에 확인을 요청합니다. 비대화형 모드에서는 적용 작업에 `--yes`가 필요합니다.
`openclaw migrate apply <provider>`는 `--yes`가 설정되지 않은 한 상태를 변경하기 전에 계획을 미리 보고 프롬프트를 표시합니다. 비대화형 모드에서 apply에는 `--yes`가 필요합니다.
</Accordion>
<Accordion title="백업">
적용 작업은 마이그레이션을 적용하기 전에 OpenClaw 백업을 만들고 확인합니다. 아직 로컬 OpenClaw 상태가 없으면 백업 단계는 건너뛰고 마이그레이션을 계속할 수 있습니다. 상태가 있을 때 백업을 건너뛰려면 `--no-backup`과 `--force`를 모두 전달하세요.
apply는 마이그레이션을 적용하기 전에 OpenClaw 백업을 만들고 검증합니다. 아직 로컬 OpenClaw 상태가 없으면 백업 단계는 건너뛰고 마이그레이션을 계속할 수 있습니다. 상태가 있을 때 백업을 건너뛰려면 `--no-backup`과 `--force`를 모두 전달하세요.
</Accordion>
<Accordion title="충돌">
계획에 충돌이 있으면 적용 작업은 계속 진행을 거부합니다. 계획을 검토한 다음 기존 대상을 대체하려는 의도가 맞다면 `--overwrite`로 다시 실행하세요. 제공자는 여전히 마이그레이션 보고서 디렉터리에 덮어쓴 파일의 항목 수준 백업을 쓸 수 있습니다.
계획에 충돌이 있으면 apply는 계속 진행을 거부합니다. 계획을 검토한 다음 기존 대상을 교체하는 것이 의도된 경우 `--overwrite`로 다시 실행하세요. 제공자는 마이그레이션 보고서 디렉터리에 덮어쓴 파일의 항목 수준 백업을 계속 작성할 수 있습니다.
</Accordion>
<Accordion title="Secrets">
Secrets는 기본적으로 절대 가져오지 않습니다. 지원되는 자격 증명을 가져오려면 `--include-secrets`를 사용하세요.
@ -96,15 +103,47 @@ openclaw onboard --import-from hermes --import-source ~/.hermes
### Claude가 가져오는 항목
- 프로젝트 `CLAUDE.md` 및 `.claude/CLAUDE.md`를 OpenClaw 에이전트 작업 영역으로 가져옵니다.
- 사용자 `~/.claude/CLAUDE.md`를 작업 영역 `USER.md`에 추가합니다.
- 프로젝트 `.mcp.json`, Claude Code `~/.claude.json`, Claude Desktop `claude_desktop_config.json`의 MCP 서버 정의.
- `SKILL.md`를 포함하는 Claude skill 디렉터리.
- Claude 명령 Markdown 파일을 수동 호출 전용 OpenClaw skills로 변환합니다.
- 프로젝트 `CLAUDE.md` 및 `.claude/CLAUDE.md`를 OpenClaw 에이전트 작업공간으로 가져옵니다.
- 사용자 `~/.claude/CLAUDE.md`를 작업공간 `USER.md`에 추가합니다.
- 프로젝트 `.mcp.json`, Claude Code `~/.claude.json`, Claude Desktop `claude_desktop_config.json`의 MCP 서버 정의입니다.
- `SKILL.md`를 포함하는 Claude skill 디렉터리입니다.
- 수동 호출 전용 OpenClaw skills로 변환된 Claude 명령 Markdown 파일입니다.
### 아카이브 및 수동 검토 상태
Claude hooks, permissions, environment defaults, local memory, path-scoped rules, subagents, caches, plans, project history는 마이그레이션 보고서에 보존되거나 수동 검토 항목으로 보고됩니다. OpenClaw는 hooks를 실행하거나, 광범위한 allowlist를 복사하거나, OAuth/Desktop 자격 증명 상태를 자동으로 가져오지 않습니다.
Claude hooks, 권한, 환경 기본값, 로컬 메모리, 경로 범위 규칙, 하위 에이전트, 캐시, 계획, 프로젝트 기록은 마이그레이션 보고서에 보존되거나 수동 검토 항목으로 보고됩니다. OpenClaw는 hooks를 실행하거나, 광범위한 허용 목록을 복사하거나, OAuth/Desktop 자격 증명 상태를 자동으로 가져오지 않습니다.
## Codex 제공자
번들 Codex 제공자는 기본적으로 `~/.codex`에서 Codex CLI 상태를 감지하거나,
해당 환경 변수가 설정된 경우 `CODEX_HOME`에서 감지합니다. 특정 Codex 홈을
인벤터리하려면 `--from <path>`를 사용하세요.
OpenClaw Codex 하네스로 이동하면서 유용한 개인 Codex CLI 자산을
의도적으로 승격하려면 이 제공자를 사용하세요. 로컬 Codex 앱 서버
실행은 에이전트별 `CODEX_HOME` 및 `HOME` 디렉터리를 사용하므로 기본적으로
개인 Codex CLI 상태를 읽지 않습니다.
대화형 터미널에서 `openclaw migrate codex`를 실행하면 전체 계획을 미리 본
다음 최종 apply 확인 전에 skill 복사 항목용 체크박스 선택기가 열립니다.
모든 skills는 선택된 상태로 시작합니다. 이 에이전트에 복사하지 않으려는
skill은 선택 해제하세요. 스크립트 실행 또는 정확한 실행의 경우 skill마다
`--skill <name>`을 한 번씩 전달하세요. 예:
```bash
openclaw migrate codex --dry-run --skill gog-vault77-google-workspace
openclaw migrate apply codex --yes --skill gog-vault77-google-workspace
```
### Codex가 가져오는 항목
- Codex의 `.system` 캐시를 제외한 `$CODEX_HOME/skills` 아래의 Codex CLI skill 디렉터리입니다.
- 에이전트별 소유권을 원할 때 현재 OpenClaw 에이전트 작업공간으로 복사되는 `$HOME/.agents/skills` 아래의 개인 AgentSkills입니다.
### 수동 검토 Codex 상태
Codex 네이티브 plugins, `config.toml`, 네이티브 `hooks/hooks.json`는 자동으로
활성화되지 않습니다. Plugins는 MCP 서버, 앱, hooks 또는 기타 실행 가능한 동작을 노출할 수 있으므로 제공자는 이를 OpenClaw에 로드하는 대신 검토용으로 보고합니다. 구성 및 hook 파일은 수동 검토를 위해 마이그레이션 보고서로 복사됩니다.
## Hermes 제공자
@ -112,15 +151,15 @@ Claude hooks, permissions, environment defaults, local memory, path-scoped rules
### Hermes가 가져오는 항목
- `config.yaml`의 기본 모델 구성.
- `providers` 및 `custom_providers`의 구성된 모델 제공자와 사용자 지정 OpenAI 호환 엔드포인트.
- `mcp_servers` 또는 `mcp.servers`의 MCP 서버 정의.
- `SOUL.md` 및 `AGENTS.md`를 OpenClaw 에이전트 작업 영역으로 가져옵니다.
- `memories/MEMORY.md` 및 `memories/USER.md`를 작업 영역 메모리 파일에 추가합니다.
- OpenClaw 파일 메모리용 메모리 구성 기본값과 Honcho 같은 외부 메모리 제공자를 위한 아카이브 또는 수동 검토 항목.
- `skills/<name>/` 아래에 `SKILL.md` 파일을 포함하는 Skills.
- `skills.config`의 Skills별 구성 값.
- `.env`의 지원되는 API 키. 단, `--include-secrets`가 있을 때만 해당합니다.
- `config.yaml`의 기본 모델 구성입니다.
- `providers` 및 `custom_providers`의 구성된 모델 제공자와 사용자 지정 OpenAI 호환 엔드포인트입니다.
- `mcp_servers` 또는 `mcp.servers`의 MCP 서버 정의입니다.
- `SOUL.md` 및 `AGENTS.md`를 OpenClaw 에이전트 작업공간으로 가져옵니다.
- `memories/MEMORY.md` 및 `memories/USER.md`를 작업공간 메모리 파일에 추가합니다.
- OpenClaw 파일 메모리의 메모리 구성 기본값과 Honcho 같은 외부 메모리 제공자의 아카이브 또는 수동 검토 항목입니다.
- `skills/<name>/` 아래에 `SKILL.md` 파일을 포함하는 Skills입니다.
- `skills.config`의 skill별 구성 값입니다.
- `.env`의 지원되는 API 키이며, `--include-secrets`를 사용한 경우에만 가져옵니다.
### 지원되는 `.env` 키
@ -128,7 +167,7 @@ Claude hooks, permissions, environment defaults, local memory, path-scoped rules
### 아카이브 전용 상태
OpenClaw가 안전하게 해석할 수 없는 Hermes 상태는 수동 검토를 위해 마이그레이션 보고서로 복사되지만, 실시간 OpenClaw 구성 또는 자격 증명으로 로드되지는 않습니다. 이렇게 하면 불투명하거나 안전하지 않은 상태를 OpenClaw가 자동으로 실행하거나 신뢰할 수 있는 것처럼 가장하지 않고도 보존할 수 있습니다.
OpenClaw가 안전하게 해석할 수 없는 Hermes 상태는 수동 검토를 위해 마이그레이션 보고서로 복사되지만, 라이브 OpenClaw 구성 또는 자격 증명으로 로드되지는 않습니다. 이렇게 하면 OpenClaw가 이를 자동으로 실행하거나 신뢰할 수 있다고 가장하지 않으면서 불투명하거나 안전하지 않은 상태를 보존합니다.
- `plugins/`
- `sessions/`
@ -146,7 +185,7 @@ openclaw doctor
## Plugin 계약
마이그레이션 원본은 Plugin입니다. Plugin은 `openclaw.plugin.json`에서 제공자 ID를 선언합니다.
마이그레이션 소스는 plugins입니다. plugin은 `openclaw.plugin.json`에서 제공자 id를 선언합니다.
```json
{
@ -156,22 +195,22 @@ openclaw doctor
}
```
런타임에 Plugin은 `api.registerMigrationProvider(...)`를 호출합니다. 제공자는 `detect`, `plan`, `apply`를 구현합니다. 코어는 CLI 오케스트레이션, 백업 정책, 프롬프트, JSON 출력, 충돌 사전 점검을 담당합니다. 코어는 검토된 계획을 `apply(ctx, plan)`에 전달하며, 제공자는 호환성을 위해 해당 인수가 없을 때만 계획을 다시 만들 수 있습니다.
런타임에서 plugin은 `api.registerMigrationProvider(...)`를 호출합니다. 제공자는 `detect`, `plan`, `apply`를 구현합니다. Core는 CLI 오케스트레이션, 백업 정책, 프롬프트, JSON 출력, 충돌 사전 검사를 소유합니다. Core는 검토된 계획을 `apply(ctx, plan)`에 전달하며, 제공자는 호환성을 위해 해당 인수가 없을 때만 계획을 다시 빌드할 수 있습니다.
제공자 Plugin은 항목 생성 및 요약 개수에 `openclaw/plugin-sdk/migration`을 사용할 수 있으며, 충돌 인식 파일 복사, 아카이브 전용 보고서 복사, 캐시된 config-runtime 래퍼, 마이그레이션 보고서에는 `openclaw/plugin-sdk/migration-runtime`을 사용할 수 있습니다.
제공자 plugins는 항목 구성 및 요약 카운트에 `openclaw/plugin-sdk/migration`을 사용할 수 있고, 충돌 인식 파일 복사, 아카이브 전용 보고서 복사, 캐시된 config-runtime 래퍼, 마이그레이션 보고서에는 `openclaw/plugin-sdk/migration-runtime`을 사용할 수 있습니다.
## 온보딩 통합
제공자가 알려진 원본을 감지하면 온보딩에서 마이그레이션을 제공할 수 있습니다. `openclaw onboard --flow import`와 `openclaw setup --wizard --import-from hermes`는 모두 동일한 Plugin 마이그레이션 제공자를 사용하며, 적용 전에 여전히 미리보기를 표시합니다.
온보딩은 제공자가 알려진 소스를 감지할 때 마이그레이션을 제공할 수 있습니다. `openclaw onboard --flow import`와 `openclaw setup --wizard --import-from hermes`는 모두 동일한 plugin 마이그레이션 제공자를 사용하며, 적용 전에 여전히 미리보기를 표시합니다.
<Note>
온보딩 가져오기는 새 OpenClaw 설정이 필요합니다. 이미 로컬 상태가 있다면 먼저 구성, 자격 증명, 세션, 작업 영역을 재설정하세요. 기존 설정에 대한 백업 후 덮어쓰기 또는 병합 가져오기는 기능 게이트로 제한됩니다.
온보딩 가져오기는 새로운 OpenClaw 설정이 필요합니다. 이미 로컬 상태가 있다면 먼저 구성, 자격 증명, 세션, 작업공간을 재설정하세요. 백업 후 덮어쓰기 또는 병합 가져오기는 기존 설정에 대해 기능 게이트가 적용됩니다.
</Note>
## 관련 항목
- [Hermes에서 마이그레이션](/ko/install/migrating-hermes): 사용자 대상 안내.
- [Claude에서 마이그레이션](/ko/install/migrating-claude): 사용자 대상 안내.
- [Hermes에서 마이그레이션](/ko/install/migrating-hermes): 사용자 대상 안내입니다.
- [Claude에서 마이그레이션](/ko/install/migrating-claude): 사용자 대상 안내입니다.
- [마이그레이션](/ko/install/migrating): OpenClaw를 새 머신으로 이동합니다.
- [Doctor](/ko/gateway/doctor): 마이그레이션 적용 후 상태 점검.
- [Plugins](/ko/tools/plugin): Plugin 설치 및 등록.
- [Doctor](/ko/gateway/doctor): 마이그레이션 적용 후 상태 검사입니다.
- [Plugins](/ko/tools/plugin): plugin 설치 및 등록입니다.

135
docs/ko/concepts/agent-workspace.md
View File

@ -1,34 +1,34 @@
---
read_when:
- 에이전트 워크스페이스 또는 해당 파일 레이아웃을 설명해야 합니다
- 에이전트 워크스페이스를 백업하거나 마이그레이션하려고 합니다
- 에이전트 작업 공간을 백업하거나 마이그레이션하려는 경우
sidebarTitle: Agent workspace
summary: '에이전트 워크스페이스: 위치, 레이아웃 및 백업 전략'
title: 에이전트 워크스페이스
summary: '에이전트 작업 공간: 위치, 레이아웃 및 백업 전략'
title: 에이전트 작업 공간
x-i18n:
generated_at: "2026-04-26T11:26:47Z"
model: gpt-5.4
generated_at: "2026-04-30T20:05:23Z"
model: gpt-5.5
provider: openai
source_hash: 35d59d1f0dec05db30f9166a43bfa519d7299b08d093bbeb905d8f83e5cd022a
source_hash: b1ccf74cbec3ff20f4c1c1ce52f099a7ca3365b2536b0aad6ff1d3a5fafcca0a
source_path: concepts/agent-workspace.md
workflow: 15
workflow: 16
---
워크스페이스는 에이전트의 집입니다. 파일 도구와 워크스페이스 컨텍스트에 사용되는 유일한 작업 디렉터리입니다. 비공개로 유지하고 메모리처럼 다루세요.
이는 config, 자격 증명, 세션을 저장하는 `~/.openclaw/`와는 별개입니다.
이는 config, credentials, sessions를 저장하는 `~/.openclaw/`와 별개입니다.
<Warning>
워크스페이스는 하드 샌드박스가 아니라 **기본 cwd**입니다. 도구는 상대 경로를 워크스페이스 기준으로 확인하지만, 샌드박싱이 활성화되지 않으면 절대 경로로 호스트의 다른 위치에도 접근할 수 있습니다. 격리가 필요하다면 [`agents.defaults.sandbox`](/ko/gateway/sandboxing)(및/또는 에이전트별 샌드박스 config)를 사용하세요.
워크스페이스는 엄격한 샌드박스가 아니라 **기본 cwd**입니다. 도구는 상대 경로를 워크스페이스 기준으로 해석하지만, 샌드박싱이 활성화되어 있지 않으면 절대 경로는 여전히 호스트의 다른 위치에 접근할 수 있습니다. 격리가 필요하면 [`agents.defaults.sandbox`](/ko/gateway/sandboxing) (및/또는 에이전트별 샌드박스 config)를 사용하세요.
샌드박싱이 활성화되어 있고 `workspaceAccess`가 `"rw"`가 아니면, 도구는 호스트 워크스페이스가 아니라 `~/.openclaw/sandboxes` 아래의 샌드박스 워크스페이스 내부에서 동작합니다.
샌드박싱이 활성화되어 있고 `workspaceAccess`가 `"rw"`가 아니면, 도구는 호스트 워크스페이스가 아니라 `~/.openclaw/sandboxes` 아래의 샌드박스 워크스페이스 안에서 작동합니다.
</Warning>
## 기본 위치
- 기본값: `~/.openclaw/workspace`
- `OPENCLAW_PROFILE`이 설정되어 있고 `"default"`가 아니면 기본값은 `~/.openclaw/workspace-<profile>`가 됩니다.
- `~/.openclaw/openclaw.json`에서 재정의:
- `OPENCLAW_PROFILE`이 설정되어 있고 `"default"`가 아니면, 기본값은 `~/.openclaw/workspace-<profile>`이 됩니다.
- `~/.openclaw/openclaw.json`에서 재정의합니다.
```json5
{
@ -40,13 +40,13 @@ x-i18n:
}
```
`openclaw onboard`, `openclaw configure`, 또는 `openclaw setup`은 워크스페이스가 없으면 이를 생성하고 bootstrap 파일을 시드합니다.
`openclaw onboard`, `openclaw configure`, 또는 `openclaw setup`은 워크스페이스를 만들고, 누락된 경우 bootstrap 파일을 시드합니다.
<Note>
샌드박스 시드 복사는 워크스페이스 내부의 일반 파일만 허용합니다. 원본 워크스페이스 밖으로 확인되는 symlink/hardlink 별칭은 무시됩니다.
샌드박스 시드 복사는 워크스페이스 안의 일반 파일만 허용합니다. 소스 워크스페이스 밖으로 해석되는 symlink/hardlink 별칭은 무시됩니다.
</Note>
이미 워크스페이스 파일을 직접 관리하고 있다면 bootstrap 파일 생성을 비활성화할 수 있습니다:
워크스페이스 파일을 이미 직접 관리하고 있다면 bootstrap 파일 생성을 비활성화할 수 있습니다.
```json5
{ agents: { defaults: { skipBootstrap: true } } }
@ -54,82 +54,83 @@ x-i18n:
## 추가 워크스페이스 폴더
오래된 설치에서는 `~/openclaw`가 생성되었을 수 있습니다. 여러 워크스페이스 디렉터리를 동시에 두면 한 번에 하나의 워크스페이스만 활성 상태이므로 인증이나 상태 드리프트가 혼란스럽게 발생할 수 있습니다.
이전 설치에서는 `~/openclaw`를 만들었을 수 있습니다. 한 번에 하나의 워크스페이스만 활성 상태이므로 여러 워크스페이스 디렉터리를 유지하면 인증 또는 상태 드리프트가 혼란스럽게 발생할 수 있습니다.
<Note>
**권장 사항:** 활성 워크스페이스는 하나만 유지하세요. 추가 폴더를 더 이상 사용하지 않는다면 보관하거나 휴지통으로 이동하세요(예: `trash ~/openclaw`). 의도적으로 여러 워크스페이스를 유지한다면 `agents.defaults.workspace`가 활성 워크스페이스를 가리키는지 확인하세요.
**권장 사항:** 활성 워크스페이스를 하나만 유지하세요. 추가 폴더를 더 이상 사용하지 않는다면 아카이브하거나 휴지통으로 이동하세요(예: `trash ~/openclaw`). 여러 워크스페이스를 의도적으로 유지한다면 `agents.defaults.workspace`가 활성 워크스페이스를 가리키는지 확인하세요.
`openclaw doctor`는 추가 워크스페이스 디렉터리를 감지하면 경고를 표시합니다.
`openclaw doctor`는 추가 워크스페이스 디렉터리를 감지하면 경고합니다.
</Note>
## 워크스페이스 파일 맵
다음은 OpenClaw가 워크스페이스 내부에서 기대하는 표준 파일입니다:
다음은 OpenClaw가 워크스페이스 안에 있을 것으로 기대하는 표준 파일입니다.
<AccordionGroup>
<Accordion title="AGENTS.md — 운영 지침">
에이전트를 위한 운영 지침과 메모리 사용 방식입니다. 모든 세션 시작 시 로드됩니다. 규칙, 우선순위, "어떻게 행동할지"에 관한 세부 사항을 두기 좋은 위치입니다.
에이전트를 위한 운영 지침과 메모리를 사용해야 하는 방식입니다. 모든 세션 시작 시 로드됩니다. 규칙, 우선순위, "어떻게 행동할지"에 대한 세부 정보를 두기 좋은 위치입니다.
</Accordion>
<Accordion title="SOUL.md — 페르소나와 톤">
페르소나, 톤, 경계입니다. 모든 세션에서 로드됩니다. 안내서: [SOUL.md 성격 가이드](/ko/concepts/soul).
페르소나, 톤, 경계입니다. 모든 세션에서 로드됩니다. 가이드: [SOUL.md 성격 가이드](/ko/concepts/soul).
</Accordion>
<Accordion title="USER.md — 사용자가 누구인지">
사용자가 누구인지와 어떻게 불러야 하는지입니다. 모든 세션에서 로드됩니다.
사용자가 누구이며 어떻게 호칭할지입니다. 모든 세션에서 로드됩니다.
</Accordion>
<Accordion title="IDENTITY.md — 이름, 분위기, 이모지">
에이전트의 이름, 분위기, 이모지입니다. bootstrap ritual 동안 생성/업데이트됩니다.
에이전트의 이름, 분위기, 이모지입니다. bootstrap 의식 중에 생성/업데이트됩니다.
</Accordion>
<Accordion title="TOOLS.md — 로컬 도구 관례">
로컬 도구와 관례에 대한 메모입니다. 도구 가용성을 제어하지는 않으며 안내용일 뿐입니다.
로컬 도구와 관례에 대한 메모입니다. 도구 사용 가능 여부를 제어하지 않으며, 안내용일 뿐입니다.
</Accordion>
<Accordion title="HEARTBEAT.md — Heartbeat 체크리스트">
Heartbeat 실행을 위한 선택적 작은 체크리스트입니다. 토큰 소모를 피하기 위해 짧게 유지하세요.
Heartbeat 실행을 위한 선택적 짧은 체크리스트입니다. 토큰 소모를 피하려면 짧게 유지하세요.
</Accordion>
<Accordion title="BOOT.md — 시작 체크리스트">
Gateway 재시작 시 자동으로 실행되는 선택적 시작 체크리스트입니다([internal hooks](/ko/automation/hooks)가 활성화된 경우). 짧게 유지하고, 아웃바운드 전송에는 message 도구를 사용하세요.
Gateway 재시작 시([internal hooks](/ko/automation/hooks)가 활성화된 경우) 자동으로 실행되는 선택적 시작 체크리스트입니다. 짧게 유지하세요. 발신 전송에는 message 도구를 사용하세요.
</Accordion>
<Accordion title="BOOTSTRAP.md — 첫 실행 ritual">
일회성 첫 실행 ritual입니다. 완전히 새로운 워크스페이스에만 생성됩니다. ritual이 완료되면 삭제하세요.
<Accordion title="BOOTSTRAP.md — 첫 실행 의식">
일회성 첫 실행 의식입니다. 완전히 새 워크스페이스에 대해서만 생성됩니다. 의식이 완료되면 삭제하세요.
</Accordion>
<Accordion title="memory/YYYY-MM-DD.md — 일일 메모리 로그">
일일 메모리 로그(하루에 파일 하나). 세션 시작 시 오늘 + 어제를 읽는 것을 권장합니다.
일일 메모리 로그입니다(하루에 파일 하나). 세션 시작 시 오늘 + 어제를 읽는 것을 권장합니다.
</Accordion>
<Accordion title="MEMORY.md — 큐레이션된 장기 메모리(선택 사항)">
큐레이션된 장기 메모리입니다. main 비공개 세션에서만 로드하세요(공유/그룹 컨텍스트 제외). 워크플로와 자동 메모리 flush는 [Memory](/ko/concepts/memory)를 참조하세요.
<Accordion title="MEMORY.md — 선별된 장기 메모리(선택 사항)">
선별된 장기 메모리입니다. 기본 비공개 세션에서만 로드하세요(공유/그룹 컨텍스트에서는 로드하지 않음). 워크플로와 자동 메모리 flush는 [메모리](/ko/concepts/memory)를 참조하세요.
</Accordion>
<Accordion title="skills/ — 워크스페이스 Skills(선택 사항)">
워크스페이스 전용 Skills입니다. 해당 워크스페이스에서 가장 높은 우선순위를 갖는 skill 위치입니다. 이름이 충돌하면 프로젝트 agent skills, 개인 agent skills, 관리형 skills, 번들 skills, `skills.load.extraDirs`를 재정의합니다.
워크스페이스별 Skills입니다. 해당 워크스페이스에서 가장 높은 우선순위의 skill 위치입니다. 이름이 충돌하면 프로젝트 에이전트 skills, 개인 에이전트 skills, 관리형 skills, 번들 skills, `skills.load.extraDirs`를 재정의합니다.
</Accordion>
<Accordion title="canvas/ — Canvas UI 파일(선택 사항)">
node 디스플레이용 Canvas UI 파일입니다(예: `canvas/index.html`).
노드 표시를 위한 Canvas UI 파일입니다(예: `canvas/index.html`).
</Accordion>
</AccordionGroup>
<Note>
bootstrap 파일이 하나라도 누락되면 OpenClaw는 세션에 "누락된 파일" 마커를 삽입하고 계속 진행합니다. 큰 bootstrap 파일은 삽입 시 잘립니다. 한도는 `agents.defaults.bootstrapMaxChars`(기본값: 12000)와 `agents.defaults.bootstrapTotalMaxChars`(기본값: 60000)로 조정하세요. `openclaw setup`은 기존 파일을 덮어쓰지 않고 누락된 기본 파일을 다시 만들 수 있습니다.
bootstrap 파일이 누락되면 OpenClaw는 "missing file" 마커를 세션에 주입하고 계속 진행합니다. 큰 bootstrap 파일은 주입될 때 잘립니다. 제한은 `agents.defaults.bootstrapMaxChars`(기본값: 12000)와 `agents.defaults.bootstrapTotalMaxChars`(기본값: 60000)로 조정하세요. `openclaw setup`은 기존 파일을 덮어쓰지 않고 누락된 기본값을 다시 만들 수 있습니다.
</Note>
## 워크스페이스에 없는 것
다음 항목은 `~/.openclaw/` 아래에 있으며 워크스페이스 repo에 커밋하면 안 됩니다:
다음은 `~/.openclaw/` 아래에 있으며 워크스페이스 repo에 커밋하면 안 됩니다.
- `~/.openclaw/openclaw.json` (config)
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (model auth profiles: OAuth + API keys)
- `~/.openclaw/credentials/` (채널/provider 상태와 레거시 OAuth 가져오기 데이터)
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (모델 인증 프로필: OAuth + API 키)
- `~/.openclaw/agents/<agentId>/agent/codex-home/` (에이전트별 Codex 런타임 계정, config, skills, plugins, 네이티브 스레드 상태)
- `~/.openclaw/credentials/` (채널/제공자 상태 및 레거시 OAuth 가져오기 데이터)
- `~/.openclaw/agents/<agentId>/sessions/` (세션 transcript + metadata)
- `~/.openclaw/skills/` (관리형 Skills)
- `~/.openclaw/skills/` (관리형 skills)
세션이나 config를 마이그레이션해야 한다면 별도로 복사하고 버전 관리에는 포함하지 마세요.
세션이나 config를 마이그레이션해야 한다면 별도로 복사하고 버전 관리에서 제외하세요.
## Git 백업(권장, 비공개)
워크스페이스를 비공개 메모리처럼 다루세요. 백업과 복구가 가능하도록 **비공개** git repo에 넣으세요.
워크스페이스를 비공개 메모리로 다루세요. 백업 가능하고 복구할 수 있도록 **비공개** git repo에 넣으세요.
이 단계는 Gateway가 실행되는 머신에서 수행하세요(워크스페이스가 거기에 있습니다).
이 단계는 Gateway가 실행되는 머신에서 실행하세요(워크스페이스가 있는 위치입니다).
<Steps>
<Step title="repo 초기화">
git이 설치되어 있으면 완전히 새로운 워크스페이스는 자동으로 초기화됩니다. 이 워크스페이스가 아직 repo가 아니라면 다음을 실행하세요:
git이 설치되어 있으면 완전히 새로운 워크스페이스는 자동으로 초기화됩니다. 이 워크스페이스가 아직 repo가 아니라면 다음을 실행하세요.
```bash
cd ~/.openclaw/workspace
@ -139,13 +140,13 @@ bootstrap 파일이 하나라도 누락되면 OpenClaw는 세션에 "누락된
```
</Step>
<Step title="비공개 원격 추가">
<Step title="비공개 remote 추가">
<Tabs>
<Tab title="GitHub 웹 UI">
1. GitHub에서 새 **비공개** repository를 생성합니다.
2. README로 초기화하지 마세요(병합 충돌 방지).
3. HTTPS 원격 URL을 복사합니다.
4. 원격을 추가하고 푸시합니다:
1. GitHub에서 새 **비공개** 저장소를 만듭니다.
2. README로 초기화하지 마세요(merge conflict 방지).
3. HTTPS remote URL을 복사합니다.
4. remote를 추가하고 push합니다.
```bash
git branch -M main
@ -160,10 +161,10 @@ bootstrap 파일이 하나라도 누락되면 OpenClaw는 세션에 "누락된
```
</Tab>
<Tab title="GitLab 웹 UI">
1. GitLab에서 새 **비공개** repository를 생성합니다.
2. README로 초기화하지 마세요(병합 충돌 방지).
3. HTTPS 원격 URL을 복사합니다.
4. 원격을 추가하고 푸시합니다:
1. GitLab에서 새 **비공개** 저장소를 만듭니다.
2. README로 초기화하지 마세요(merge conflict 방지).
3. HTTPS remote URL을 복사합니다.
4. remote를 추가하고 push합니다.
```bash
git branch -M main
@ -184,19 +185,19 @@ bootstrap 파일이 하나라도 누락되면 OpenClaw는 세션에 "누락된
</Step>
</Steps>
## 시크릿은 커밋하지 마세요
## secret을 커밋하지 마세요
<Warning>
비공개 repo에서도 워크스페이스에 시크릿을 저장하지 않는 것이 좋습니다:
비공개 repo에서도 워크스페이스에 secret을 저장하지 마세요.
- API 키, OAuth 토큰, 비밀번호 또는 비공개 자격 증명
- `~/.openclaw/` 아래의 모든 것
- 채팅 원본 덤프 또는 민감한 첨부 파일
- API 키, OAuth 토큰, 비밀번호 또는 비공개 credentials.
- `~/.openclaw/` 아래의 모든 것.
- 채팅 또는 민감한 첨부 파일의 원시 dump.
민감한 참조를 반드시 저장해야 한다면 placeholder를 사용하고 실제 시크릿은 다른 곳(비밀번호 관리자, 환경 변수 또는 `~/.openclaw/`)에 보관하세요.
민감한 참조를 저장해야 한다면 placeholder를 사용하고 실제 secret은 다른 곳(비밀번호 관리자, 환경 변수 또는 `~/.openclaw/`)에 보관하세요.
</Warning>
권장 `.gitignore` 시작 예시:
권장 `.gitignore` 시작점:
```gitignore
.DS_Store
@ -206,31 +207,31 @@ bootstrap 파일이 하나라도 누락되면 OpenClaw는 세션에 "누락된
**/secrets*
```
## 새 머신으로 워크스페이스 이동하기
## 워크스페이스를 새 머신으로 이동
<Steps>
<Step title="repo 클론">
원하는 경로(기본값 `~/.openclaw/workspace`)에 repo를 클론합니다.
repo를 원하는 경로에 클론합니다(기본값 `~/.openclaw/workspace`).
</Step>
<Step title="config 업데이트">
`~/.openclaw/openclaw.json`에서 `agents.defaults.workspace`를 해당 경로로 설정합니다.
</Step>
<Step title="누락된 파일 시드">
<Step title="누락 파일 시드">
누락된 파일을 시드하려면 `openclaw setup --workspace <path>`를 실행합니다.
</Step>
<Step title="세션 복사(선택 사항)">
세션이 필요하면 이전 머신의 `~/.openclaw/agents/<agentId>/sessions/`를 별도로 복사합니다.
세션이 필요하면 이전 머신에서 `~/.openclaw/agents/<agentId>/sessions/`를 별도로 복사합니다.
</Step>
</Steps>
## 고급 참고 사항
- 다중 에이전트 라우팅은 에이전트별로 다른 워크스페이스를 사용할 수 있습니다. 라우팅 구성은 [채널 라우팅](/ko/channels/channel-routing)을 참조하세요.
- `agents.defaults.sandbox`가 활성화되어 있으면 non-main 세션은 `agents.defaults.sandbox.workspaceRoot` 아래의 세션별 샌드박스 워크스페이스를 사용할 수 있습니다.
- 다중 에이전트 라우팅은 에이전트별로 서로 다른 워크스페이스를 사용할 수 있습니다. 라우팅 config는 [채널 라우팅](/ko/channels/channel-routing)을 참조하세요.
- `agents.defaults.sandbox`가 활성화되어 있으면, 기본 세션이 아닌 세션은 `agents.defaults.sandbox.workspaceRoot` 아래의 세션별 샌드박스 워크스페이스를 사용할 수 있습니다.
## 관련
## 관련 항목
- [Heartbeat](/ko/gateway/heartbeat) — HEARTBEAT.md 워크스페이스 파일
- [샌드박싱](/ko/gateway/sandboxing) — 샌드박스 환경의 워크스페이스 접근
- [샌드박싱](/ko/gateway/sandboxing) — 샌드박스 환경에서의 워크스페이스 접근
- [세션](/ko/concepts/session) — 세션 저장 경로
- [상시 지침](/ko/automation/standing-orders) — 워크스페이스 파일의 영구 지침
- [상시 지시](/ko/automation/standing-orders) — 워크스페이스 파일의 지속 지침

1178
docs/ko/gateway/security/index.md
View File

File diff suppressed because it is too large Load Diff

562
docs/ko/plugins/codex-harness.md
View File

@ -1,135 +1,203 @@
---
read_when:
- 번들로 제공되는 Codex app-server 하네스를 사용하려는 경우
- Codex 하니스 구성 예제가 필요합니다
- 번들로 제공되는 Codex 앱 서버 하네스를 사용하려는 경우
- Codex 하네스 구성 예제가 필요합니다
- Codex 전용 배포가 PI로 폴백하는 대신 실패하도록 하려는 경우
summary: 번들된 Codex 앱 서버 하네스를 통해 OpenClaw 임베디드 에이전트 턴을 실행합니다
summary: 번들된 Codex app-server 하네스를 통해 OpenClaw 임베디드 에이전트 턴 실행
title: Codex 하네스
x-i18n:
generated_at: "2026-04-30T06:41:17Z"
generated_at: "2026-04-30T20:05:39Z"
model: gpt-5.5
provider: openai
source_hash: 93abb72e9590aad265e5b6b8691dd16314178c4d255679b4e53da33b792a6e6b
source_hash: 335ec60cbdb76579db833eccb5151ffc5bcd28b370ca2e99587abdb578eeee4f
source_path: plugins/codex-harness.md
workflow: 16
---
번들 `codex` Plugin은 OpenClaw가 내장 PI 하네스 대신 Codex app-server를 통해 임베디드 에이전트 턴을 실행할 수 있게 합니다.
번들로 제공되는 `codex` Plugin을 사용하면 OpenClaw가 내장 PI 하네스 대신
Codex 앱 서버를 통해 임베디드 에이전트 턴을 실행할 수 있습니다.
저수준 에이전트 세션을 Codex가 소유하게 하려는 경우에 사용하세요. 여기에는 모델 발견, 네이티브 스레드 재개, 네이티브 Compaction, app-server 실행이 포함됩니다. OpenClaw는 계속 채팅 채널, 세션 파일, 모델 선택, 도구, 승인, 미디어 전달, 보이는 대화 기록 미러를 소유합니다.
저수준 에이전트 세션을 Codex가 소유하게 하고 싶을 때 이것을 사용하세요. 모델
검색, 네이티브 스레드 재개, 네이티브 Compaction, 앱 서버 실행이 여기에 포함됩니다.
OpenClaw는 여전히 채팅 채널, 세션 파일, 모델 선택, 도구, 승인, 미디어 전달,
표시되는 트랜스크립트 미러를 소유합니다.
방향을 잡고 있다면 [에이전트 런타임](/ko/concepts/agent-runtimes)부터 시작하세요. 짧게 말하면 `openai/gpt-5.5`는 모델 참조이고, `codex`는 런타임이며, Telegram, Discord, Slack 또는 다른 채널은 계속 통신 표면으로 남습니다.
방향을 잡으려는 중이라면
[에이전트 런타임](/ko/concepts/agent-runtimes)부터 시작하세요. 짧게 말하면:
`openai/gpt-5.5`는 모델 참조이고, `codex`는 런타임이며, Telegram,
Discord, Slack 또는 다른 채널은 커뮤니케이션 표면으로 유지됩니다.
## 이 Plugin이 변경하는 것
## 이 Plugin이 바꾸는 것
번들 `codex` Plugin은 여러 개별 기능을 제공합니다.
| 기능 | 사용 방법 | 수행하는 작업 |
| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- |
| 네이티브 임베디드 런타임 | `agentRuntime.id: "codex"` | Codex app-server를 통해 OpenClaw 임베디드 에이전트 턴을 실행합니다. |
| 네이티브 채팅 제어 명령 | `/codex bind`, `/codex resume`, `/codex steer`, ... | 메시징 대화에서 Codex app-server 스레드를 바인딩하고 제어합니다. |
| Codex app-server 제공자/카탈로그 | `codex` 내부 요소, 하네스를 통해 노출됨 | 런타임이 app-server 모델을 발견하고 검증할 수 있게 합니다. |
| Codex 미디어 이해 경로 | `codex/*` 이미지 모델 호환성 경로 | 지원되는 이미지 이해 모델에 대해 제한된 Codex app-server 턴을 실행합니다. |
| 네이티브 훅 릴레이 | Codex 네이티브 이벤트 주변의 Plugin 훅 | OpenClaw가 지원되는 Codex 네이티브 도구/종료 이벤트를 관찰/차단할 수 있게 합니다. |
| 기능 | 사용 방법 | 수행하는 일 |
| --------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------- |
| 네이티브 임베디드 런타임 | `agentRuntime.id: "codex"` | OpenClaw 임베디드 에이전트 턴을 Codex 앱 서버를 통해 실행합니다. |
| 네이티브 채팅 제어 명령 | `/codex bind`, `/codex resume`, `/codex steer`, ... | 메시징 대화에서 Codex 앱 서버 스레드를 바인딩하고 제어합니다. |
| Codex 앱 서버 제공자/카탈로그 | `codex` 내부 기능, 하네스를 통해 노출됨 | 런타임이 앱 서버 모델을 검색하고 검증할 수 있게 합니다. |
| Codex 미디어 이해 경로 | `codex/*` 이미지 모델 호환성 경로 | 지원되는 이미지 이해 모델에 대해 제한된 Codex 앱 서버 턴을 실행합니다. |
| 네이티브 훅 릴레이 | Codex 네이티브 이벤트 주변의 Plugin 훅 | OpenClaw가 지원되는 Codex 네이티브 도구/종료 이벤트를 관찰하거나 차단할 수 있게 합니다. |
Plugin을 활성화하면 이러한 기능을 사용할 수 있습니다. 다음을 수행하지는 **않습니다**.
Plugin을 활성화하면 이러한 기능을 사용할 수 있습니다. 이것은 다음을 **하지 않습니다**:
- 모든 OpenAI 모델에 대해 Codex 사용 시작
- 모든 OpenAI 모델에 Codex를 사용하기 시작
- `openai-codex/*` 모델 참조를 네이티브 런타임으로 변환
- ACP/acpx를 기본 Codex 경로로 만들기
- 이미 PI 런타임을 기록한 기존 세션을 핫스위치
- OpenClaw 채널 전달, 세션 파일, 인증 프로필 저장소 또는 메시지 라우팅 대체
- ACP/acpx를 기본 Codex 경로로 설정
- 이미 PI 런타임을 기록한 기존 세션을 핫 스위치
- OpenClaw 채널 전달, 세션 파일, 인증 프로필 저장소 또는
메시지 라우팅 대체
동일한 Plugin은 네이티브 `/codex` 채팅 제어 명령 표면도 소유합니다. Plugin이 활성화되어 있고 사용자가 채팅에서 Codex 스레드를 바인딩, 재개, 조향, 중지 또는 검사하라고 요청하는 경우 에이전트는 ACP보다 `/codex ...`를 선호해야 합니다. ACP는 사용자가 ACP/acpx를 요청하거나 ACP Codex 어댑터를 테스트하는 경우의 명시적 폴백으로 남습니다.
동일한 Plugin은 네이티브 `/codex` 채팅 제어 명령 표면도 소유합니다. Plugin이
활성화되어 있고 사용자가 채팅에서 Codex 스레드를 바인딩, 재개, 조정, 중지 또는
검사해 달라고 요청하면 에이전트는 ACP보다 `/codex ...`를 우선해야 합니다. 사용자가
ACP/acpx를 요청하거나 ACP Codex 어댑터를 테스트 중일 때는 ACP가 명시적 폴백으로
남습니다.
네이티브 Codex 턴은 OpenClaw Plugin 훅을 공개 호환성 계층으로 유지합니다. 이것들은 프로세스 내부 OpenClaw 훅이며, Codex `hooks.json` 명령 훅이 아닙니다.
네이티브 Codex 턴은 OpenClaw Plugin 훅을 공개 호환성 계층으로 유지합니다.
이들은 프로세스 내부 OpenClaw 훅이며 Codex `hooks.json` 명령 훅이 아닙니다.
- `before_prompt_build`
- `before_compaction`, `after_compaction`
- `llm_input`, `llm_output`
- `before_tool_call`, `after_tool_call`
- 미러링된 대화 기록 레코드를 위한 `before_message_write`
- Codex `Stop` 릴레이를 통한 `before_agent_finalize`
- `before_message_write` for mirrored transcript records
- `before_agent_finalize` through Codex `Stop` relay
- `agent_end`
Plugin은 런타임 중립 도구 결과 미들웨어도 등록하여, OpenClaw가 도구를 실행한 뒤 결과가 Codex로 반환되기 전에 OpenClaw 동적 도구 결과를 다시 작성할 수 있습니다. 이는 OpenClaw가 소유한 대화 기록 도구 결과 쓰기를 변환하는 공개 `tool_result_persist` Plugin 훅과 별개입니다.
Plugin은 OpenClaw가 도구를 실행한 뒤 결과가 Codex로 반환되기 전에 OpenClaw
동적 도구 결과를 다시 작성하기 위한 런타임 중립 도구 결과 미들웨어도 등록할 수
있습니다. 이것은 OpenClaw가 소유한 트랜스크립트 도구 결과 쓰기를 변환하는 공개
`tool_result_persist` Plugin 훅과 별개입니다.
Plugin 훅 의미 자체는 [Plugin 훅](/ko/plugins/hooks) 및 [Plugin 가드 동작](/ko/tools/plugin)을 참조하세요.
Plugin 훅 의미 자체는 [Plugin 훅](/ko/plugins/hooks) 및
[Plugin 가드 동작](/ko/tools/plugin)을 참조하세요.
하네스는 기본적으로 꺼져 있습니다. 새 구성은 OpenAI 모델 참조를 `openai/gpt-*`로 정식 유지하고, 네이티브 app-server 실행을 원할 때 `agentRuntime.id: "codex"` 또는 `OPENCLAW_AGENT_RUNTIME=codex`를 명시적으로 강제해야 합니다. 레거시 `codex/*` 모델 참조는 호환성을 위해 여전히 하네스를 자동 선택하지만, 런타임 기반 레거시 제공자 접두사는 일반 모델/제공자 선택지로 표시되지 않습니다.
하네스는 기본적으로 꺼져 있습니다. 새 구성은 OpenAI 모델 참조를
`openai/gpt-*`라는 정식 형식으로 유지하고, 네이티브 앱 서버 실행을 원할 때
`agentRuntime.id: "codex"` 또는 `OPENCLAW_AGENT_RUNTIME=codex`를
명시적으로 강제해야 합니다. 레거시 `codex/*` 모델 참조는 호환성을 위해 여전히
하네스를 자동 선택하지만, 런타임 기반 레거시 제공자 접두사는 일반 모델/제공자
선택지로 표시되지 않습니다.
`codex` Plugin이 활성화되어 있지만 기본 모델이 여전히 `openai-codex/*`이면 `openclaw doctor`는 경로를 변경하는 대신 경고합니다. 이는 의도된 동작입니다. `openai-codex/*`는 계속 PI Codex OAuth/구독 경로로 남고, 네이티브 app-server 실행은 명시적 런타임 선택으로 유지됩니다.
`codex` Plugin이 활성화되어 있지만 기본 모델이 여전히 `openai-codex/*`이면,
`openclaw doctor`는 경로를 변경하지 않고 경고합니다. 이는 의도된 동작입니다.
`openai-codex/*`는 PI Codex OAuth/구독 경로로 유지되며, 네이티브 앱 서버 실행은
명시적인 런타임 선택으로 남습니다.
## 경로 맵
구성을 변경하기 전에 이 표를 사용하세요.
| 원하는 동작 | 모델 참조 | 런타임 구성 | Plugin 요구 사항 | 예상 상태 레이블 |
| ------------------------------------------- | -------------------------- | -------------------------------------- | --------------------------- | ------------------------------ |
| 일반 OpenClaw 러너를 통한 OpenAI API | `openai/gpt-*` | 생략 또는 `runtime: "pi"` | OpenAI 제공자 | `Runtime: OpenClaw Pi Default` |
| PI를 통한 Codex OAuth/구독 | `openai-codex/gpt-*` | 생략 또는 `runtime: "pi"` | OpenAI Codex OAuth 제공자 | `Runtime: OpenClaw Pi Default` |
| 네이티브 Codex app-server 임베디드 턴 | `openai/gpt-*` | `agentRuntime.id: "codex"` | `codex` Plugin | `Runtime: OpenAI Codex` |
| 보수적 자동 모드의 혼합 제공자 | 제공자별 참조 | `agentRuntime.id: "auto"` | 선택적 Plugin 런타임 | 선택된 런타임에 따라 다름 |
| 명시적 Codex ACP 어댑터 세션 | ACP 프롬프트/모델에 따라 다름 | `sessions_spawn` with `runtime: "acp"` | 정상 `acpx` 백엔드 | ACP 작업/세션 상태 |
| 원하는 동작 | 모델 참조 | 런타임 구성 | Plugin 요구 사항 | 예상 상태 레이블 |
| ------------------------------------------- | -------------------------- | -------------------------------------- | ----------------------------- | ------------------------------ |
| 일반 OpenClaw 러너를 통한 OpenAI API | `openai/gpt-*` | 생략 또는 `runtime: "pi"` | OpenAI 제공자 | `Runtime: OpenClaw Pi Default` |
| PI를 통한 Codex OAuth/구독 | `openai-codex/gpt-*` | 생략 또는 `runtime: "pi"` | OpenAI Codex OAuth 제공자 | `Runtime: OpenClaw Pi Default` |
| 네이티브 Codex 앱 서버 임베디드 턴 | `openai/gpt-*` | `agentRuntime.id: "codex"` | `codex` Plugin | `Runtime: OpenAI Codex` |
| 보수적 자동 모드의 혼합 제공자 | 제공자별 참조 | `agentRuntime.id: "auto"` | 선택적 Plugin 런타임 | 선택된 런타임에 따라 다름 |
| 명시적 Codex ACP 어댑터 세션 | ACP 프롬프트/모델에 따라 다름 | `sessions_spawn` with `runtime: "acp"` | 정상 `acpx` 백엔드 | ACP 작업/세션 상태 |
중요한 구분은 제공자와 런타임입니다.
- `openai-codex/*`는 "PI가 어떤 제공자/인증 경로를 사용해야 하는가?"에 답합니다.
- `agentRuntime.id: "codex"`는 "어떤 루프가 이 임베디드 턴을 실행해야 하는가?"에 답합니다.
- `/codex ...`는 "이 채팅이 어떤 네이티브 Codex 대화에 바인딩되거나 이를 제어해야 하는가?"에 답합니다.
- ACP는 "acpx가 어떤 외부 하네스 프로세스를 실행해야 하는가?"에 답합니다.
- `agentRuntime.id: "codex"`는 "어떤 루프가 이
임베디드 턴을 실행해야 하는가?"에 답합니다.
- `/codex ...`는 "이 채팅이 어떤 네이티브 Codex 대화에 바인딩되거나
그것을 제어해야 하는가?"에 답합니다.
- ACP는 "acpx가 어떤 외부 하네스 프로세스를 시작해야 하는가?"에 답합니다.
## 올바른 모델 접두사 선택
OpenAI 계열 경로는 접두사별로 구분됩니다. PI를 통한 Codex OAuth를 원하면 `openai-codex/*`를 사용하고, 직접 OpenAI API 액세스를 원하거나 네이티브 Codex app-server 하네스를 강제하는 경우에는 `openai/*`를 사용하세요.
OpenAI 계열 경로는 접두사별로 구분됩니다. PI를 통해 Codex OAuth를 원하면
`openai-codex/*`를 사용하고, 직접 OpenAI API 접근을 원하거나 네이티브 Codex 앱
서버 하네스를 강제할 때는 `openai/*`를 사용하세요.
| 모델 참조 | 런타임 경로 | 사용 시점 |
| 모델 참조 | 런타임 경로 | 사용 시점 |
| --------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
| `openai/gpt-5.4` | OpenClaw/PI 배관을 통한 OpenAI 제공자 | `OPENAI_API_KEY`로 현재 직접 OpenAI Platform API 액세스를 원할 때. |
| `openai-codex/gpt-5.5` | OpenClaw/PI를 통한 OpenAI Codex OAuth | 기본 PI 러너에서 ChatGPT/Codex 구독 인증을 원할 때. |
| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex app-server 하네스 | 임베디드 에이전트 턴에 대해 네이티브 Codex app-server 실행을 원할 때. |
| `openai/gpt-5.4` | OpenClaw/PI 배관을 통한 OpenAI 제공자 | `OPENAI_API_KEY`로 현재 직접 OpenAI Platform API 접근을 원할 때. |
| `openai-codex/gpt-5.5` | OpenClaw/PI를 통한 OpenAI Codex OAuth | 기본 PI 러너와 함께 ChatGPT/Codex 구독 인증을 원할 때. |
| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex 앱 서버 하네스 | 임베디드 에이전트 턴에 네이티브 Codex 앱 서버 실행을 원할 때. |
GPT-5.5는 현재 OpenClaw에서 구독/OAuth 전용입니다. PI OAuth에는 `openai-codex/gpt-5.5`를 사용하거나, Codex app-server 하네스와 함께 `openai/gpt-5.5`를 사용하세요. OpenAI가 공개 API에서 GPT-5.5를 활성화하면 `openai/gpt-5.5`에 대한 직접 API 키 액세스가 지원됩니다.
GPT-5.5는 현재 OpenClaw에서 구독/OAuth 전용입니다. PI OAuth에는
`openai-codex/gpt-5.5`를 사용하거나, Codex 앱 서버 하네스와 함께
`openai/gpt-5.5`를 사용하세요. `openai/gpt-5.5`에 대한 직접 API 키 접근은
OpenAI가 공개 API에서 GPT-5.5를 활성화하면 지원됩니다.
레거시 `codex/gpt-*` 참조는 호환성 별칭으로 계속 허용됩니다. Doctor 호환성 마이그레이션은 레거시 기본 런타임 참조를 정식 모델 참조로 다시 쓰고 런타임 정책을 별도로 기록하지만, 폴백 전용 레거시 참조는 런타임이 전체 에이전트 컨테이너에 대해 구성되므로 변경하지 않습니다. 새 PI Codex OAuth 구성은 `openai-codex/gpt-*`를 사용해야 하며, 새 네이티브 app-server 하네스 구성은 `agentRuntime.id: "codex"`와 함께 `openai/gpt-*`를 사용해야 합니다.
레거시 `codex/gpt-*` 참조는 호환성 별칭으로 계속 허용됩니다. Doctor 호환성
마이그레이션은 레거시 기본 런타임 참조를 정식 모델 참조로 다시 쓰고 런타임
정책을 별도로 기록하지만, 폴백 전용 레거시 참조는 런타임이 전체 에이전트
컨테이너에 대해 구성되므로 변경하지 않습니다. 새 PI Codex OAuth 구성은
`openai-codex/gpt-*`를 사용해야 하며, 새 네이티브 앱 서버 하네스 구성은
`openai/gpt-*`와 `agentRuntime.id: "codex"`를 함께 사용해야 합니다.
`agents.defaults.imageModel`도 동일한 접두사 구분을 따릅니다. 이미지 이해가 OpenAI Codex OAuth 제공자 경로를 통해 실행되어야 하면 `openai-codex/gpt-*`를 사용하세요. 이미지 이해가 제한된 Codex app-server 턴을 통해 실행되어야 하면 `codex/gpt-*`를 사용하세요. Codex app-server 모델은 이미지 입력 지원을 광고해야 합니다. 텍스트 전용 Codex 모델은 미디어 턴이 시작되기 전에 실패합니다.
`agents.defaults.imageModel`도 동일한 접두사 구분을 따릅니다. 이미지 이해가
OpenAI Codex OAuth 제공자 경로를 통해 실행되어야 하면 `openai-codex/gpt-*`를
사용하세요. 이미지 이해가 제한된 Codex 앱 서버 턴을 통해 실행되어야 하면
`codex/gpt-*`를 사용하세요. Codex 앱 서버 모델은 이미지 입력 지원을 광고해야
합니다. 텍스트 전용 Codex 모델은 미디어 턴이 시작되기 전에 실패합니다.
현재 세션의 유효 하네스를 확인하려면 `/status`를 사용하세요. 선택이 예상과 다르면 `agents/harness` 하위 시스템의 디버그 로깅을 활성화하고 Gateway의 구조화된 `agent harness selected` 레코드를 검사하세요. 여기에는 선택된 하네스 ID, 선택 이유, 런타임/폴백 정책, 그리고 `auto` 모드에서는 각 Plugin 후보의 지원 결과가 포함됩니다.
현재 세션의 유효 하네스를 확인하려면 `/status`를 사용하세요. 선택이 예상과 다르면
`agents/harness` 하위 시스템에 대한 디버그 로깅을 활성화하고 Gateway의 구조화된
`agent harness selected` 레코드를 검사하세요. 여기에는 선택된 하네스 ID, 선택
이유, 런타임/폴백 정책, 그리고 `auto` 모드에서는 각 Plugin 후보의 지원 결과가
포함됩니다.
### Doctor 경고의 의미
다음이 모두 참일 때 `openclaw doctor`가 경고합니다.
`openclaw doctor`는 다음이 모두 참일 때 경고합니다.
- 번들 `codex` Plugin이 활성화되었거나 허용됨
- 번들 `codex` Plugin이 활성화되어 있거나 허용됨
- 에이전트의 기본 모델이 `openai-codex/*`
- 해당 에이전트의 유효 런타임이 `codex`가 아님
이 경고는 사용자가 종종 "Codex Plugin 활성화"가 "네이티브 Codex app-server 런타임"을 의미한다고 기대하기 때문에 존재합니다. OpenClaw는 그런 추론을 하지 않습니다. 이 경고의 의미는 다음과 같습니다.
이 경고가 있는 이유는 사용자가 종종 "Codex Plugin 활성화"가 "네이티브 Codex 앱
서버 런타임"을 의미한다고 기대하기 때문입니다. OpenClaw는 그런 도약을 하지
않습니다. 경고의 의미는 다음과 같습니다.
- PI를 통한 ChatGPT/Codex OAuth를 의도했다면 **변경이 필요하지 않습니다**.
- 네이티브 app-server 실행을 의도했다면 모델을 `openai/<model>`로 변경하고 `agentRuntime.id: "codex"`를 설정하세요.
- 런타임 변경 후에도 기존 세션에는 `/new` 또는 `/reset`이 필요합니다. 세션 런타임 핀은 고정적이기 때문입니다.
- PI를 통한 ChatGPT/Codex OAuth를 의도했다면 **변경이 필요 없습니다**.
- 네이티브 앱 서버 실행을 의도했다면 모델을 `openai/<model>`로 변경하고
`agentRuntime.id: "codex"`를 설정하세요.
- 세션 런타임 핀은 고정적이므로, 기존 세션은 런타임 변경 후에도
`/new` 또는 `/reset`이 필요합니다.
하네스 선택은 라이브 세션 제어가 아닙니다. 임베디드 턴이 실행될 때 OpenClaw는 선택된 하네스 ID를 해당 세션에 기록하고 같은 세션 ID의 이후 턴에도 계속 사용합니다. 향후 세션이 다른 하네스를 사용하도록 하려면 `agentRuntime` 구성 또는 `OPENCLAW_AGENT_RUNTIME`을 변경하세요. 기존 대화를 PI와 Codex 사이에서 전환하기 전에 `/new` 또는 `/reset`으로 새 세션을 시작하세요. 이렇게 하면 하나의 대화 기록을 호환되지 않는 두 네이티브 세션 시스템에서 재생하는 일을 피할 수 있습니다.
하네스 선택은 라이브 세션 제어가 아닙니다. 임베디드 턴이 실행될 때 OpenClaw는
선택된 하네스 ID를 해당 세션에 기록하고 같은 세션 ID의 이후 턴에도 계속
사용합니다. 이후 세션이 다른 하네스를 사용하게 하려면 `agentRuntime` 구성 또는
`OPENCLAW_AGENT_RUNTIME`을 변경하세요. PI와 Codex 사이에서 기존 대화를 전환하기
전에 새 세션을 시작하려면 `/new` 또는 `/reset`을 사용하세요. 이렇게 하면 하나의
트랜스크립트를 호환되지 않는 두 네이티브 세션 시스템으로 재생하는 일을 피할 수
있습니다.
하네스 핀이 생기기 전에 생성된 레거시 세션은 대화 기록이 있으면 PI에 핀된 것으로 처리됩니다. 구성을 변경한 뒤 해당 대화를 Codex로 전환하려면 `/new` 또는 `/reset`을 사용하세요.
하네스 핀이 생기기 전에 생성된 레거시 세션은 트랜스크립트 기록이 있으면 PI 핀으로
처리됩니다. 구성을 변경한 후 해당 대화를 Codex로 선택 적용하려면 `/new` 또는
`/reset`을 사용하세요.
`/status`는 유효 모델 런타임을 표시합니다. 기본 PI 하네스는 `Runtime: OpenClaw Pi Default`로 표시되고, Codex app-server 하네스는 `Runtime: OpenAI Codex`로 표시됩니다.
`/status`는 유효 모델 런타임을 표시합니다. 기본 PI 하네스는
`Runtime: OpenClaw Pi Default`로 표시되고, Codex 앱 서버 하네스는
`Runtime: OpenAI Codex`로 표시됩니다.
## 요구 사항
- 번들 `codex` Plugin을 사용할 수 있는 OpenClaw.
- Codex app-server `0.125.0` 이상. 번들 Plugin은 기본적으로 호환되는 Codex app-server 바이너리를 관리하므로, `PATH`의 로컬 `codex` 명령은 일반 하네스 시작에 영향을 주지 않습니다.
- app-server 프로세스 또는 OpenClaw의 Codex 인증 브리지에서 사용할 수 있는 Codex 인증.
- Codex 앱 서버 `0.125.0` 이상. 번들 Plugin은 기본적으로 호환되는 Codex 앱 서버
바이너리를 관리하므로, `PATH`의 로컬 `codex` 명령은 일반 하네스 시작에 영향을
주지 않습니다.
- 앱 서버 프로세스 또는 OpenClaw의 Codex 인증 브리지에서 사용할 수 있는 Codex 인증.
로컬 앱 서버 실행은 각 에이전트마다 OpenClaw가 관리하는 Codex 홈과 격리된 자식
`HOME`을 사용하므로 기본적으로 개인 `~/.codex` 계정, Skills, Plugin, 구성,
스레드 상태 또는 네이티브 `$HOME/.agents/skills`를 읽지 않습니다.
Plugin은 오래되었거나 버전이 없는 app-server 핸드셰이크를 차단합니다. 이렇게 하면 OpenClaw가 테스트된 프로토콜 표면에 머물게 됩니다.
Plugin은 오래되었거나 버전이 없는 앱 서버 핸드셰이크를 차단합니다. 이렇게 하면
OpenClaw가 테스트된 프로토콜 표면 위에 유지됩니다.
라이브 및 Docker 스모크 테스트의 경우 인증은 일반적으로 Codex CLI 계정 또는 OpenClaw `openai-codex` 인증 프로필에서 옵니다. 로컬 stdio app-server 실행은 계정이 없을 때 `CODEX_API_KEY` / `OPENAI_API_KEY`로 폴백할 수도 있습니다.
라이브 및 Docker 스모크 테스트의 경우 인증은 보통 Codex CLI 계정 또는 OpenClaw
`openai-codex` 인증 프로필에서 가져옵니다. 로컬 stdio 앱 서버 실행은 계정이 없을
때 `CODEX_API_KEY` / `OPENAI_API_KEY`로 폴백할 수도 있습니다.
## 최소 구성
`openai/gpt-5.5`를 사용하고, 번들 Plugin을 활성화한 뒤, `codex` 하네스를 강제하세요.
`openai/gpt-5.5`를 사용하고, 번들 Plugin을 활성화하며, `codex` 하네스를
강제하세요.
```json5
{
@ -151,7 +219,7 @@ Plugin은 오래되었거나 버전이 없는 app-server 핸드셰이크를 차
}
```
구성이 `plugins.allow`를 사용한다면 거기에도 `codex`를 포함하세요.
구성에서 `plugins.allow`를 사용한다면 거기에도 `codex`를 포함하세요.
```json5
{
@ -166,21 +234,21 @@ Plugin은 오래되었거나 버전이 없는 app-server 핸드셰이크를 차
}
```
`agents.defaults.model` 또는 에이전트 모델을 `codex/<model>`로 설정하는 레거시 구성은 여전히 번들 `codex` Plugin을 자동 활성화합니다. 새 구성은 위의 명시적 `agentRuntime` 항목과 함께 `openai/<model>`을 선호해야 합니다.
`agents.defaults.model` 또는 에이전트 모델을 `codex/<model>`로 설정한 레거시
구성은 여전히 번들 `codex` Plugin을 자동 활성화합니다. 새 구성은 위의 명시적
`agentRuntime` 항목과 함께 `openai/<model>`을 선호해야 합니다.
## 다른 모델과 함께 Codex 추가
같은 에이전트가 Codex와 비 Codex 제공자 모델 사이를 자유롭게 전환해야 한다면 `agentRuntime.id: "codex"`를 전역으로 설정하지 마세요. 강제된 런타임은 해당 에이전트 또는 세션의 모든 임베디드 턴에 적용됩니다. 그 런타임이 강제된 상태에서 Anthropic 모델을 선택하면, OpenClaw는 해당 턴을 조용히 PI로 라우팅하는 대신 여전히 Codex 하네스를 시도하고 실패 폐쇄됩니다.
동일한 에이전트가 Codex와 비-Codex 제공자 모델 사이를 자유롭게 전환해야 한다면 `agentRuntime.id: "codex"`를 전역으로 설정하지 마세요. 강제된 런타임은 해당 에이전트 또는 세션의 모든 임베디드 턴에 적용됩니다. 해당 런타임이 강제된 상태에서 Anthropic 모델을 선택하면, OpenClaw는 여전히 Codex 하네스를 시도하며 해당 턴을 PI를 통해 조용히 라우팅하는 대신 닫힌 상태로 실패합니다.
대신 다음 형태 중 하나를 사용하세요.
- 전용 에이전트에 `agentRuntime.id: "codex"`로 Codex를 배치합니다.
- 일반적인 혼합 공급자 사용을 위해 기본 에이전트는 `agentRuntime.id: "auto"`와 PI 폴백으로 유지합니다.
- 레거시 `codex/*` 참조는 호환성 목적으로만 사용합니다. 새 구성은
`openai/*`와 명시적인 Codex 런타임 정책을 선호해야 합니다.
- `agentRuntime.id: "codex"`를 사용해 Codex를 전용 에이전트에 배치합니다.
- 일반적인 혼합 제공자 사용을 위해 기본 에이전트를 `agentRuntime.id: "auto"`와 PI 폴백으로 유지합니다.
- 레거시 `codex/*` 참조는 호환성 용도로만 사용합니다. 새 구성은 `openai/*`와 명시적인 Codex 런타임 정책을 선호해야 합니다.
예를 들어, 다음은 기본 에이전트를 일반 자동 선택에 유지하고
별도의 Codex 에이전트를 추가합니다.
예를 들어, 다음은 기본 에이전트를 일반 자동 선택 상태로 유지하고 별도의 Codex 에이전트를 추가합니다.
```json5
{
@ -219,36 +287,31 @@ Plugin은 오래되었거나 버전이 없는 app-server 핸드셰이크를 차
이 형태에서는 다음과 같습니다.
- 기본 `main` 에이전트는 일반 공급자 경로와 PI 호환성 폴백을 사용합니다.
- `codex` 에이전트는 Codex 앱 서버 하네스를 사용합니다.
- `codex` 에이전트에 대해 Codex가 없거나 지원되지 않으면, 조용히 PI를 사용하는 대신
해당 턴이 실패합니다.
- 기본 `main` 에이전트는 일반 제공자 경로와 PI 호환성 폴백을 사용합니다.
- `codex` 에이전트는 Codex app-server 하네스를 사용합니다.
- `codex` 에이전트에 Codex가 없거나 지원되지 않으면 턴은 PI를 조용히 사용하는 대신 실패합니다.
## 에이전트 명령 라우팅
에이전트는 "Codex"라는 단어만이 아니라 의도에 따라 사용자 요청을 라우팅해야 합니다.
| 사용자가 요청하는 내용... | 에이전트가 사용해야 하는 것... |
| 사용자가 요청하는 내용... | 에이전트가 사용해야 하는 것... |
| -------------------------------------------------------- | ------------------------------------------------ |
| "이 채팅을 Codex에 바인딩" | `/codex bind` |
| "Codex 스레드 `<id>`를 여기서 재개" | `/codex resume <id>` |
| "Codex 스레드 표시" | `/codex threads` |
| "잘못된 Codex 실행에 대한 지원 보고서 제출" | `/diagnostics [note]` |
| "이 첨부된 스레드에 대해서만 Codex 피드백 전송" | `/codex diagnostics [note]` |
| "이 에이전트의 런타임으로 Codex 사용" | `agentRuntime.id` 구성 변경 |
| "일반 OpenClaw에서 내 ChatGPT/Codex 구독 사용" | `openai-codex/*` 모델 참조 |
| "ACP/acpx를 통해 Codex 실행" | ACP `sessions_spawn({ runtime: "acp", ... })` |
| "스레드에서 Claude Code/Gemini/OpenCode/Cursor 시작" | ACP/acpx, `/codex`도 아니고 네이티브 하위 에이전트도 아님 |
| "이 채팅을 Codex에 바인딩" | `/codex bind` |
| "여기서 Codex 스레드 `<id>` 재개" | `/codex resume <id>` |
| "Codex 스레드 표시" | `/codex threads` |
| "잘못된 Codex 실행에 대한 지원 보고서 제출" | `/diagnostics [note]` |
| "이 첨부된 스레드에 대해서만 Codex 피드백 보내기" | `/codex diagnostics [note]` |
| "이 에이전트의 런타임으로 Codex 사용" | `agentRuntime.id`로 구성 변경 |
| "일반 OpenClaw에서 내 ChatGPT/Codex 구독 사용" | `openai-codex/*` 모델 참조 |
| "ACP/acpx를 통해 Codex 실행" | ACP `sessions_spawn({ runtime: "acp", ... })` |
| "스레드에서 Claude Code/Gemini/OpenCode/Cursor 시작" | ACP/acpx, `/codex`도 네이티브 하위 에이전트도 아님 |
OpenClaw는 ACP가 활성화되어 있고, 디스패치 가능하며, 로드된 런타임 백엔드로 뒷받침될 때만
에이전트에 ACP 스폰 가이드를 광고합니다. ACP를 사용할 수 없으면
시스템 프롬프트와 Plugin Skills는 에이전트에게 ACP 라우팅을 가르치지 않아야 합니다.
OpenClaw는 ACP가 활성화되어 있고, 디스패치 가능하며, 로드된 런타임 백엔드가 뒷받침할 때만 에이전트에 ACP 스폰 가이드를 알립니다. ACP를 사용할 수 없으면 시스템 프롬프트와 Plugin Skills는 에이전트에게 ACP 라우팅을 가르치면 안 됩니다.
## Codex 전용 배포
모든 내장 에이전트 턴이 Codex를 사용한다는 것을 증명해야 할 때 Codex 하네스를 강제합니다.
명시적 Plugin 런타임은 기본적으로 PI 폴백이 없으므로
`fallback: "none"`은 선택 사항이지만 문서화 용도로 유용한 경우가 많습니다.
모든 임베디드 에이전트 턴이 Codex를 사용한다는 것을 증명해야 할 때 Codex 하네스를 강제하세요. 명시적 Plugin 런타임은 기본적으로 PI 폴백이 없으므로 `fallback: "none"`은 선택 사항이지만 문서화 목적으로 유용한 경우가 많습니다.
```json5
{
@ -270,10 +333,7 @@ OpenClaw는 ACP가 활성화되어 있고, 디스패치 가능하며, 로드된
OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
```
Codex가 강제되면 Codex Plugin이 비활성화되어 있거나,
앱 서버가 너무 오래되었거나, 앱 서버를 시작할 수 없는 경우 OpenClaw는 일찍 실패합니다.
누락된 하네스 선택을 의도적으로 PI가 처리하게 하려는 경우에만
`OPENCLAW_AGENT_HARNESS_FALLBACK=pi`를 설정하세요.
Codex가 강제되면 Codex Plugin이 비활성화되어 있거나, app-server가 너무 오래되었거나, app-server를 시작할 수 없는 경우 OpenClaw가 일찍 실패합니다. 누락된 하네스 선택을 의도적으로 PI가 처리하게 하려는 경우에만 `OPENCLAW_AGENT_HARNESS_FALLBACK=pi`를 설정하세요.
## 에이전트별 Codex
@ -308,21 +368,17 @@ Codex가 강제되면 Codex Plugin이 비활성화되어 있거나,
}
```
일반 세션 명령을 사용해 에이전트와 모델을 전환하세요. `/new`는 새
OpenClaw 세션을 만들고, Codex 하네스는 필요에 따라 사이드카 앱 서버
스레드를 만들거나 재개합니다. `/reset`은 해당 스레드의 OpenClaw 세션 바인딩을 지우고
다음 턴이 현재 구성에서 하네스를 다시 해석하도록 합니다.
일반 세션 명령을 사용해 에이전트와 모델을 전환하세요. `/new`는 새 OpenClaw 세션을 만들고 Codex 하네스는 필요에 따라 사이드카 app-server 스레드를 만들거나 재개합니다. `/reset`은 해당 스레드에 대한 OpenClaw 세션 바인딩을 지우고 다음 턴이 현재 구성에서 하네스를 다시 해석하도록 합니다.
## 모델 검색
## 모델 발견
기본적으로 Codex Plugin은 사용 가능한 모델을 앱 서버에 요청합니다. 검색이 실패하거나
시간 초과되면 다음에 대해 번들된 폴백 카탈로그를 사용합니다.
기본적으로 Codex Plugin은 app-server에 사용 가능한 모델을 요청합니다. 발견이 실패하거나 시간이 초과되면 다음 항목에 대해 번들된 폴백 카탈로그를 사용합니다.
- GPT-5.5
- GPT-5.4 mini
- GPT-5.2
`plugins.entries.codex.config.discovery`에서 검색을 조정할 수 있습니다.
`plugins.entries.codex.config.discovery` 아래에서 발견을 조정할 수 있습니다.
```json5
{
@ -342,7 +398,7 @@ OpenClaw 세션을 만들고, Codex 하네스는 필요에 따라 사이드카
}
```
시작 시 Codex를 탐색하지 않고 폴백 카탈로그만 사용하려면 검색을 비활성화하세요.
시작 시 Codex를 탐색하지 않고 폴백 카탈로그를 그대로 사용하려면 발견을 비활성화하세요.
```json5
{
@ -361,27 +417,19 @@ OpenClaw 세션을 만들고, Codex 하네스는 필요에 따라 사이드카
}
```
## 앱 서버 연결 및 정책
## App-server 연결 및 정책
기본적으로 Plugin은 다음을 사용해 OpenClaw의 관리형 Codex 바이너리를 로컬에서 시작합니다.
기본적으로 Plugin은 다음으로 OpenClaw의 관리형 Codex 바이너리를 로컬에서 시작합니다.
```bash
codex app-server --listen stdio://
```
관리형 바이너리는 번들된 Plugin 런타임 종속성으로 선언되며
나머지 `codex` Plugin 종속성과 함께 스테이징됩니다. 이렇게 하면 앱 서버
버전이 로컬에 우연히 설치된 별도의 Codex CLI가 아니라 번들된 Plugin에 묶입니다.
다른 실행 파일을 의도적으로 실행하려는 경우에만 `appServer.command`를 설정하세요.
관리형 바이너리는 번들 Plugin 런타임 의존성으로 선언되며 나머지 `codex` Plugin 의존성과 함께 스테이징됩니다. 이렇게 하면 로컬에 별도로 설치되어 있을 수 있는 Codex CLI가 아니라 번들 Plugin에 app-server 버전이 연결됩니다. 의도적으로 다른 실행 파일을 실행하려는 경우에만 `appServer.command`를 설정하세요.
기본적으로 OpenClaw는 로컬 Codex 하네스 세션을 YOLO 모드로 시작합니다.
`approvalPolicy: "never"`, `approvalsReviewer: "user"`,
`sandbox: "danger-full-access"`입니다. 이는 자율 Heartbeat에 사용되는 신뢰된
로컬 운영자 자세입니다. Codex는 답변할 사람이 없는 네이티브 승인 프롬프트에서
멈추지 않고 셸과 네트워크 도구를 사용할 수 있습니다.
기본적으로 OpenClaw는 YOLO 모드에서 로컬 Codex 하네스 세션을 시작합니다. `approvalPolicy: "never"`, `approvalsReviewer: "user"`, `sandbox: "danger-full-access"`입니다. 이는 자율 Heartbeat에 사용되는 신뢰된 로컬 운영자 자세입니다. Codex는 답변할 사람이 없는 네이티브 승인 프롬프트에서 멈추지 않고 셸 및 네트워크 도구를 사용할 수 있습니다.
Codex 보호자 검토 승인에 옵트인하려면 `appServer.mode:
"guardian"`을 설정하세요.
Codex 가디언 검토 승인에 옵트인하려면 `appServer.mode: "guardian"`을 설정하세요.
```json5
{
@ -401,19 +449,11 @@ Codex 보호자 검토 승인에 옵트인하려면 `appServer.mode:
}
```
Guardian 모드는 Codex의 네이티브 자동 검토 승인 경로를 사용합니다. Codex가
샌드박스를 벗어나거나, 워크스페이스 밖에 쓰거나, 네트워크 액세스 같은 권한을 추가하려고 요청하면
Codex는 해당 승인 요청을 사람 프롬프트 대신 네이티브 검토자에게 라우팅합니다.
검토자는 Codex의 위험 프레임워크를 적용하고 특정 요청을 승인하거나 거부합니다.
YOLO 모드보다 더 많은 가드레일이 필요하지만 무인 에이전트가 계속 진행해야 할 때 Guardian을 사용하세요.
가디언 모드는 Codex의 네이티브 자동 검토 승인 경로를 사용합니다. Codex가 샌드박스를 벗어나거나, 워크스페이스 밖에 쓰거나, 네트워크 액세스 같은 권한을 추가하려고 요청하면, Codex는 해당 승인 요청을 사람 프롬프트 대신 네이티브 검토자로 라우팅합니다. 검토자는 Codex의 위험 프레임워크를 적용하고 특정 요청을 승인하거나 거부합니다. YOLO 모드보다 더 많은 가드레일이 필요하지만 무인 에이전트가 계속 진행해야 할 때 가디언을 사용하세요.
`guardian` 프리셋은 `approvalPolicy: "on-request"`,
`approvalsReviewer: "auto_review"`, `sandbox: "workspace-write"`로 확장됩니다.
개별 정책 필드는 여전히 `mode`를 재정의하므로 고급 배포에서는
프리셋을 명시적 선택과 혼합할 수 있습니다. 이전 `guardian_subagent` 검토자 값은
호환성 별칭으로 계속 허용되지만, 새 구성은 `auto_review`를 사용해야 합니다.
`guardian` 프리셋은 `approvalPolicy: "on-request"`, `approvalsReviewer: "auto_review"`, `sandbox: "workspace-write"`로 확장됩니다. 개별 정책 필드는 여전히 `mode`를 재정의하므로 고급 배포에서는 프리셋과 명시적 선택을 혼합할 수 있습니다. 이전 `guardian_subagent` 검토자 값은 호환성 별칭으로 계속 허용되지만, 새 구성은 `auto_review`를 사용해야 합니다.
이미 실행 중인 앱 서버의 경우 WebSocket 전송을 사용하세요.
이미 실행 중인 app-server에는 WebSocket 전송을 사용하세요.
```json5
{
@ -435,23 +475,26 @@ YOLO 모드보다 더 많은 가드레일이 필요하지만 무인 에이전트
}
```
Stdio 앱 서버 실행은 기본적으로 OpenClaw의 프로세스 환경을 상속하지만,
OpenClaw가 Codex 앱 서버 계정 브리지를 소유합니다. 인증은 다음 순서로 선택됩니다.
Stdio app-server 실행은 기본적으로 OpenClaw의 프로세스 환경을 상속하지만, OpenClaw는 Codex app-server 계정 브리지를 소유하며 `CODEX_HOME`과 `HOME`을 모두 해당 에이전트의 OpenClaw 상태 아래에 있는 에이전트별 디렉터리로 설정합니다. Codex 자체 Skills 로더는 `$CODEX_HOME/skills`와 `$HOME/.agents/skills`를 읽으므로 두 값 모두 로컬 app-server 실행에서 격리됩니다. 이로써 Codex 네이티브 Skills, Plugins, 구성, 계정, 스레드 상태가 운영자의 개인 Codex CLI 홈에서 유출되지 않고 OpenClaw 에이전트 범위로 제한됩니다.
OpenClaw Plugins와 OpenClaw Skills 스냅샷은 여전히 OpenClaw 자체 Plugin 레지스트리와 Skills 로더를 통해 흐릅니다. 개인 Codex CLI 자산은 그렇지 않습니다. OpenClaw 에이전트의 일부가 되어야 하는 유용한 Codex CLI Skills 또는 Plugins가 있다면 명시적으로 인벤토리를 작성하세요.
```bash
openclaw migrate codex --dry-run
openclaw migrate apply codex --yes
```
Codex 마이그레이션 제공자는 Skills를 현재 OpenClaw 에이전트 워크스페이스로 복사합니다. Codex 네이티브 Plugins, 훅, 구성 파일은 자동으로 활성화되지 않고 수동 검토를 위해 보고되거나 보관됩니다. 명령을 실행하거나, MCP 서버를 노출하거나, 자격 증명을 포함할 수 있기 때문입니다.
인증은 다음 순서로 선택됩니다.
1. 에이전트에 대한 명시적 OpenClaw Codex 인증 프로필.
2. 로컬 Codex CLI ChatGPT 로그인 같은 앱 서버의 기존 계정.
3. 로컬 stdio 앱 서버 실행에 한해서, 앱 서버 계정이 없고 OpenAI 인증이
여전히 필요한 경우 `CODEX_API_KEY`, 그 다음 `OPENAI_API_KEY`.
2. 해당 에이전트의 Codex 홈에 있는 app-server의 기존 계정.
3. 로컬 stdio app-server 실행에 한해서만, app-server 계정이 없고 OpenAI 인증이 여전히 필요한 경우 `CODEX_API_KEY`, 그다음 `OPENAI_API_KEY`.
OpenClaw가 ChatGPT 구독 스타일의 Codex 인증 프로필을 발견하면, 생성된 Codex 자식 프로세스에서
`CODEX_API_KEY`와 `OPENAI_API_KEY`를 제거합니다. 이렇게 하면 Gateway 수준 API 키는
임베딩이나 직접 OpenAI 모델에 사용할 수 있으면서도 네이티브 Codex 앱 서버 턴이
실수로 API를 통해 과금되지 않도록 합니다. 명시적 Codex API 키 프로필과 로컬 stdio
환경 키 폴백은 상속된 자식 프로세스 환경 대신 앱 서버 로그인을 사용합니다. WebSocket 앱 서버 연결은
Gateway 환경 API 키 폴백을 받지 않습니다. 명시적 인증 프로필이나 원격 앱 서버 자체 계정을 사용하세요.
OpenClaw가 ChatGPT 구독 스타일 Codex 인증 프로필을 발견하면, 생성된 Codex 자식 프로세스에서 `CODEX_API_KEY`와 `OPENAI_API_KEY`를 제거합니다. 이렇게 하면 Gateway 수준 API 키는 임베딩 또는 직접 OpenAI 모델에 사용할 수 있으면서도, 네이티브 Codex app-server 턴이 실수로 API를 통해 청구되지 않습니다. 명시적 Codex API 키 프로필과 로컬 stdio 환경 키 폴백은 상속된 자식 프로세스 환경 대신 app-server 로그인을 사용합니다. WebSocket app-server 연결은 Gateway 환경 API 키 폴백을 받지 않습니다. 명시적 인증 프로필 또는 원격 app-server 자체 계정을 사용하세요.
배포에 추가 환경 격리가 필요한 경우 해당 변수를
`appServer.clearEnv`에 추가하세요.
배포에 추가 환경 격리가 필요하면 해당 변수를 `appServer.clearEnv`에 추가하세요.
```json5
{
@ -470,31 +513,39 @@ Gateway 환경 API 키 폴백을 받지 않습니다. 명시적 인증 프로필
}
```
`appServer.clearEnv`는 생성된 Codex 앱 서버 자식 프로세스에만 영향을 줍니다.
`appServer.clearEnv`는 생성된 Codex app-server 자식 프로세스에만 영향을 줍니다.
지원되는 `appServer` 필드:
| 필드 | 기본값 | 의미 |
| ------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `transport` | `"stdio"` | `"stdio"`는 Codex를 생성하고, `"websocket"`은 `url`에 연결합니다. |
| `command` | 관리형 Codex 바이너리 | stdio 전송용 실행 파일입니다. 관리형 바이너리를 사용하려면 설정하지 말고, 명시적으로 재정의할 때만 설정하세요. |
| `args` | `["app-server", "--listen", "stdio://"]` | stdio 전송용 인수입니다. |
| `url` | 설정 안 됨 | WebSocket app-server URL입니다. |
| `authToken` | 설정 안 됨 | WebSocket 전송용 Bearer 토큰입니다. |
| `headers` | `{}` | 추가 WebSocket 헤더입니다. |
| `clearEnv` | `[]` | OpenClaw가 상속 환경을 구성한 뒤 생성된 stdio app-server 프로세스에서 제거되는 추가 환경 변수 이름입니다. |
| `requestTimeoutMs` | `60000` | app-server 제어 평면 호출의 제한 시간입니다. |
| `mode` | `"yolo"` | YOLO 또는 guardian 검토 실행용 프리셋입니다. |
| `approvalPolicy` | `"never"` | 스레드 시작/재개/턴에 전송되는 네이티브 Codex 승인 정책입니다. |
| `sandbox` | `"danger-full-access"` | 스레드 시작/재개에 전송되는 네이티브 Codex 샌드박스 모드입니다. |
| `approvalsReviewer` | `"user"` | Codex가 네이티브 승인 프롬프트를 검토하게 하려면 `"auto_review"`를 사용하세요. `guardian_subagent`는 레거시 별칭으로 남아 있습니다. |
| `serviceTier` | 설정 안 됨 | 선택적 Codex app-server 서비스 티어입니다: `"fast"`, `"flex"` 또는 `null`. 유효하지 않은 레거시 값은 무시됩니다. |
| 필드 | 기본값 | 의미 |
| ------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transport` | `"stdio"` | `"stdio"`는 Codex를 생성하고, `"websocket"`은 `url`에 연결합니다. |
| `command` | 관리형 Codex 바이너리 | stdio 전송에 사용할 실행 파일입니다. 관리형 바이너리를 사용하려면 설정하지 말고, 명시적으로 재정의할 때만 설정하세요. |
| `args` | `["app-server", "--listen", "stdio://"]` | stdio 전송에 사용할 인수입니다. |
| `url` | 설정 안 됨 | WebSocket 앱 서버 URL입니다. |
| `authToken` | 설정 안 됨 | WebSocket 전송에 사용할 Bearer 토큰입니다. |
| `headers` | `{}` | 추가 WebSocket 헤더입니다. |
| `clearEnv` | `[]` | OpenClaw가 상속 환경을 빌드한 뒤 생성된 stdio 앱 서버 프로세스에서 제거할 추가 환경 변수 이름입니다. `CODEX_HOME` 및 `HOME`은 로컬 실행 시 OpenClaw의 에이전트별 Codex 격리를 위해 예약되어 있습니다. |
| `requestTimeoutMs` | `60000` | 앱 서버 제어 플레인 호출의 제한 시간입니다. |
| `mode` | `"yolo"` | YOLO 또는 guardian 검토가 적용된 실행을 위한 프리셋입니다. |
| `approvalPolicy` | `"never"` | 스레드 시작/재개/턴에 전송되는 기본 Codex 승인 정책입니다. |
| `sandbox` | `"danger-full-access"` | 스레드 시작/재개에 전송되는 기본 Codex 샌드박스 모드입니다. |
| `approvalsReviewer` | `"user"` | Codex가 기본 승인 프롬프트를 검토하도록 하려면 `"auto_review"`를 사용하세요. `guardian_subagent`는 레거시 별칭으로 남아 있습니다. |
| `serviceTier` | 설정 안 됨 | 선택적 Codex 앱 서버 서비스 티어: `"fast"`, `"flex"` 또는 `null`. 유효하지 않은 레거시 값은 무시됩니다. |
OpenClaw 소유 동적 도구 호출은 `appServer.requestTimeoutMs`와 독립적으로 제한됩니다. 각 Codex `item/tool/call` 요청은 30초 이내에 OpenClaw 응답을 받아야 합니다. 제한 시간이 초과되면 OpenClaw는 지원되는 경우 도구 신호를 중단하고 실패한 동적 도구 응답을 Codex에 반환하여 세션을 `processing` 상태로 남겨두지 않고 턴을 계속할 수 있게 합니다.
OpenClaw가 소유한 동적 도구 호출은 `appServer.requestTimeoutMs`와 별도로
제한됩니다. 각 Codex `item/tool/call` 요청은 30초 이내에 OpenClaw 응답을
받아야 합니다. 제한 시간이 지나면 OpenClaw는 지원되는 경우 도구 신호를
중단하고 실패한 동적 도구 응답을 Codex에 반환하여 세션이 `processing`에
남아 있지 않고 턴이 계속될 수 있게 합니다.
OpenClaw가 Codex 턴 범위 app-server 요청에 응답한 뒤, 하네스는 Codex가 네이티브 턴을 `turn/completed`로 마치는 것도 기대합니다. 해당 응답 이후 app-server가 60초 동안 응답하지 않으면 OpenClaw는 최선의 노력으로 Codex 턴을 중단하고, 진단 제한 시간을 기록하며, 오래된 네이티브 턴 뒤에 후속 채팅 메시지가 대기하지 않도록 OpenClaw 세션 레인을 해제합니다.
OpenClaw가 Codex 턴 범위 앱 서버 요청에 응답한 뒤에는, 하네스도 Codex가
기본 턴을 `turn/completed`로 마치기를 기대합니다. 해당 응답 이후 앱 서버가
60초 동안 조용하면 OpenClaw는 최선의 방식으로 Codex 턴을 인터럽트하고,
진단 제한 시간을 기록하며, 후속 채팅 메시지가 오래된 기본 턴 뒤에 대기하지
않도록 OpenClaw 세션 레인을 해제합니다.
로컬 테스트에는 환경 재정의가 계속 제공됩니다:
로컬 테스트에는 환경 재정의를 계속 사용할 수 있습니다.
- `OPENCLAW_CODEX_APP_SERVER_BIN`
- `OPENCLAW_CODEX_APP_SERVER_ARGS`
@ -502,18 +553,29 @@ OpenClaw가 Codex 턴 범위 app-server 요청에 응답한 뒤, 하네스는 Co
- `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY`
- `OPENCLAW_CODEX_APP_SERVER_SANDBOX`
`appServer.command`가 설정되지 않은 경우 `OPENCLAW_CODEX_APP_SERVER_BIN`은 관리형 바이너리를 우회합니다.
`appServer.command`가 설정되지 않은 경우 `OPENCLAW_CODEX_APP_SERVER_BIN`은
관리형 바이너리를 우회합니다.
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1`은 제거되었습니다. 대신 `plugins.entries.codex.config.appServer.mode: "guardian"`을 사용하거나, 일회성 로컬 테스트에는 `OPENCLAW_CODEX_APP_SERVER_MODE=guardian`을 사용하세요. 반복 가능한 배포에는 구성이 선호됩니다. 이렇게 하면 Plugin 동작이 나머지 Codex 하네스 설정과 같은 검토된 파일에 유지되기 때문입니다.
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1`은 제거되었습니다. 대신
`plugins.entries.codex.config.appServer.mode: "guardian"`을 사용하거나,
일회성 로컬 테스트에는 `OPENCLAW_CODEX_APP_SERVER_MODE=guardian`을 사용하세요.
반복 가능한 배포에는 구성이 권장됩니다. 나머지 Codex 하네스 설정과 동일한
검토 대상 파일 안에 Plugin 동작을 유지하기 때문입니다.
## 컴퓨터 사용
컴퓨터 사용은 별도의 설정 가이드에서 다룹니다:
컴퓨터 사용은 자체 설정 가이드에서 다룹니다.
[Codex 컴퓨터 사용](/ko/plugins/codex-computer-use).
간단히 말해 OpenClaw는 데스크톱 제어 앱을 벤더링하거나 데스크톱 작업을 직접 실행하지 않습니다. Codex app-server를 준비하고, `computer-use` MCP 서버를 사용할 수 있는지 확인한 다음, Codex 모드 턴 중 네이티브 MCP 도구 호출을 Codex가 처리하게 합니다.
짧게 말하면, OpenClaw는 데스크톱 제어 앱을 벤더링하거나 데스크톱 동작을
직접 실행하지 않습니다. OpenClaw는 Codex 앱 서버를 준비하고, `computer-use`
MCP 서버를 사용할 수 있는지 확인한 다음, Codex 모드 턴 중 기본 MCP 도구
호출은 Codex가 처리하도록 합니다.
Codex marketplace 흐름 밖에서 직접 TryCua 드라이버에 접근하려면 `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`로 `cua-driver mcp`를 등록하세요. Codex 소유 컴퓨터 사용과 직접 MCP 등록의 차이는 [Codex 컴퓨터 사용](/ko/plugins/codex-computer-use)을 참조하세요.
Codex 마켓플레이스 흐름 밖에서 TryCua 드라이버에 직접 접근하려면
`openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`로
`cua-driver mcp`를 등록하세요. Codex 소유 컴퓨터 사용과 직접 MCP 등록의
차이는 [Codex 컴퓨터 사용](/ko/plugins/codex-computer-use)을 참고하세요.
최소 구성:
@ -543,16 +605,26 @@ Codex marketplace 흐름 밖에서 직접 TryCua 드라이버에 접근하려면
}
```
설정은 명령 표면에서 확인하거나 설치할 수 있습니다:
설정은 명령 표면에서 확인하거나 설치할 수 있습니다.
- `/codex computer-use status`
- `/codex computer-use install`
- `/codex computer-use install --source <marketplace-source>`
- `/codex computer-use install --marketplace-path <path>`
컴퓨터 사용은 macOS 전용이며, Codex MCP 서버가 앱을 제어하기 전에 로컬 OS 권한이 필요할 수 있습니다. `computerUse.enabled`가 true이고 MCP 서버를 사용할 수 없으면, Codex 모드 턴은 네이티브 컴퓨터 사용 도구 없이 조용히 실행되지 않고 스레드가 시작되기 전에 실패합니다. marketplace 선택지, 원격 카탈로그 제한, 상태 이유, 문제 해결은 [Codex 컴퓨터 사용](/ko/plugins/codex-computer-use)을 참조하세요.
컴퓨터 사용은 macOS 전용이며, Codex MCP 서버가 앱을 제어하기 전에 로컬 OS
권한이 필요할 수 있습니다. `computerUse.enabled`가 true이고 MCP 서버를 사용할
수 없으면, 기본 컴퓨터 사용 도구 없이 조용히 실행되는 대신 스레드가 시작되기
전에 Codex 모드 턴이 실패합니다. 마켓플레이스 선택지, 원격 카탈로그 제한,
상태 이유 및 문제 해결은 [Codex 컴퓨터 사용](/ko/plugins/codex-computer-use)을
참고하세요.
`computerUse.autoInstall`이 true인 경우, Codex가 아직 로컬 marketplace를 발견하지 못했다면 OpenClaw는 `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled`에서 표준 번들 Codex Desktop marketplace를 등록할 수 있습니다. 런타임 또는 컴퓨터 사용 구성을 변경한 뒤에는 기존 세션이 오래된 PI 또는 Codex 스레드 바인딩을 유지하지 않도록 `/new` 또는 `/reset`을 사용하세요.
`computerUse.autoInstall`이 true이면, Codex가 아직 로컬 마켓플레이스를
발견하지 못한 경우 OpenClaw는
`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled`에서 표준
번들 Codex Desktop 마켓플레이스를 등록할 수 있습니다. 런타임 또는 컴퓨터 사용
구성을 변경한 뒤에는 기존 세션이 오래된 Pi 또는 Codex 스레드 바인딩을 유지하지
않도록 `/new` 또는 `/reset`을 사용하세요.
## 일반 레시피
@ -592,7 +664,7 @@ Codex 전용 하네스 검증:
}
```
guardian 검토 Codex 승인:
guardian 검토가 적용된 Codex 승인:
```json5
{
@ -614,7 +686,7 @@ guardian 검토 Codex 승인:
}
```
명시적 헤더가 있는 원격 app-server:
명시적 헤더가 있는 원격 앱 서버:
```json5
{
@ -637,45 +709,51 @@ guardian 검토 Codex 승인:
}
```
모델 전환은 OpenClaw가 계속 제어합니다. OpenClaw 세션이 기존 Codex 스레드에 연결되어 있으면, 다음 턴은 현재 선택된 OpenAI 모델, provider, 승인 정책, 샌드박스, 서비스 티어를 app-server에 다시 전송합니다. `openai/gpt-5.5`에서 `openai/gpt-5.2`로 전환하면 스레드 바인딩은 유지되지만 Codex에 새로 선택한 모델로 계속 진행하도록 요청합니다.
모델 전환은 계속 OpenClaw가 제어합니다. OpenClaw 세션이 기존 Codex 스레드에
연결되어 있으면, 다음 턴은 현재 선택된 OpenAI 모델, 공급자, 승인 정책, 샌드박스
및 서비스 티어를 앱 서버로 다시 보냅니다. `openai/gpt-5.5`에서
`openai/gpt-5.2`로 전환하면 스레드 바인딩은 유지되지만, 새로 선택한 모델로
계속 진행하도록 Codex에 요청합니다.
## Codex 명령
번들 Plugin은 `/codex`를 승인된 슬래시 명령으로 등록합니다. 이 명령은 일반적이며 OpenClaw 텍스트 명령을 지원하는 모든 채널에서 작동합니다.
번들 Plugin은 `/codex`를 승인된 슬래시 명령으로 등록합니다. 이 명령은
범용이며 OpenClaw 텍스트 명령을 지원하는 모든 채널에서 작동합니다.
일반 형식:
- `/codex status`는 실시간 app-server 연결성, 모델, 계정, 속도 제한, MCP 서버, Skills를 표시합니다.
- `/codex models`는 실시간 Codex app-server 모델을 나열합니다.
- `/codex status`는 실시간 앱 서버 연결성, 모델, 계정, 속도 제한, MCP 서버 및 Skills를 표시합니다.
- `/codex models`는 실시간 Codex 앱 서버 모델을 나열합니다.
- `/codex threads [filter]`는 최근 Codex 스레드를 나열합니다.
- `/codex resume <thread-id>`는 현재 OpenClaw 세션을 기존 Codex 스레드에 연결합니다.
- `/codex compact`는 Codex app-server에 연결된 스레드를 압축하도록 요청합니다.
- `/codex review`는 연결된 스레드에 대해 Codex 네이티브 검토를 시작합니다.
- `/codex diagnostics [note]`는 연결된 스레드에 대한 Codex 진단 피드백을 보내기 전에 확인을 요청합니다.
- `/codex compact`는 Codex 앱 서버에 연결된 스레드를 압축하도록 요청합니다.
- `/codex review`는 연결된 스레드에 대해 Codex 기본 검토를 시작합니다.
- `/codex diagnostics [note]`는 연결된 스레드의 Codex 진단 피드백을 보내기 전에 확인을 요청합니다.
- `/codex computer-use status`는 구성된 컴퓨터 사용 Plugin과 MCP 서버를 확인합니다.
- `/codex computer-use install`은 구성된 컴퓨터 사용 Plugin을 설치하고 MCP 서버를 다시 로드합니다.
- `/codex account`는 계정 및 속도 제한 상태를 표시합니다.
- `/codex mcp`는 Codex app-server MCP 서버 상태를 나열합니다.
- `/codex skills`는 Codex app-server Skills를 나열합니다.
- `/codex mcp`는 Codex 앱 서버 MCP 서버 상태를 나열합니다.
- `/codex skills`는 Codex 앱 서버 Skills를 나열합니다.
### 일반 디버깅 워크플로
Codex 기반 에이전트가 Telegram, Discord, Slack 또는 다른 채널에서 예상 밖의 동작을 하면, 문제가 발생한 대화에서 시작하세요:
Codex 기반 에이전트가 Telegram, Discord, Slack 또는 다른 채널에서 예상과
다른 일을 하면, 문제가 발생한 대화에서 시작하세요.
1. `/diagnostics bad tool choice after image upload` 또는 본 내용을 설명하는 다른 짧은 메모를 실행합니다.
2. 진단 요청을 한 번 승인합니다. 승인하면 로컬 Gateway 진단 zip이 생성되고, 세션이 Codex 하네스를 사용 중이므로 관련 Codex 피드백 번들도 OpenAI 서버로 전송됩니다.
3. 완료된 진단 응답을 버그 보고서나 지원 스레드에 복사합니다. 여기에는 로컬 번들 경로, 개인정보 요약, OpenClaw 세션 ID, Codex 스레드 ID, 각 Codex 스레드의 `Inspect locally` 줄이 포함됩니다.
4. 실행을 직접 디버깅하려면 출력된 `Inspect locally` 명령을 터미널에서 실행합니다. 이 명령은 `codex resume <thread-id>`처럼 보이며 네이티브 Codex 스레드를 열어 대화를 검사하고, 로컬에서 계속 진행하거나, Codex에 특정 도구나 계획을 선택한 이유를 물어볼 수 있게 합니다.
1. `/diagnostics bad tool choice after image upload`를 실행하거나, 본 내용을 설명하는 다른 짧은 메모를 실행합니다.
2. 진단 요청을 한 번 승인합니다. 승인은 로컬 Gateway 진단 zip을 생성하며, 세션이 Codex 하네스를 사용 중이므로 관련 Codex 피드백 번들도 OpenAI 서버로 보냅니다.
3. 완료된 진단 응답을 버그 보고서 또는 지원 스레드에 복사합니다. 여기에는 로컬 번들 경로, 개인정보 요약, OpenClaw 세션 ID, Codex 스레드 ID, 그리고 각 Codex 스레드의 `Inspect locally` 줄이 포함됩니다.
4. 실행을 직접 디버그하려면 출력된 `Inspect locally` 명령을 터미널에서 실행합니다. 이 명령은 `codex resume <thread-id>`와 같은 형태이며 기본 Codex 스레드를 열어 대화를 검사하거나, 로컬에서 계속 진행하거나, Codex가 특정 도구 또는 계획을 선택한 이유를 물어볼 수 있습니다.
전체 OpenClaw Gateway 진단 번들 없이 현재 연결된 스레드에 대한 Codex 피드백 업로드만 구체적으로 원할 때만 `/codex diagnostics [note]`를 사용하세요. 대부분의 지원 보고서에는 `/diagnostics [note]`가 더 나은 시작점입니다. 로컬 Gateway 상태와 Codex 스레드 ID를 하나의 응답으로 연결하기 때문입니다. 전체 개인정보 모델과 그룹 채팅 동작은 [진단 내보내기](/ko/gateway/diagnostics)를 참조하세요.
`/codex diagnostics [note]`는 전체 OpenClaw Gateway 진단 번들 없이 현재 연결된 스레드에 대한 Codex 피드백 업로드를 특별히 원할 때만 사용하세요. 대부분의 지원 보고서에서는 `/diagnostics [note]`가 더 나은 시작점입니다. 한 번의 응답에서 로컬 Gateway 상태와 Codex 스레드 ID를 함께 연결하기 때문입니다. 전체 개인정보 보호 모델과 그룹 채팅 동작은 [진단 내보내기](/ko/gateway/diagnostics)를 참조하세요.
Core OpenClaw는 일반 Gateway 진단 명령으로 소유자 전용 `/diagnostics [note]`도 노출합니다. 해당 승인 프롬프트는 민감 데이터 안내문을 표시하고, [진단 내보내기](/ko/gateway/diagnostics)에 연결하며, 매번 명시적 exec 승인을 통해 `openclaw gateway diagnostics export --json`을 요청합니다. allow-all 규칙으로 진단을 승인하지 마세요. 승인 후 OpenClaw는 로컬 번들 경로와 매니페스트 요약이 포함된 붙여넣기 가능한 보고서를 전송합니다. 활성 OpenClaw 세션이 Codex 하네스를 사용 중이면, 같은 승인으로 관련 Codex 피드백 번들을 OpenAI 서버로 보내는 것도 허가됩니다. 승인 프롬프트는 Codex 피드백이 전송될 것이라고 말하지만, 승인 전에는 Codex 세션 또는 스레드 ID를 나열하지 않습니다.
핵심 OpenClaw는 일반 Gateway 진단 명령으로 소유자 전용 `/diagnostics [note]`도 제공합니다. 승인 프롬프트에는 민감한 데이터 안내문이 표시되고, [진단 내보내기](/ko/gateway/diagnostics) 링크가 포함되며, 매번 명시적 실행 승인을 통해 `openclaw gateway diagnostics export --json`을 요청합니다. 모두 허용 규칙으로 진단을 승인하지 마세요. 승인 후 OpenClaw는 로컬 번들 경로와 매니페스트 요약이 포함된 붙여넣기 가능한 보고서를 보냅니다. 활성 OpenClaw 세션이 Codex 하네스를 사용 중이면, 같은 승인으로 관련 Codex 피드백 번들을 OpenAI 서버로 보내는 것도 승인됩니다. 승인 프롬프트에는 Codex 피드백이 전송된다고 표시되지만, 승인 전에는 Codex 세션 또는 스레드 ID를 나열하지 않습니다.
소유자가 그룹 채팅에서 `/diagnostics`를 호출하면 OpenClaw는 공유 채널을 깔끔하게 유지합니다. 그룹에는 짧은 알림만 전달되고, 진단 안내문, 승인 프롬프트, Codex 세션/스레드 ID는 비공개 승인 경로를 통해 소유자에게 전송됩니다. 비공개 소유자 경로가 없으면 OpenClaw는 그룹 요청을 거부하고 소유자에게 DM에서 실행하라고 요청합니다.
그룹 채팅에서 소유자가 `/diagnostics`를 호출하면 OpenClaw는 공유 채널을 깔끔하게 유지합니다. 그룹에는 짧은 알림만 표시되고, 진단 안내문, 승인 프롬프트, Codex 세션/스레드 ID는 비공개 승인 경로를 통해 소유자에게 전송됩니다. 비공개 소유자 경로가 없으면 OpenClaw는 그룹 요청을 거부하고 소유자에게 DM에서 실행하라고 요청합니다.
승인된 Codex 업로드는 Codex app-server `feedback/upload`를 호출하고, 사용 가능한 경우 나열된 각 스레드와 생성된 Codex 하위 스레드의 로그를 포함하도록 app-server에 요청합니다. 업로드는 Codex의 일반 피드백 경로를 통해 OpenAI 서버로 전달됩니다. 해당 app-server에서 Codex 피드백이 비활성화되어 있으면 명령은 app-server 오류를 반환합니다. 완료된 진단 응답에는 전송된 스레드의 채널, OpenClaw 세션 ID, Codex 스레드 ID, 로컬 `codex resume <thread-id>` 명령이 나열됩니다. 승인을 거부하거나 무시하면 OpenClaw는 해당 Codex ID를 출력하지 않습니다. 이 업로드는 로컬 Gateway 진단 내보내기를 대체하지 않습니다.
승인된 Codex 업로드는 Codex app-server `feedback/upload`를 호출하고, 가능한 경우 나열된 각 스레드와 생성된 Codex 하위 스레드의 로그를 포함하도록 app-server에 요청합니다. 업로드는 Codex의 일반 피드백 경로를 통해 OpenAI 서버로 전송됩니다. 해당 app-server에서 Codex 피드백이 비활성화되어 있으면 명령은 app-server 오류를 반환합니다. 완료된 진단 응답에는 전송된 스레드의 채널, OpenClaw 세션 ID, Codex 스레드 ID, 로컬 `codex resume <thread-id>` 명령이 나열됩니다. 승인을 거부하거나 무시하면 OpenClaw는 해당 Codex ID를 출력하지 않습니다. 이 업로드는 로컬 Gateway 진단 내보내기를 대체하지 않습니다.
`/codex resume`은 하네스가 일반 턴에 사용하는 것과 동일한 사이드카 바인딩 파일을 작성합니다. 다음 메시지에서 OpenClaw는 해당 Codex 스레드를 재개하고, 현재 선택된 OpenClaw 모델을 app-server에 전달하며, 확장 히스토리를 계속 활성화합니다.
`/codex resume`은 하네스가 일반 턴에 사용하는 것과 동일한 사이드카 바인딩 파일을 씁니다. 다음 메시지에서 OpenClaw는 해당 Codex 스레드를 재개하고, 현재 선택된 OpenClaw 모델을 app-server에 전달하며, 확장 기록을 계속 활성화합니다.
### CLI에서 Codex 스레드 검사
@ -685,104 +763,104 @@ Core OpenClaw는 일반 Gateway 진단 명령으로 소유자 전용 `/diagnosti
codex resume <thread-id>
```
채널 대화에서 버그를 발견했고 문제가 있는 Codex 세션을 검사하거나, 로컬에서 이어서 진행하거나, Codex가 특정 도구 또는 추론 선택을 한 이유를 물어보고 싶을 때 사용하세요. 가장 쉬운 경로는 보통 먼저 `/diagnostics [note]`를 실행하는 것입니다. 승인 후 완료된 보고서에는 각 Codex 스레드가 나열되고 `Inspect locally` 명령이 출력됩니다. 예: `codex resume <thread-id>`. 해당 명령을 터미널에 직접 복사할 수 있습니다.
채널 대화에서 버그를 발견했고 문제가 있는 Codex 세션을 검사하거나, 로컬에서 이어서 진행하거나, Codex가 특정 도구 또는 추론 선택을 한 이유를 묻고 싶을 때 이 명령을 사용하세요. 가장 쉬운 경로는 보통 먼저 `/diagnostics [note]`를 실행하는 것입니다. 승인 후 완료된 보고서에는 각 Codex 스레드가 나열되고 `Inspect locally` 명령이 출력됩니다. 예: `codex resume <thread-id>`. 해당 명령을 터미널에 바로 복사할 수 있습니다.
현재 채팅의 `/codex binding` 또는 최근 Codex app-server 스레드의 `/codex threads [filter]`에서 스레드 ID를 얻은 뒤, 셸에서 동일한 `codex resume` 명령을 실행할 수도 있습니다.
현재 채팅의 `/codex binding` 또는 최근 Codex app-server 스레드의 `/codex threads [filter]`에서도 스레드 ID를 얻은 다음, 셸에서 같은 `codex resume` 명령을 실행할 수 있습니다.
명령 표면에는 Codex app-server `0.125.0` 이상이 필요합니다. 향후 또는 커스텀 app-server가 해당 JSON-RPC 메서드를 노출하지 않으면 개별 제어 메서드는 `unsupported by this Codex app-server`로 보고됩니다.
명령 표면에는 Codex app-server `0.125.0` 이상이 필요합니다. 향후 또는 사용자 지정 app-server가 해당 JSON-RPC 메서드를 노출하지 않으면 개별 제어 메서드는 `unsupported by this Codex app-server`로 보고됩니다.
## 훅 경계
## 후크 경계
Codex 하네스에는 세 가지 훅 계층이 있습니다.
Codex 하네스에는 세 가지 후크 레이어가 있습니다.
| 계층 | 소유자 | 목적 |
| 레이어 | 소유자 | 목적 |
| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- |
| OpenClaw Plugin 훅 | OpenClaw | PI 및 Codex 하네스 전반의 제품/Plugin 호환성. |
| Codex app-server 확장 미들웨어 | OpenClaw 번들 Plugin | OpenClaw 동적 도구 주변의 턴별 어댑터 동작. |
| Codex 네이티브 훅 | Codex | Codex 구성의 저수준 Codex 수명 주기 및 네이티브 도구 정책. |
| OpenClaw Plugin 후크 | OpenClaw | PI 및 Codex 하네스 전반의 제품/Plugin 호환성. |
| Codex app-server 확장 미들웨어 | OpenClaw 번들 Plugin | OpenClaw 동적 도구 주변의 턴별 어댑터 동작. |
| Codex 네이티브 후크 | Codex | Codex 구성의 저수준 Codex 수명 주기 및 네이티브 도구 정책. |
OpenClaw는 OpenClaw Plugin 동작을 라우팅하기 위해 프로젝트 또는 전역 Codex `hooks.json` 파일을 사용하지 않습니다. 지원되는 네이티브 도구 및 권한 브리지의 경우 OpenClaw는 `PreToolUse`, `PostToolUse`, `PermissionRequest`, `Stop`에 대해 스레드별 Codex 구성을 주입합니다. `SessionStart` 및 `UserPromptSubmit` 같은 다른 Codex 훅은 Codex 수준 제어로 유지되며, v1 계약에서 OpenClaw Plugin 훅으로 노출되지 않습니다.
OpenClaw는 OpenClaw Plugin 동작을 라우팅하기 위해 프로젝트 또는 전역 Codex `hooks.json` 파일을 사용하지 않습니다. 지원되는 네이티브 도구 및 권한 브리지의 경우, OpenClaw는 `PreToolUse`, `PostToolUse`, `PermissionRequest`, `Stop`에 대해 스레드별 Codex 구성을 주입합니다. `SessionStart`, `UserPromptSubmit` 같은 다른 Codex 후크는 Codex 수준 제어로 남으며, v1 계약에서 OpenClaw Plugin 후크로 노출되지 않습니다.
OpenClaw 동적 도구의 경우 Codex가 호출을 요청한 뒤 OpenClaw가 도구를 실행하므로, OpenClaw는 하네스 어댑터에서 자신이 소유한 Plugin 및 미들웨어 동작을 실행합니다. Codex 네이티브 도구의 경우 Codex가 정식 도구 레코드를 소유합니다. OpenClaw는 선택한 이벤트를 미러링할 수 있지만, Codex가 app-server 또는 네이티브 훅 콜백을 통해 해당 작업을 노출하지 않는 한 네이티브 Codex 스레드를 다시 작성할 수 없습니다.
OpenClaw 동적 도구의 경우, Codex가 호출을 요청한 뒤 OpenClaw가 도구를 실행하므로 OpenClaw는 하네스 어댑터에서 자신이 소유한 Plugin 및 미들웨어 동작을 실행합니다. Codex 네이티브 도구의 경우, Codex가 표준 도구 레코드를 소유합니다. OpenClaw는 선택된 이벤트를 미러링할 수 있지만, Codex가 app-server 또는 네이티브 후크 콜백을 통해 해당 작업을 노출하지 않는 한 네이티브 Codex 스레드를 다시 쓸 수 없습니다.
Compaction 및 LLM 수명 주기 투영은 네이티브 Codex 훅 명령이 아니라 Codex app-server 알림과 OpenClaw 어댑터 상태에서 옵니다. OpenClaw의 `before_compaction`, `after_compaction`, `llm_input`, `llm_output` 이벤트는 Codex 내부 요청 또는 Compaction 페이로드를 바이트 단위로 캡처한 것이 아니라 어댑터 수준 관찰입니다.
Compaction 및 LLM 수명 주기 프로젝션은 네이티브 Codex 후크 명령이 아니라 Codex app-server 알림과 OpenClaw 어댑터 상태에서 나옵니다. OpenClaw의 `before_compaction`, `after_compaction`, `llm_input`, `llm_output` 이벤트는 어댑터 수준 관찰이며, Codex의 내부 요청 또는 Compaction 페이로드를 바이트 단위로 캡처한 것이 아닙니다.
Codex 네이티브 `hook/started` 및 `hook/completed` app-server 알림은 궤적 및 디버깅을 위해 `codex_app_server.hook` 에이전트 이벤트로 투영됩니다. 이 알림은 OpenClaw Plugin 훅을 호출하지 않습니다.
Codex 네이티브 `hook/started` 및 `hook/completed` app-server 알림은 궤적 및 디버깅을 위한 `codex_app_server.hook` 에이전트 이벤트로 프로젝션됩니다. 이 알림들은 OpenClaw Plugin 후크를 호출하지 않습니다.
## V1 지원 계약
Codex 모드는 내부의 모델 호출만 다른 PI가 아닙니다. Codex는 네이티브 모델 루프의 더 많은 부분을 소유하며, OpenClaw는 그 경계에 맞춰 Plugin 및 세션 표면을 조정합니다.
Codex 모드는 내부에서 다른 모델 호출을 사용하는 PI가 아닙니다. Codex는 네이티브 모델 루프의 더 많은 부분을 소유하며, OpenClaw는 해당 경계에 맞춰 Plugin 및 세션 표면을 조정합니다.
Codex 런타임 v1에서 지원됨:
| 표면 | 지원 | 이유 |
| --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Codex를 통한 OpenAI 모델 루프 | 지원됨 | Codex app-server가 OpenAI 턴, 네이티브 스레드 재개, 네이티브 도구 계속 진행을 소유합니다. |
| OpenClaw 채널 라우팅 및 전달 | 지원됨 | Telegram, Discord, Slack, WhatsApp, iMessage 및 기타 채널은 모델 런타임 외부에 유지됩니다. |
| OpenClaw 동적 도구 | 지원됨 | Codex가 OpenClaw에 이러한 도구 실행을 요청하므로 OpenClaw는 실행 경로에 남아 있습니다. |
| 프롬프트 및 컨텍스트 Plugin | 지원됨 | OpenClaw는 스레드를 시작하거나 재개하기 전에 프롬프트 오버레이를 빌드하고 컨텍스트를 Codex 턴에 투영합니다. |
| 컨텍스트 엔진 수명 주기 | 지원됨 | 조립, 수집 또는 턴 이후 유지 관리, 컨텍스트 엔진 Compaction 조정이 Codex 턴에 대해 실행됩니다. |
| 동적 도구 훅 | 지원됨 | `before_tool_call`, `after_tool_call`, 도구 결과 미들웨어가 OpenClaw 소유 동적 도구 주변에서 실행됩니다. |
| 수명 주기 훅 | 어댑터 관찰로 지원됨 | `llm_input`, `llm_output`, `agent_end`, `before_compaction`, `after_compaction`이 정직한 Codex 모드 페이로드와 함께 실행됩니다. |
| 최종 답변 수정 게이트 | 네이티브 훅 릴레이를 통해 지원됨 | Codex `Stop`이 `before_agent_finalize`로 릴레이되고, `revise`는 최종화 전에 Codex에 모델 패스를 한 번 더 요청합니다. |
| 네이티브 셸, 패치, MCP 차단 또는 관찰 | 네이티브 훅 릴레이를 통해 지원됨 | Codex `PreToolUse` 및 `PostToolUse`가 Codex app-server `0.125.0` 이상에서 MCP 페이로드를 포함한 커밋된 네이티브 도구 표면에 대해 릴레이됩니다. 차단은 지원되지만 인수 다시 작성은 지원되지 않습니다. |
| 네이티브 권한 정책 | 네이티브 훅 릴레이를 통해 지원됨 | 런타임이 노출하는 경우 Codex `PermissionRequest`를 OpenClaw 정책을 통해 라우팅할 수 있습니다. OpenClaw가 결정을 반환하지 않으면 Codex는 일반 guardian 또는 사용자 승인 경로를 계속 진행합니다. |
| App-server 궤적 캡처 | 지원됨 | OpenClaw는 app-server에 보낸 요청과 수신한 app-server 알림을 기록합니다. |
| Codex를 통한 OpenAI 모델 루프 | 지원됨 | Codex app-server가 OpenAI 턴, 네이티브 스레드 재개, 네이티브 도구 이어가기를 소유합니다. |
| OpenClaw 채널 라우팅 및 전달 | 지원됨 | Telegram, Discord, Slack, WhatsApp, iMessage 및 기타 채널은 모델 런타임 외부에 남습니다. |
| OpenClaw 동적 도구 | 지원됨 | Codex가 OpenClaw에 이러한 도구 실행을 요청하므로 OpenClaw는 실행 경로에 남습니다. |
| 프롬프트 및 컨텍스트 Plugin | 지원됨 | OpenClaw는 스레드를 시작하거나 재개하기 전에 프롬프트 오버레이를 구성하고 컨텍스트를 Codex 턴에 프로젝션합니다. |
| 컨텍스트 엔진 수명 주기 | 지원됨 | 조립, 수집 또는 턴 이후 유지 관리, 컨텍스트 엔진 Compaction 조정이 Codex 턴에서 실행됩니다. |
| 동적 도구 후크 | 지원됨 | `before_tool_call`, `after_tool_call`, 도구 결과 미들웨어가 OpenClaw 소유 동적 도구 주변에서 실행됩니다. |
| 수명 주기 후크 | 어댑터 관찰로 지원됨 | `llm_input`, `llm_output`, `agent_end`, `before_compaction`, `after_compaction`이 정직한 Codex 모드 페이로드와 함께 실행됩니다. |
| 최종 답변 수정 게이트 | 네이티브 후크 릴레이를 통해 지원됨 | Codex `Stop`이 `before_agent_finalize`로 릴레이되고, `revise`는 최종화 전에 Codex에 모델 패스를 한 번 더 요청합니다. |
| 네이티브 셸, 패치, MCP 차단 또는 관찰 | 네이티브 후크 릴레이를 통해 지원됨 | Codex `PreToolUse` 및 `PostToolUse`가 Codex app-server `0.125.0` 이상에서 MCP 페이로드를 포함해 커밋된 네이티브 도구 표면에 대해 릴레이됩니다. 차단은 지원되지만 인수 재작성은 지원되지 않습니다. |
| 네이티브 권한 정책 | 네이티브 후크 릴레이를 통해 지원됨 | 런타임이 노출하는 경우 Codex `PermissionRequest`를 OpenClaw 정책을 통해 라우팅할 수 있습니다. OpenClaw가 결정을 반환하지 않으면 Codex는 일반 guardian 또는 사용자 승인 경로를 통해 계속 진행합니다. |
| app-server 궤적 캡처 | 지원됨 | OpenClaw는 app-server에 보낸 요청과 app-server에서 받은 알림을 기록합니다. |
Codex 런타임 v1에서 지원되지 않음:
| 표면 | V1 경계 | 향후 경로 |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| 네이티브 도구 인수 변경 | Codex 네이티브 사전 도구 훅은 차단할 수 있지만, OpenClaw는 Codex 네이티브 도구 인수를 다시 작성하지 않습니다. | 대체 도구 입력에 대한 Codex 훅/스키마 지원이 필요합니다. |
| 편집 가능한 Codex 네이티브 transcript 히스토리 | Codex는 정식 네이티브 스레드 히스토리를 소유합니다. OpenClaw는 미러를 소유하고 향후 컨텍스트를 투영할 수 있지만, 지원되지 않는 내부를 변경해서는 안 됩니다. | 네이티브 스레드 수술이 필요하면 명시적인 Codex app-server API를 추가합니다. |
| Codex 네이티브 도구 레코드의 `tool_result_persist` | 해당 훅은 Codex 네이티브 도구 레코드가 아니라 OpenClaw 소유 transcript 쓰기를 변환합니다. | 변환된 레코드를 미러링할 수는 있지만, 정식 다시 작성에는 Codex 지원이 필요합니다. |
| 풍부한 네이티브 Compaction 메타데이터 | OpenClaw는 Compaction 시작과 완료를 관찰하지만, 안정적인 유지/삭제 목록, 토큰 델타 또는 요약 페이로드를 받지 않습니다. | 더 풍부한 Codex Compaction 이벤트가 필요합니다. |
| Compaction 개입 | 현재 OpenClaw Compaction 훅은 Codex 모드에서 알림 수준입니다. | Plugin이 네이티브 Compaction을 거부하거나 다시 작성해야 하는 경우 Codex 사전/사후 Compaction 훅을 추가합니다. |
| 바이트 단위 모델 API 요청 캡처 | OpenClaw는 app-server 요청과 알림을 캡처할 수 있지만, Codex 코어가 최종 OpenAI API 요청을 내부적으로 빌드합니다. | Codex 모델 요청 추적 이벤트 또는 디버그 API가 필요합니다. |
| 영역 | V1 경계 | 향후 경로 |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| 네이티브 도구 인수 변경 | Codex 네이티브 사전 도구 훅은 차단할 수 있지만, OpenClaw는 Codex 네이티브 도구 인수를 다시 작성하지 않습니다. | 대체 도구 입력을 위한 Codex 훅/스키마 지원이 필요합니다. |
| 편집 가능한 Codex 네이티브 transcript 기록 | Codex는 정식 네이티브 스레드 기록을 소유합니다. OpenClaw는 미러를 소유하고 향후 컨텍스트를 투영할 수 있지만, 지원되지 않는 내부 구조를 변경해서는 안 됩니다. | 네이티브 스레드 수술이 필요한 경우 명시적인 Codex 앱 서버 API를 추가합니다. |
| Codex 네이티브 도구 레코드용 `tool_result_persist` | 해당 훅은 OpenClaw가 소유한 transcript 쓰기를 변환하며, Codex 네이티브 도구 레코드는 변환하지 않습니다. | 변환된 레코드를 미러링할 수는 있지만, 정식 재작성에는 Codex 지원이 필요합니다. |
| 풍부한 네이티브 Compaction 메타데이터 | OpenClaw는 Compaction 시작과 완료를 관찰하지만, 안정적인 유지/삭제 목록, 토큰 델타 또는 요약 페이로드를 받지 않습니다. | 더 풍부한 Codex Compaction 이벤트가 필요합니다. |
| Compaction 개입 | 현재 OpenClaw Compaction 훅은 Codex 모드에서 알림 수준입니다. | Plugin이 네이티브 Compaction을 거부하거나 다시 작성해야 하는 경우 Codex 사전/사후 Compaction 훅을 추가합니다. |
| 바이트 단위로 동일한 모델 API 요청 캡처 | OpenClaw는 앱 서버 요청과 알림을 캡처할 수 있지만, Codex 코어가 최종 OpenAI API 요청을 내부적으로 빌드합니다. | Codex 모델 요청 추적 이벤트 또는 디버그 API가 필요합니다. |
## 도구, 미디어 및 Compaction
Codex 하네스는 저수준 임베디드 에이전트 실행기만 변경합니다.
Codex 하니스는 저수준 임베디드 에이전트 실행기만 변경합니다.
OpenClaw는 여전히 도구 목록을 빌드하고 하네스에서 동적 도구 결과를 받습니다. 텍스트, 이미지, 비디오, 음악, TTS, 승인, 메시징 도구 출력은 일반 OpenClaw 전달 경로를 계속 사용합니다.
OpenClaw는 계속 도구 목록을 빌드하고 하니스에서 동적 도구 결과를 받습니다. 텍스트, 이미지, 비디오, 음악, TTS, 승인 및 메시징 도구 출력은 계속 일반 OpenClaw 전달 경로를 통과합니다.
네이티브 훅 릴레이는 의도적으로 일반적이지만, v1 지원 계약은 OpenClaw가 테스트하는 Codex 네이티브 도구 및 권한 경로로 제한됩니다. Codex 런타임에서 여기에는 셸, 패치, MCP `PreToolUse`, `PostToolUse`, `PermissionRequest` 페이로드가 포함됩니다. 런타임 계약이 명명하기 전에는 향후 모든 Codex 훅 이벤트가 OpenClaw Plugin 표면이라고 가정하지 마세요.
네이티브 훅 릴레이는 의도적으로 범용적이지만, v1 지원 계약은 OpenClaw가 테스트하는 Codex 네이티브 도구 및 권한 경로로 제한됩니다. Codex 런타임에서 여기에는 셸, 패치 및 MCP `PreToolUse`, `PostToolUse`, `PermissionRequest` 페이로드가 포함됩니다. 런타임 계약이 이름을 지정하기 전까지는 모든 향후 Codex 훅 이벤트가 OpenClaw Plugin 표면이라고 가정하지 마세요.
`PermissionRequest`의 경우 OpenClaw는 정책이 결정할 때만 명시적인 허용 또는 거부 결정을 반환합니다. 결정 없음 결과는 허용이 아닙니다. Codex는 이를 훅 결정 없음으로 처리하고 자체 guardian 또는 사용자 승인 경로로 넘어갑니다.
`PermissionRequest`의 경우, OpenClaw는 정책이 결정할 때만 명시적인 허용 또는 거부 결정을 반환합니다. 결정 없음 결과는 허용이 아닙니다. Codex는 이를 훅 결정 없음으로 처리하고 자체 보호자 또는 사용자 승인 경로로 넘어갑니다.
Codex MCP 도구 승인 요청은 Codex가 `_meta.codex_approval_kind`를 `"mcp_tool_call"`로 표시할 때 OpenClaw의 Plugin 승인 흐름을 통해 라우팅됩니다. Codex `request_user_input` 프롬프트는 원래 채팅으로 다시 전송되며, 다음 대기 중인 후속 메시지는 추가 컨텍스트로 유도되는 대신 해당 네이티브 서버 요청에 답합니다. 다른 MCP 요청은 여전히 닫힌 상태로 실패합니다.
Codex MCP 도구 승인 유도는 Codex가 `_meta.codex_approval_kind`를 `"mcp_tool_call"`로 표시할 때 OpenClaw의 Plugin 승인 플로를 통해 라우팅됩니다. Codex `request_user_input` 프롬프트는 원래 채팅으로 다시 전송되며, 다음 대기 중인 후속 메시지는 추가 컨텍스트로 조향되는 대신 해당 네이티브 서버 요청에 응답합니다. 다른 MCP 유도 요청은 여전히 안전하게 실패합니다.
활성 실행 큐 조정은 Codex 앱 서버 `turn/steer`에 매핑됩니다. 기본값인 `messages.queue.mode: "steer"`에서는 OpenClaw가 구성된 대기 시간 동안 큐에 들어온 채팅 메시지를 묶고, 도착 순서대로 하나의 `turn/steer` 요청으로 보냅니다. 레거시 `queue` 모드는 별도의 `turn/steer` 요청을 보냅니다. Codex 리뷰와 수동 Compaction 턴은 같은 턴 조정을 거부할 수 있으며, 이 경우 선택한 모드가 폴백을 허용하면 OpenClaw는 후속 큐를 사용합니다. [조정 큐](/ko/concepts/queue-steering)를 참조하세요.
활성 실행 큐 조향은 Codex 앱 서버 `turn/steer`에 매핑됩니다. 기본 `messages.queue.mode: "steer"`를 사용하면 OpenClaw는 구성된 조용한 창 동안 대기 중인 채팅 메시지를 배치로 묶고 도착 순서대로 하나의 `turn/steer` 요청으로 보냅니다. 레거시 `queue` 모드는 별도의 `turn/steer` 요청을 보냅니다. Codex 검토와 수동 Compaction 턴은 같은 턴 조향을 거부할 수 있으며, 이 경우 선택된 모드가 폴백을 허용하면 OpenClaw는 followup 큐를 사용합니다. [조향 큐](/ko/concepts/queue-steering)를 참조하세요.
선택한 모델이 Codex 하네스를 사용할 때 네이티브 스레드 Compaction은 Codex 앱 서버에 위임됩니다. OpenClaw는 채널 기록, 검색, `/new`, `/reset`, 그리고 향후 모델 또는 하네스 전환을 위해 transcript 미러를 유지합니다. 미러에는 사용자 프롬프트, 최종 어시스턴트 텍스트, 그리고 앱 서버가 내보내는 경우 가벼운 Codex 추론 또는 계획 레코드가 포함됩니다. 현재 OpenClaw는 네이티브 Compaction 시작 및 완료 신호만 기록합니다. 아직 사람이 읽을 수 있는 Compaction 요약이나 Compaction 후 Codex가 어떤 항목을 유지했는지에 대한 감사 가능한 목록은 노출하지 않습니다.
선택한 모델이 Codex 하니스를 사용하는 경우, 네이티브 스레드 Compaction은 Codex 앱 서버에 위임됩니다. OpenClaw는 채널 기록, 검색, `/new`, `/reset`, 향후 모델 또는 하니스 전환을 위해 transcript 미러를 유지합니다. 미러에는 사용자 프롬프트, 최종 어시스턴트 텍스트, 그리고 앱 서버가 내보낼 때 가벼운 Codex 추론 또는 계획 레코드가 포함됩니다. 현재 OpenClaw는 네이티브 Compaction 시작 및 완료 신호만 기록합니다. 아직 사람이 읽을 수 있는 Compaction 요약이나 Compaction 후 Codex가 유지한 항목의 감사 가능한 목록을 노출하지 않습니다.
Codex가 표준 네이티브 스레드를 소유하므로 `tool_result_persist`는 현재 Codex 네이티브 도구 결과 레코드를 다시 작성하지 않습니다. OpenClaw가 OpenClaw 소유 세션 transcript 도구 결과를 작성할 때만 적용됩니다.
Codex가 정식 네이티브 스레드를 소유하므로, `tool_result_persist`는 현재 Codex 네이티브 도구 결과 레코드를 다시 작성하지 않습니다. OpenClaw가 OpenClaw 소유 세션 transcript 도구 결과를 쓰는 경우에만 적용됩니다.
미디어 생성에는 PI가 필요하지 않습니다. 이미지, 동영상, 음악, PDF, TTS, 미디어 이해는 계속해서 `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel`, `messages.tts` 같은 해당 provider/model 설정을 사용합니다.
미디어 생성에는 PI가 필요하지 않습니다. 이미지, 비디오, 음악, PDF, TTS 및 미디어 이해는 `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel`, `messages.tts` 같은 일치하는 공급자/모델 설정을 계속 사용합니다.
## 문제 해결
**Codex가 일반 `/model` provider로 표시되지 않음:** 새 구성에서는 예상된 동작입니다. `agentRuntime.id: "codex"`가 있는 `openai/gpt-*` 모델(또는 레거시 `codex/*` 참조)을 선택하고, `plugins.entries.codex.enabled`를 활성화한 다음, `plugins.allow`가 `codex`를 제외하는지 확인하세요.
**Codex가 일반 `/model` 공급자로 표시되지 않습니다:** 새 구성에서는 예상된 동작입니다. `agentRuntime.id: "codex"`가 있는 `openai/gpt-*` 모델(또는 레거시 `codex/*` 참조)을 선택하고, `plugins.entries.codex.enabled`를 활성화한 다음, `plugins.allow`가 `codex`를 제외하는지 확인하세요.
**OpenClaw가 Codex 대신 PI를 사용함:** `agentRuntime.id: "auto"`는 Codex 하네스가 실행을 가져가지 않을 때 호환성 백엔드로 여전히 PI를 사용할 수 있습니다. 테스트 중 Codex 선택을 강제하려면 `agentRuntime.id: "codex"`를 설정하세요. 강제된 Codex 런타임은 이제 `agentRuntime.fallback: "pi"`를 명시적으로 설정하지 않는 한 PI로 폴백하지 않고 실패합니다. Codex 앱 서버가 선택되면, 해당 실패는 추가 폴백 구성 없이 직접 표면화됩니다.
**OpenClaw가 Codex 대신 PI를 사용합니다:** `agentRuntime.id: "auto"`는 실행을 차지하는 Codex 하니스가 없을 때 여전히 PI를 호환성 백엔드로 사용할 수 있습니다. 테스트 중 Codex 선택을 강제하려면 `agentRuntime.id: "codex"`를 설정하세요. 강제된 Codex 런타임은 이제 `agentRuntime.fallback: "pi"`를 명시적으로 설정하지 않는 한 PI로 폴백하지 않고 실패합니다. Codex 앱 서버가 선택되면, 추가 폴백 구성 없이 해당 실패가 직접 표시됩니다.
**앱 서버가 거부됨:** 앱 서버 핸드셰이크가 버전 `0.125.0` 이상을 보고하도록 Codex를 업그레이드하세요. `0.125.0-alpha.2` 또는 `0.125.0+custom` 같은 동일 버전의 시험판이나 빌드 접미사가 붙은 버전은 거부됩니다. OpenClaw가 테스트하는 기준은 안정 버전 `0.125.0` 프로토콜 하한이기 때문입니다.
**앱 서버가 거부됩니다:** 앱 서버 핸드셰이크가 버전 `0.125.0` 이상을 보고하도록 Codex를 업그레이드하세요. `0.125.0-alpha.2` 또는 `0.125.0+custom` 같은 동일 버전 프리릴리스 또는 빌드 접미사 버전은 거부됩니다. OpenClaw가 테스트하는 기준이 안정 `0.125.0` 프로토콜 하한이기 때문입니다.
**모델 검색이 느림:** `plugins.entries.codex.config.discovery.timeoutMs`를 낮추거나 검색을 비활성화하세요.
**모델 검색이 느립니다:** `plugins.entries.codex.config.discovery.timeoutMs`를 낮추거나 검색을 비활성화하세요.
**WebSocket 전송이 즉시 실패함:** `appServer.url`, `authToken`, 그리고 원격 앱 서버가 같은 Codex 앱 서버 프로토콜 버전을 사용하는지 확인하세요.
**WebSocket 전송이 즉시 실패합니다:** `appServer.url`, `authToken`, 그리고 원격 앱 서버가 동일한 Codex 앱 서버 프로토콜 버전을 사용하는지 확인하세요.
**Codex가 아닌 모델이 PI를 사용함:** 해당 에이전트에 대해 `agentRuntime.id: "codex"`를 강제했거나 레거시 `codex/*` 참조를 선택한 경우가 아니라면 예상된 동작입니다. 일반 `openai/gpt-*` 및 다른 provider 참조는 `auto` 모드에서 정상 provider 경로를 유지합니다. `agentRuntime.id: "codex"`를 강제하면 해당 에이전트의 모든 내장 턴은 Codex가 지원하는 OpenAI 모델이어야 합니다.
**Codex가 아닌 모델이 PI를 사용합니다:** 해당 에이전트에 대해 `agentRuntime.id: "codex"`를 강제했거나 레거시 `codex/*` 참조를 선택한 경우가 아니라면 예상된 동작입니다. 일반 `openai/gpt-*` 및 다른 공급자 참조는 `auto` 모드에서 정상 공급자 경로를 유지합니다. `agentRuntime.id: "codex"`를 강제하면 해당 에이전트의 모든 임베디드 턴은 Codex가 지원하는 OpenAI 모델이어야 합니다.
**Computer Use가 설치되어 있지만 도구가 실행되지 않음:** 새 세션에서 `/codex computer-use status`를 확인하세요. 도구가 `Native hook relay unavailable`을 보고하면 `/new` 또는 `/reset`을 사용하세요. 계속되면 오래된 네이티브 후크 등록을 지우기 위해 Gateway를 다시 시작하세요. `computer-use.list_apps`가 시간 초과되면 Codex Computer Use 또는 Codex Desktop을 다시 시작하고 재시도하세요.
**Computer Use가 설치되어 있지만 도구가 실행되지 않습니다:** 새 세션에서 `/codex computer-use status`를 확인하세요. 도구가 `Native hook relay unavailable`을 보고하면 `/new` 또는 `/reset`을 사용하세요. 계속되면 Gateway를 재시작해 오래된 네이티브 훅 등록을 지우세요. `computer-use.list_apps`가 시간 초과되면 Codex Computer Use 또는 Codex Desktop을 재시작하고 다시 시도하세요.
## 관련 항목
- [에이전트 하네스 Plugin](/ko/plugins/sdk-agent-harness)
- [에이전트 하니스 Plugin](/ko/plugins/sdk-agent-harness)
- [에이전트 런타임](/ko/concepts/agent-runtimes)
- [모델 provider](/ko/concepts/model-providers)
- [OpenAI provider](/ko/providers/openai)
- [모델 공급자](/ko/concepts/model-providers)
- [OpenAI 공급자](/ko/providers/openai)
- [상태](/ko/cli/status)
- [Plugin 후크](/ko/plugins/hooks)
- [Plugin 훅](/ko/plugins/hooks)
- [구성 참조](/ko/gateway/configuration-reference)
- [테스트](/ko/help/testing-live#live-codex-app-server-harness-smoke)

313
docs/ko/tools/skills.md
View File

@ -1,61 +1,56 @@
---
read_when:
- Skills 추가 또는 수정
- Skills 게이팅, 허용 목록 또는 로드 규칙 변경
- 스킬 우선순위와 스냅샷 동작 이해하기
- 스킬 게이팅, 허용 목록 또는 로드 규칙 변경
- Skills 우선순위와 스냅샷 동작 이해
sidebarTitle: Skills
summary: 'Skills: 관리형 대 워크스페이스, 게이팅 규칙, 에이전트 허용 목록 및 설정 연결'
summary: 'Skills: 관리형 vs 작업공간, 게이팅 규칙, 에이전트 허용 목록 및 설정 연결'
title: Skills
x-i18n:
generated_at: "2026-04-30T09:34:59Z"
generated_at: "2026-04-30T20:05:37Z"
model: gpt-5.5
provider: openai
source_hash: d7dd17f52119bf0a0bb197025070abb68f7667a7d22c3d5fa6ef2f666110a45a
source_hash: b58d690786756bd3539940aae9f2abcb8a497798ed7b6afeb5e6d6e255fcf257
source_path: tools/skills.md
workflow: 16
---
OpenClaw는 에이전트에게 도구 사용법을 가르치기 위해 **[AgentSkills](https://agentskills.io)-호환** skill
폴더를 사용합니다. 각 skill은 YAML frontmatter와 지침이 포함된 `SKILL.md`를
담은 디렉터리입니다. OpenClaw는 번들 skill과 선택적 로컬 재정의를 로드하며,
로드 시점에 환경, config, 바이너리 존재 여부를 기준으로 이를 필터링합니다.
OpenClaw는 에이전트에게 도구 사용법을 가르치기 위해 **[AgentSkills](https://agentskills.io) 호환** 스킬 폴더를 사용합니다. 각 스킬은 YAML frontmatter와 지침이 포함된 `SKILL.md`를 담은 디렉터리입니다. OpenClaw는 번들 스킬과 선택적 로컬 재정의를 로드하고, 환경, 구성, 바이너리 존재 여부를 기준으로 로드 시점에 필터링합니다.
## 위치와 우선순위
OpenClaw는 다음 소스에서 skill을 로드하며, **가장 높은 우선순위가 먼저**입니다.
OpenClaw는 다음 소스에서 스킬을 로드하며, **우선순위가 높은 순서**입니다.
| # | 소스 | 경로 |
| --- | --------------------- | -------------------------------- |
| 1 | Workspace skill | `<workspace>/skills` |
| 2 | Project agent skill | `<workspace>/.agents/skills` |
| 3 | Personal agent skill | `~/.agents/skills` |
| 4 | Managed/local skill | `~/.openclaw/skills` |
| 5 | 번들 skill | 설치와 함께 제공됨 |
| 6 | 추가 skill 폴더 | `skills.load.extraDirs` (config) |
| 1 | 워크스페이스 스킬 | `<workspace>/skills` |
| 2 | 프로젝트 에이전트 스킬 | `<workspace>/.agents/skills` |
| 3 | 개인 에이전트 스킬 | `~/.agents/skills` |
| 4 | 관리형/로컬 스킬 | `~/.openclaw/skills` |
| 5 | 번들 스킬 | 설치와 함께 제공됨 |
| 6 | 추가 스킬 폴더 | `skills.load.extraDirs` (구성) |
skill 이름이 충돌하면 가장 높은 소스가 우선합니다.
스킬 이름이 충돌하면 가장 높은 소스가 우선합니다.
## 에이전트별 skill과 공유 skill
Codex CLI의 기본 `$CODEX_HOME/skills` 디렉터리는 이러한 OpenClaw 스킬 루트 중 하나가 아닙니다. Codex 하네스 모드에서는 로컬 앱 서버 실행이 에이전트별로 격리된 Codex 홈을 사용하므로, 개인 Codex CLI 스킬은 암시적으로 로드되지 않습니다. 해당 스킬을 목록화하려면 `openclaw migrate codex --dry-run`을 사용하고, 현재 OpenClaw 에이전트 워크스페이스로 복사하기 전에 대화형 체크박스 프롬프트로 스킬 디렉터리를 선택하려면 `openclaw migrate codex`를 사용하세요. 비대화형 실행의 경우 복사할 정확한 스킬마다 `--skill <name>`을 반복해서 지정하세요.
**multi-agent** 설정에서는 각 에이전트가 자체 workspace를 가집니다.
## 에이전트별 스킬과 공유 스킬
**다중 에이전트** 구성에서는 각 에이전트가 자체 워크스페이스를 가집니다.
| 범위 | 경로 | 표시 대상 |
| -------------------- | ------------------------------------------- | ---------------------------- |
| 에이전트별 | `<workspace>/skills` | 해당 에이전트만 |
| Project-agent | `<workspace>/.agents/skills` | 해당 workspace의 에이전트만 |
| Personal-agent | `~/.agents/skills` | 해당 머신의 모든 에이전트 |
| 공유 managed/local | `~/.openclaw/skills` | 해당 머신의 모든 에이전트 |
| 공유 extra dirs | `skills.load.extraDirs` (가장 낮은 우선순위) | 해당 머신의 모든 에이전트 |
| 프로젝트 에이전트 | `<workspace>/.agents/skills` | 해당 워크스페이스의 에이전트만 |
| 개인 에이전트 | `~/.agents/skills` | 해당 머신의 모든 에이전트 |
| 공유 관리형/로컬 | `~/.openclaw/skills` | 해당 머신의 모든 에이전트 |
| 공유 추가 디렉터리 | `skills.load.extraDirs` (가장 낮은 우선순위) | 해당 머신의 모든 에이전트 |
여러 위치에 같은 이름이 있으면 → 가장 높은 소스가 우선합니다. Workspace는
project-agent보다, project-agent는 personal-agent보다, personal-agent는 managed/local보다,
managed/local은 번들보다, 번들은 extra dirs보다 우선합니다.
여러 위치에 같은 이름이 있으면 → 가장 높은 소스가 우선합니다. 워크스페이스가 프로젝트 에이전트보다, 프로젝트 에이전트가 개인 에이전트보다, 개인 에이전트가 관리형/로컬보다, 관리형/로컬이 번들보다, 번들이 추가 디렉터리보다 우선합니다.
## 에이전트 skill 허용 목록
## 에이전트 스킬 허용 목록
skill **위치**와 skill **가시성**은 별도의 제어입니다.
위치/우선순위는 같은 이름의 skill 중 어떤 복사본이 우선할지 결정하고,
에이전트 허용 목록은 에이전트가 실제로 사용할 수 있는 skill을 결정합니다.
스킬 **위치**와 스킬 **가시성**은 별도의 제어입니다. 위치/우선순위는 같은 이름의 스킬 중 어느 사본이 우선하는지 결정하고, 에이전트 허용 목록은 에이전트가 실제로 사용할 수 있는 스킬을 결정합니다.
```json5
{
@ -74,89 +69,57 @@ skill **위치**와 skill **가시성**은 별도의 제어입니다.
<AccordionGroup>
<Accordion title="허용 목록 규칙">
- 기본적으로 제한 없는 skill을 사용하려면 `agents.defaults.skills`를 생략합니다.
- `agents.defaults.skills`를 상속하려면 `agents.list[].skills`를 생략합니다.
- skill을 사용하지 않으려면 `agents.list[].skills: []`로 설정합니다.
- 비어 있지 않은 `agents.list[].skills` 목록은 해당 에이전트의 **최종** 집합입니다.
기본값과 병합되지 않습니다.
- 유효 허용 목록은 프롬프트 빌드, skill slash-command 검색, sandbox 동기화,
skill 스냅샷 전반에 적용됩니다.
- 기본적으로 제한 없는 스킬을 사용하려면 `agents.defaults.skills`를 생략하세요.
- `agents.defaults.skills`를 상속하려면 `agents.list[].skills`를 생략하세요.
- 스킬을 사용하지 않으려면 `agents.list[].skills: []`를 설정하세요.
- 비어 있지 않은 `agents.list[].skills` 목록은 해당 에이전트의 **최종** 집합입니다. 기본값과 병합되지 않습니다.
- 유효 허용 목록은 프롬프트 빌드, 스킬 슬래시 명령 검색, 샌드박스 동기화, 스킬 스냅샷 전반에 적용됩니다.
</Accordion>
</AccordionGroup>
## Plugin과 skill
## Plugin 및 스킬
Plugin은 `openclaw.plugin.json`에 `skills` 디렉터리를 나열하여 자체 skill을
제공할 수 있습니다(경로는 Plugin 루트 기준 상대 경로). Plugin skill은
Plugin이 활성화될 때 로드됩니다. 이는 도구 설명에 넣기에는 너무 길지만
Plugin이 설치되어 있을 때마다 사용할 수 있어야 하는 도구별 운영 가이드를
두기에 적절한 위치입니다. 예를 들어 브라우저 Plugin은 다단계 브라우저
제어를 위한 `browser-automation` skill을 제공합니다.
Plugin은 `openclaw.plugin.json`에 `skills` 디렉터리를 나열하여 자체 스킬을 함께 제공할 수 있습니다(경로는 Plugin 루트 기준 상대 경로). Plugin 스킬은 Plugin이 활성화될 때 로드됩니다. 도구 설명에 넣기에는 너무 길지만 Plugin이 설치되어 있을 때 항상 사용할 수 있어야 하는 도구별 운영 가이드는 여기에 두는 것이 적합합니다. 예를 들어 브라우저 Plugin은 다단계 브라우저 제어를 위한 `browser-automation` 스킬을 제공합니다.
Plugin skill 디렉터리는 `skills.load.extraDirs`와 동일한 낮은 우선순위 경로에
병합되므로, 같은 이름의 번들, managed, agent, workspace skill이 이를 재정의합니다.
Plugin의 config 항목에서 `metadata.openclaw.requires.config`를 통해 이를 제한할 수 있습니다.
Plugin 스킬 디렉터리는 `skills.load.extraDirs`와 동일한 낮은 우선순위 경로에 병합되므로, 같은 이름의 번들, 관리형, 에이전트, 워크스페이스 스킬이 이를 재정의합니다. Plugin의 구성 항목에서 `metadata.openclaw.requires.config`를 통해 게이트할 수 있습니다.
검색/config는 [Plugin](/ko/tools/plugin)을, 이러한 skill이 가르치는 도구 표면은
[도구](/ko/tools)를 참조하세요.
검색/구성은 [Plugin](/ko/tools/plugin)을, 이러한 스킬이 가르치는 도구 표면은 [도구](/ko/tools)를 참조하세요.
## Skill Workshop
## 스킬 Workshop
선택적 실험 기능인 **Skill Workshop** Plugin은 에이전트 작업 중 관찰된
재사용 가능한 절차로 workspace skill을 만들거나 업데이트할 수 있습니다.
기본적으로 비활성화되어 있으며 `plugins.entries.skill-workshop`을 통해 명시적으로
활성화해야 합니다.
선택적이고 실험적인 **스킬 Workshop** Plugin은 에이전트 작업 중 관찰된 재사용 가능한 절차에서 워크스페이스 스킬을 만들거나 업데이트할 수 있습니다. 기본적으로 비활성화되어 있으며 `plugins.entries.skill-workshop`을 통해 명시적으로 활성화해야 합니다.
Skill Workshop은 `<workspace>/skills`에만 쓰고, 생성된 콘텐츠를 스캔하며,
보류 중 승인 또는 자동 안전 쓰기를 지원하고, 안전하지 않은 제안을 격리하며,
쓰기 성공 후 skill 스냅샷을 새로 고쳐 Gateway 재시작 없이 새 skill을 사용할 수 있게 합니다.
스킬 Workshop은 `<workspace>/skills`에만 쓰고, 생성된 콘텐츠를 스캔하며, 보류 중 승인 또는 자동 안전 쓰기를 지원하고, 안전하지 않은 제안을 격리하며, 성공적으로 쓴 뒤 스킬 스냅샷을 새로 고쳐 Gateway 재시작 없이 새 스킬을 사용할 수 있게 합니다.
_"다음에는 GIF 저작자 표시를 확인"_ 같은 수정 사항이나 미디어 QA 체크리스트처럼
어렵게 얻은 workflow에 사용하세요. 보류 중 승인으로 시작하고, 자동 쓰기는 제안을
검토한 뒤 신뢰할 수 있는 workspace에서만 사용하세요. 전체 가이드:
[Skill Workshop Plugin](/ko/plugins/skill-workshop).
_"다음에는 GIF 출처 표시를 확인"_ 같은 수정 사항이나 미디어 QA 체크리스트 같은 어렵게 얻은 워크플로에 사용하세요. 보류 중 승인으로 시작하고, 제안을 검토한 뒤 신뢰할 수 있는 워크스페이스에서만 자동 쓰기를 사용하세요. 전체 가이드: [스킬 Workshop Plugin](/ko/plugins/skill-workshop).
## ClawHub (설치 및 동기화)
[ClawHub](https://clawhub.ai)는 OpenClaw의 공개 skill 레지스트리입니다.
검색/설치/업데이트에는 네이티브 `openclaw skills` 명령을 사용하거나,
게시/동기화 workflow에는 별도의 `clawhub` CLI를 사용하세요. 전체 가이드:
[ClawHub](/ko/tools/clawhub).
[ClawHub](https://clawhub.ai)는 OpenClaw용 공개 스킬 레지스트리입니다. 검색/설치/업데이트에는 기본 `openclaw skills` 명령을 사용하고, 게시/동기화 워크플로에는 별도의 `clawhub` CLI를 사용하세요. 전체 가이드: [ClawHub](/ko/tools/clawhub).
| 작업 | 명령 |
| ---------------------------------- | -------------------------------------- |
| workspace에 skill 설치 | `openclaw skills install <skill-slug>` |
| 설치된 모든 skill 업데이트 | `openclaw skills update --all` |
| 동기화(스캔 + 업데이트 게시) | `clawhub sync --all` |
| 작업 | 명령 |
| -------------------------------- | -------------------------------------- |
| 워크스페이스에 스킬 설치 | `openclaw skills install <skill-slug>` |
| 설치된 모든 스킬 업데이트 | `openclaw skills update --all` |
| 동기화(스캔 + 업데이트 게시) | `clawhub sync --all` |
네이티브 `openclaw skills install`은 활성 workspace의 `skills/` 디렉터리에
설치합니다. 별도의 `clawhub` CLI도 현재 작업 디렉터리 아래의 `./skills`에
설치합니다(또는 구성된 OpenClaw workspace로 폴백). OpenClaw는 다음 세션에서
이를 `<workspace>/skills`로 인식합니다.
구성된 skill 루트는 `skills/<group>/<skill>/SKILL.md` 같은 한 단계 그룹화도
지원하므로, 관련된 타사 skill을 광범위한 재귀 스캔 없이 공유 폴더 아래에
유지할 수 있습니다.
기본 `openclaw skills install`은 활성 워크스페이스의 `skills/` 디렉터리에 설치합니다. 별도의 `clawhub` CLI도 현재 작업 디렉터리 아래의 `./skills`에 설치합니다(또는 구성된 OpenClaw 워크스페이스로 폴백). OpenClaw는 다음 세션에서 이를 `<workspace>/skills`로 인식합니다.
구성된 스킬 루트는 `skills/<group>/<skill>/SKILL.md`처럼 한 단계 그룹화도 지원하므로, 관련 타사 스킬을 광범위한 재귀 스캔 없이 공유 폴더 아래에 둘 수 있습니다.
ClawHub skill 페이지는 설치 전 최신 보안 스캔 상태를 노출하며,
VirusTotal, ClawScan, 정적 분석에 대한 스캐너 상세 페이지를 제공합니다.
`openclaw skills install <slug>`는 여전히 설치 경로일 뿐입니다. 게시자는
ClawHub 대시보드 또는 `clawhub skill rescan <slug>`를 통해 false positive를
복구합니다.
ClawHub 스킬 페이지는 설치 전에 최신 보안 스캔 상태를 표시하며, VirusTotal, ClawScan, 정적 분석의 스캐너 상세 페이지를 제공합니다. `openclaw skills install <slug>`는 여전히 설치 경로일 뿐입니다. 게시자는 ClawHub 대시보드 또는 `clawhub skill rescan <slug>`를 통해 오탐을 복구합니다.
## 보안
<Warning>
타사 skill은 **신뢰할 수 없는 코드**로 취급하세요. 활성화하기 전에 읽어 보세요.
신뢰할 수 없는 입력과 위험한 도구에는 sandbox 실행을 선호하세요. 에이전트 측
제어는 [Sandboxing](/ko/gateway/sandboxing)을 참조하세요.
타사 스킬을 **신뢰할 수 없는 코드**로 취급하세요. 활성화하기 전에 읽으세요. 신뢰할 수 없는 입력과 위험한 도구에는 샌드박스 실행을 선호하세요. 에이전트 측 제어는 [샌드박싱](/ko/gateway/sandboxing)을 참조하세요.
</Warning>
- Workspace 및 extra-dir skill 검색은 해석된 realpath가 구성된 루트 내부에 유지되는 skill 루트와 `SKILL.md` 파일만 허용합니다.
- Gateway 기반 skill dependency 설치(`skills.install`, 온보딩, Skills 설정 UI)는 설치 관리자 메타데이터를 실행하기 전에 내장 위험 코드 스캐너를 실행합니다. 호출자가 위험 override를 명시적으로 설정하지 않는 한 `critical` findings는 기본적으로 차단됩니다. 의심스러운 findings는 여전히 경고만 표시합니다.
- `openclaw skills install <slug>`는 다릅니다. 이는 ClawHub skill 폴더를 workspace로 다운로드하며, 위의 설치 관리자 메타데이터 경로를 사용하지 않습니다.
- `skills.entries.*.env`와 `skills.entries.*.apiKey`는 해당 에이전트 turn의 **host** 프로세스에 secret을 주입합니다(sandbox가 아님). secret을 프롬프트와 로그에 포함하지 마세요.
- 워크스페이스 및 추가 디렉터리 스킬 검색은 해석된 realpath가 구성된 루트 내부에 남아 있는 스킬 루트와 `SKILL.md` 파일만 허용합니다.
- Gateway 기반 스킬 의존성 설치(`skills.install`, 온보딩, Skills 설정 UI)는 설치 관리자 메타데이터를 실행하기 전에 내장 위험 코드 스캐너를 실행합니다. 호출자가 위험 재정의를 명시적으로 설정하지 않는 한 `critical` 발견 사항은 기본적으로 차단됩니다. 의심스러운 발견 사항은 여전히 경고만 표시합니다.
- `openclaw skills install <slug>`는 다릅니다. 이는 ClawHub 스킬 폴더를 워크스페이스로 다운로드하며 위의 설치 관리자 메타데이터 경로를 사용하지 않습니다.
- `skills.entries.*.env`와 `skills.entries.*.apiKey`는 해당 에이전트 턴의 **호스트** 프로세스에 시크릿을 주입합니다(샌드박스가 아님). 프롬프트와 로그에 시크릿을 남기지 마세요.
더 넓은 위협 모델과 체크리스트는 [Security](/ko/gateway/security)를 참조하세요.
더 넓은 위협 모델과 체크리스트는 [보안](/ko/gateway/security)을 참조하세요.
## SKILL.md 형식
@ -169,35 +132,32 @@ description: Generate or edit images via a provider-backed image workflow
---
```
OpenClaw는 layout/intent에 대해 AgentSkills 사양을 따릅니다. 임베디드 에이전트가
사용하는 파서는 **single-line** frontmatter key만 지원합니다.
`metadata`는 **single-line JSON object**여야 합니다. 지침에서 skill 폴더 경로를
참조하려면 `{baseDir}`를 사용하세요.
OpenClaw는 레이아웃/의도에 대해 AgentSkills 사양을 따릅니다. 내장 에이전트가 사용하는 파서는 **한 줄** frontmatter 키만 지원합니다. `metadata`는 **한 줄 JSON 객체**여야 합니다. 지침에서 스킬 폴더 경로를 참조하려면 `{baseDir}`을 사용하세요.
### 선택적 frontmatter key
### 선택적 frontmatter 키
<ParamField path="homepage" type="string">
macOS Skills UI에서 "Website"로 표시되는 URL입니다. `metadata.openclaw.homepage`를 통해서도 지원됩니다.
</ParamField>
<ParamField path="user-invocable" type="boolean" default="true">
`true`이면 skill이 사용자 slash command로 노출됩니다.
`true`이면 스킬이 사용자 슬래시 명령으로 노출됩니다.
</ParamField>
<ParamField path="disable-model-invocation" type="boolean" default="false">
`true`이면 skill이 모델 프롬프트에서 제외됩니다(사용자 호출을 통해서는 계속 사용 가능).
`true`이면 스킬이 모델 프롬프트에서 제외됩니다(사용자 호출을 통해서는 계속 사용 가능).
</ParamField>
<ParamField path="command-dispatch" type='"tool"'>
`tool`로 설정하면 slash command가 모델을 우회하고 도구로 직접 dispatch됩니다.
`tool`로 설정하면 슬래시 명령이 모델을 우회하고 도구로 직접 디스패치됩니다.
</ParamField>
<ParamField path="command-tool" type="string">
`command-dispatch: tool`이 설정되었을 때 호출할 도구 이름입니다.
</ParamField>
<ParamField path="command-arg-mode" type='"raw"' default="raw">
도구 dispatch의 경우 raw args 문자열을 도구로 전달합니다(코어 파싱 없음). 도구는 `{ command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }`로 호출됩니다.
도구 디스패치의 경우 원시 인수 문자열을 도구로 전달합니다(코어 파싱 없음). 도구는 `{ command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }`로 호출됩니다.
</ParamField>
## 게이팅(로드 시점 필터)
OpenClaw는 `metadata`(single-line JSON)를 사용해 로드 시점에 skill을 필터링합니다.
OpenClaw는 `metadata`(한 줄 JSON)를 사용해 로드 시점에 스킬을 필터링합니다.
```markdown
---
@ -214,28 +174,28 @@ metadata:
---
```
`metadata.openclaw` 아래의 필드:
`metadata.openclaw` 아래 필드:
<ParamField path="always" type="boolean">
`true`이면 항상 skill을 포함합니다(다른 gate 건너뜀).
`true`이면 항상 스킬을 포함합니다(다른 게이트 건너뜀).
</ParamField>
<ParamField path="emoji" type="string">
macOS Skills UI에서 사용하는 선택적 emoji입니다.
macOS Skills UI에서 사용하는 선택적 이모지입니다.
</ParamField>
<ParamField path="homepage" type="string">
macOS Skills UI에서 "Website"로 표시되는 선택적 URL입니다.
</ParamField>
<ParamField path="os" type='"darwin" | "linux" | "win32"' >
선택적 플랫폼 목록입니다. 설정하면 skill은 해당 OS에서만 적격입니다.
선택적 플랫폼 목록입니다. 설정하면 스킬은 해당 OS에서만 대상이 됩니다.
</ParamField>
<ParamField path="requires.bins" type="string[]">
각각이 `PATH`에 있어야 합니다.
각각이 `PATH`에 존재해야 합니다.
</ParamField>
<ParamField path="requires.anyBins" type="string[]">
최소 하나가 `PATH`에 있어야 합니다.
최소 하나가 `PATH`에 존재해야 합니다.
</ParamField>
<ParamField path="requires.env" type="string[]">
Env var가 존재하거나 config에 제공되어야 합니다.
Env var가 존재하거나 구성에서 제공되어야 합니다.
</ParamField>
<ParamField path="requires.config" type="string[]">
truthy여야 하는 `openclaw.json` 경로 목록입니다.
@ -247,20 +207,17 @@ metadata:
macOS Skills UI에서 사용하는 선택적 설치 관리자 사양입니다(brew/node/go/uv/download).
</ParamField>
`metadata.openclaw`가 없으면 skill은 항상 적격입니다(config에서 비활성화되었거나
번들 skill에 대해 `skills.allowBundled`에 의해 차단된 경우 제외).
`metadata.openclaw`가 없으면 해당 스킬은 항상 대상이 됩니다(구성에서 비활성화되었거나 번들 스킬에 대해 `skills.allowBundled`로 차단된 경우 제외).
<Note>
Legacy `metadata.clawdbot` 블록은 `metadata.openclaw`가 없을 때 여전히 허용되므로,
이전에 설치된 skill은 dependency gate와 설치 관리자 hint를 유지합니다. 신규 및
업데이트된 skill은 `metadata.openclaw`를 사용해야 합니다.
레거시 `metadata.clawdbot` 블록은 `metadata.openclaw`가 없을 때 여전히 허용되므로, 오래된 설치 스킬은 의존성 게이트와 설치 관리자 힌트를 유지합니다. 새 스킬과 업데이트된 스킬은 `metadata.openclaw`를 사용해야 합니다.
</Note>
### Sandboxing 참고 사항
### 샌드박싱 참고 사항
- `requires.bins`는 skill 로드 시점에 **host**에서 확인됩니다.
- 에이전트가 sandbox 처리된 경우 바이너리도 **컨테이너 내부**에 있어야 합니다. `agents.defaults.sandbox.docker.setupCommand`(또는 사용자 지정 이미지)를 통해 설치하세요. `setupCommand`는 컨테이너가 생성된 뒤 한 번 실행됩니다. 패키지 설치에는 네트워크 egress, 쓰기 가능한 루트 FS, sandbox의 root 사용자도 필요합니다.
- 예: `summarize` skill(`skills/summarize/SKILL.md`)은 sandbox 컨테이너에서 실행하려면 그 안에 `summarize` CLI가 필요합니다.
- `requires.bins`는 스킬 로드 시점에 **호스트**에서 확인됩니다.
- 에이전트가 샌드박스 처리된 경우 바이너리도 **컨테이너 내부**에 존재해야 합니다. `agents.defaults.sandbox.docker.setupCommand`(또는 사용자 지정 이미지)를 통해 설치하세요. `setupCommand`는 컨테이너가 생성된 후 한 번 실행됩니다. 패키지 설치에는 네트워크 이그레스, 쓰기 가능한 루트 FS, 샌드박스의 루트 사용자도 필요합니다.
- 예: `summarize` 스킬(`skills/summarize/SKILL.md`)은 샌드박스 컨테이너에서 실행되려면 그 안에 `summarize` CLI가 필요합니다.
### 설치 관리자 사양
@ -292,16 +249,16 @@ metadata:
<AccordionGroup>
<Accordion title="Installer selection rules">
- 여러 설치 프로그램이 나열된 경우 Gateway는 선호하는 옵션 하나를 선택합니다(사용 가능한 경우 brew, 그렇지 않으면 node).
- 모든 설치 프로그램이 `download`이면 OpenClaw는 사용 가능한 아티팩트를 볼 수 있도록 각 항목을 나열합니다.
- 설치 프로그램 사양에는 플랫폼별로 옵션을 필터링하기 위해 `os: ["darwin"|"linux"|"win32"]`를 포함할 수 있습니다.
- Node 설치는 `openclaw.json`의 `skills.install.nodeManager`를 따릅니다(기본값: npm, 옵션: npm/pnpm/yarn/bun). 이는 Skills 설치에만 영향을 줍니다. Gateway 런타임은 여전히 Node여야 하며, Bun은 WhatsApp/Telegram에 권장되지 않습니다.
- Gateway 기반 설치 프로그램 선택은 선호도에 따라 결정됩니다. 설치 사양에 여러 종류가 섞여 있으면 OpenClaw는 `skills.install.preferBrew`가 활성화되어 있고 `brew`가 존재할 때 Homebrew를 우선하고, 그다음 `uv`, 구성된 node 관리자, 그리고 `go`나 `download` 같은 다른 대체 옵션 순으로 선호합니다.
- 모든 설치 사양이 `download`이면 OpenClaw는 하나의 선호 설치 프로그램으로 축약하지 않고 모든 다운로드 옵션을 표시합니다.
- 모든 설치 프로그램이 `download`인 경우 OpenClaw는 사용 가능한 아티팩트를 볼 수 있도록 각 항목을 나열합니다.
- 설치 사양에는 플랫폼별로 옵션을 필터링하기 위해 `os: ["darwin"|"linux"|"win32"]`를 포함할 수 있습니다.
- Node 설치는 `openclaw.json`의 `skills.install.nodeManager`를 따릅니다(기본값: npm; 옵션: npm/pnpm/yarn/bun). 이는 Skills 설치에만 영향을 줍니다. Gateway 런타임은 여전히 Node여야 하며, Bun은 WhatsApp/Telegram에는 권장되지 않습니다.
- Gateway 기반 설치 프로그램 선택은 선호도에 따라 결정됩니다. 설치 사양에 여러 종류가 섞여 있으면 OpenClaw는 `skills.install.preferBrew`가 활성화되어 있고 `brew`가 존재할 때 Homebrew를 우선하고, 그다음 `uv`, 구성된 node 관리자, `go` 또는 `download` 같은 기타 대체 항목 순으로 선호합니다.
- 모든 설치 사양이 `download`이면 OpenClaw는 하나의 선호 설치 프로그램으로 축소하지 않고 모든 다운로드 옵션을 표시합니다.
</Accordion>
<Accordion title="Per-installer details">
- **Go 설치:** `go`가 없고 `brew`를 사용할 수 있으면 Gateway는 먼저 Homebrew를 통해 Go를 설치하고, 가능하면 `GOBIN`을 Homebrew의 `bin`으로 설정합니다.
- **다운로드 설치:** `url`(필수), `archive`(`tar.gz` | `tar.bz2` | `zip`), `extract`(기본값: 아카이브 감지 시 auto), `stripComponents`, `targetDir`(기본값: `~/.openclaw/tools/<skillKey>`).
- **Go 설치:** `go`가 없고 `brew`를 사용할 수 있으면 Gateway가 먼저 Homebrew를 통해 Go를 설치하고, 가능한 경우 `GOBIN`을 Homebrew의 `bin`으로 설정합니다.
- **다운로드 설치:** `url`(필수), `archive`(`tar.gz` | `tar.bz2` | `zip`), `extract`(기본값: 아카이브가 감지되면 auto), `stripComponents`, `targetDir`(기본값: `~/.openclaw/tools/<skillKey>`).
</Accordion>
</AccordionGroup>
@ -309,7 +266,7 @@ metadata:
## 구성 재정의
번들 및 관리형 Skills는 `~/.openclaw/openclaw.json`의 `skills.entries`
아래에서 켜거나 끄고 env 값을 제공할 수 있습니다.
아래에서 토글하고 env 값을 제공할 수 있습니다.
```json5
{
@ -334,35 +291,36 @@ metadata:
```
<ParamField path="enabled" type="boolean">
`false`는 번들로 제공되었거나 설치된 경우에도 해당 Skills를 비활성화합니다.
번들 `coding-agent` Skills는 옵트인 방식입니다. 에이전트에 노출하기 전에
`skills.entries.coding-agent.enabled: true`를 설정한 다음, `claude`, `codex`,
`opencode`, `pi` 중 하나가 설치되어 있고 자체 CLI에 인증되어 있는지
확인하세요.
`false`는 번들되었거나 설치된 경우에도 skill을 비활성화합니다.
번들된 `coding-agent` skill은 옵트인 방식입니다. 에이전트에 노출하기 전에
`skills.entries.coding-agent.enabled: true`를 설정한 다음,
`claude`, `codex`, `opencode`, `pi` 중 하나가 설치되어 있고
자체 CLI 인증이 완료되었는지 확인하세요.
</ParamField>
<ParamField path="apiKey" type='string | { source, provider, id }'>
`metadata.openclaw.primaryEnv`를 선언하는 Skills를 위한 편의 기능입니다. 일반 텍스트 또는 SecretRef를 지원합니다.
</ParamField>
<ParamField path="env" type="Record<string, string>">
변수가 프로세스에 아직 설정되어 있지 않은 경우에만 주입됩니다.
해당 변수가 프로세스에 아직 설정되어 있지 않은 경우에만 주입됩니다.
</ParamField>
<ParamField path="config" type="object">
사용자 지정 Skills별 필드를 위한 선택적 모음입니다. 사용자 지정 키는 반드시 여기에 있어야 합니다.
사용자 지정 skill별 필드를 위한 선택적 모음입니다. 사용자 지정 키는 반드시 여기에 있어야 합니다.
</ParamField>
<ParamField path="allowBundled" type="string[]">
**번들** Skills에만 적용되는 선택적 허용 목록입니다. 설정하면 목록에 있는 번들 Skills만 대상이 됩니다(관리형/워크스페이스 Skills에는 영향 없음).
**번들된** Skills 전용 선택적 허용 목록입니다. 설정하면 목록에 있는 번들 Skills만 사용할 수 있습니다(관리형/워크스페이스 Skills에는 영향 없음).
</ParamField>
Skills 이름에 하이픈이 포함되어 있으면 키를 따옴표로 감싸세요(JSON5는 따옴표로 감싼
키를 허용합니다). 구성 키는 기본적으로 **Skills 이름**과 일치합니다. Skills가
skill 이름에 하이픈이 포함되어 있으면 키를 따옴표로 감싸세요(JSON5는 따옴표로 감싼
키를 허용합니다). 구성 키는 기본적으로 **skill 이름**과 일치합니다. skill이
`metadata.openclaw.skillKey`를 정의하는 경우 `skills.entries` 아래에서 해당 키를 사용하세요.
<Note>
OpenClaw 안에서 스톡 이미지 생성/편집을 할 때는 번들 Skills 대신
`agents.defaults.imageGenerationModel`과 함께 코어 `image_generate` 도구를 사용하세요.
여기 있는 Skills 예시는 사용자 지정 또는 서드파티 워크플로를 위한 것입니다.
네이티브 이미지 분석에는 `agents.defaults.imageModel`과 함께 `image` 도구를 사용하세요.
`openai/*`, `google/*`, `fal/*` 또는 다른 제공자별 이미지 모델을 선택하는 경우 해당 제공자의
OpenClaw 내부의 기본 이미지 생성/편집에는 번들 skill 대신
`agents.defaults.imageGenerationModel`과 함께 코어
`image_generate` 도구를 사용하세요. 여기에 있는 skill 예시는 사용자 지정 또는 서드파티
워크플로를 위한 것입니다. 네이티브 이미지 분석에는
`agents.defaults.imageModel`과 함께 `image` 도구를 사용하세요. `openai/*`, `google/*`,
`fal/*` 또는 다른 제공자별 이미지 모델을 선택하는 경우 해당 제공자의
인증/API 키도 추가하세요.
</Note>
@ -370,36 +328,39 @@ OpenClaw 안에서 스톡 이미지 생성/편집을 할 때는 번들 Skills
에이전트 실행이 시작되면 OpenClaw는 다음을 수행합니다.
1. Skills 메타데이터를 읽습니다.
1. skill 메타데이터를 읽습니다.
2. `skills.entries.<key>.env` 및 `skills.entries.<key>.apiKey`를 `process.env`에 적용합니다.
3. **대상** Skills로 시스템 프롬프트를 빌드합니다.
3. **사용 가능한** Skills로 시스템 프롬프트를 빌드합니다.
4. 실행이 끝난 뒤 원래 환경을 복원합니다.
환경 주입은 전역 셸 환경이 아니라 **에이전트 실행에 한정**됩니다.
환경 주입은 전역 셸 환경이 아니라 **에이전트 실행 범위로 제한**됩니다.
번들 `claude-cli` 백엔드의 경우, OpenClaw는 같은 대상 스냅샷을 임시 Claude Code Plugin으로도
구체화하고 `--plugin-dir`와 함께 전달합니다. 그러면 Claude Code는 자체 네이티브 Skills
해결기를 사용할 수 있으며, OpenClaw는 계속해서 우선순위, 에이전트별 허용 목록, 게이팅,
`skills.entries.*` env/API 키 주입을 관리합니다. 다른 CLI 백엔드는 프롬프트 카탈로그만 사용합니다.
번들된 `claude-cli` 백엔드의 경우 OpenClaw는 동일한
사용 가능 스냅샷을 임시 Claude Code Plugin으로 구체화하고
`--plugin-dir`로 전달합니다. 그러면 Claude Code는 네이티브 skill resolver를 사용할 수 있고,
OpenClaw는 계속해서 우선순위, 에이전트별 허용 목록, 게이팅,
`skills.entries.*` env/API 키 주입을 담당합니다. 다른 CLI 백엔드는
프롬프트 카탈로그만 사용합니다.
## 스냅샷 및 새로 고침
OpenClaw는 세션이 시작될 때 **대상 Skills**의 스냅샷을 만들고,
같은 세션의 이후 턴에서는 해당 목록을 재사용합니다. Skills 또는 구성 변경 사항은 다음 새 세션부터 적용됩니다.
OpenClaw는 **세션이 시작될 때** 사용 가능한 Skills의 스냅샷을 만들고
같은 세션의 이후 턴에서 그 목록을 재사용합니다. Skills 또는 구성 변경 사항은
다음 새 세션부터 적용됩니다.
Skills는 다음 두 경우에 세션 중간에 새로 고쳐질 수 있습니다.
Skills는 두 가지 경우 세션 중간에 새로 고칠 수 있습니다.
- Skills 감시자가 활성화되어 있습니다.
- 새로운 대상 원격 node가 나타납니다.
- 새로운 사용 가능한 원격 node가 나타납니다.
이를 **핫 리로드**로 생각하면 됩니다. 새로 고친 목록은 다음 에이전트 턴에서 반영됩니다.
해당 세션의 유효 에이전트 Skills 허용 목록이 변경되면 OpenClaw는 표시되는 Skills가
현재 에이전트와 일치하도록 스냅샷을 새로 고칩니다.
이를 **핫 리로드**로 생각하면 됩니다. 새로 고친 목록은
다음 에이전트 턴에서 반영됩니다. 해당 세션의 유효한 에이전트 skill 허용 목록이 변경되면
OpenClaw는 보이는 Skills가 현재 에이전트와 계속 일치하도록 스냅샷을 새로 고칩니다.
### Skills 감시자
기본적으로 OpenClaw는 Skills 폴더를 감시하고 `SKILL.md` 파일이 변경되면 Skills 스냅샷을 갱신합니다.
`skills.load` 아래에서 구성하세요.
기본적으로 OpenClaw는 skill 폴더를 감시하고 `SKILL.md` 파일이 변경되면
Skills 스냅샷을 갱신합니다. `skills.load` 아래에서 구성하세요.
```json5
{
@ -415,21 +376,24 @@ Skills는 다음 두 경우에 세션 중간에 새로 고쳐질 수 있습니
### 원격 macOS node(Linux Gateway)
Gateway가 Linux에서 실행되지만 `system.run`이 허용된 **macOS node**가 연결되어 있으면
(Exec 승인 보안이 `deny`로 설정되지 않은 경우), 필요한 바이너리가 해당 node에 있을 때
OpenClaw는 macOS 전용 Skills를 대상으로 간주할 수 있습니다. 에이전트는 `host=node`와 함께
`exec` 도구를 사용해 이러한 Skills를 실행해야 합니다.
(Exec 승인 보안이 `deny`로 설정되지 않은 경우),
필요한 바이너리가 해당 node에 있을 때 OpenClaw는 macOS 전용 Skills를 사용 가능한 것으로 처리할 수 있습니다.
에이전트는 `host=node`와 함께 `exec` 도구를 통해 해당 Skills를 실행해야 합니다.
이는 node가 자신의 명령 지원을 보고하고, `system.which` 또는 `system.run`을 통한 bin probe에 의존합니다.
오프라인 node는 원격 전용 Skills를 표시하지 않습니다. 연결된 node가 bin probe에 응답하지 않으면
OpenClaw는 캐시된 bin 일치를 지워, 현재 그곳에서 실행할 수 없는 Skills가 더 이상 에이전트에 보이지 않게 합니다.
이는 node가 명령 지원을 보고하고 `system.which` 또는 `system.run`을 통한
bin 프로브가 가능하다는 점에 의존합니다. 오프라인 node는 **원격 전용** Skills를
보이게 만들지 않습니다. 연결된 node가 bin 프로브에 응답하지 않으면
OpenClaw는 캐시된 bin 일치 항목을 지워 에이전트가 현재 그곳에서 실행할 수 없는
Skills를 더 이상 보지 않도록 합니다.
## 토큰 영향
Skills가 대상이면 OpenClaw는 사용 가능한 Skills의 간결한 XML 목록을 시스템 프롬프트에 주입합니다
(`pi-coding-agent`의 `formatSkillsForPrompt`를 통해). 비용은 결정적입니다.
Skills를 사용할 수 있으면 OpenClaw는 사용 가능한 Skills의 간결한 XML 목록을
시스템 프롬프트에 주입합니다(`pi-coding-agent`의 `formatSkillsForPrompt` 사용).
비용은 결정적입니다.
- **기본 오버헤드**(Skills가 1개 이상일 때만): 195자.
- **Skills당:** 97자 + XML 이스케이프된 `<name>`, `<description>`, `<location>` 값의 길이.
- **기본 오버헤드**(skill이 1개 이상일 때만): 195자.
- **skill당:** 97자 + XML 이스케이프된 `<name>`, `<description>`, `<location>` 값의 길이.
공식(문자 수):
@ -437,15 +401,18 @@ Skills가 대상이면 OpenClaw는 사용 가능한 Skills의 간결한 XML 목
total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))
```
XML 이스케이프는 `& < > " '`를 엔터티(`&amp;`, `&lt;` 등)로 확장하므로 길이가 늘어납니다.
토큰 수는 모델 토크나이저에 따라 달라집니다. OpenAI 스타일의 대략적인 추정치는 약 4자/토큰이므로,
**97자 ≈ 24토큰**이 Skills당 추가되며 실제 필드 길이가 더해집니다.
XML 이스케이프는 `& < > " '`를 엔티티(`&amp;`, `&lt;` 등)로 확장하여
길이를 늘립니다. 토큰 수는 모델 토크나이저에 따라 달라집니다. 대략적인
OpenAI 스타일 추정치는 약 4자/토큰이므로 **97자 ≈ 24토큰**이
skill당 추가되고, 여기에 실제 필드 길이가 더해집니다.
## 관리형 Skills 수명 주기
OpenClaw는 설치(npm 패키지 또는 OpenClaw.app)와 함께 기준 Skills 세트를 **번들 Skills**로 제공합니다.
`~/.openclaw/skills`는 로컬 재정의를 위해 존재합니다. 예를 들어 번들 사본을 변경하지 않고
Skills를 고정하거나 패치할 수 있습니다. 워크스페이스 Skills는 사용자가 소유하며, 이름 충돌 시 둘보다 우선합니다.
OpenClaw는 설치(npm 패키지 또는 OpenClaw.app)와 함께 **번들 Skills**로
기본 Skills 세트를 제공합니다. `~/.openclaw/skills`는
로컬 재정의를 위해 존재합니다. 예를 들어 번들된 사본을 변경하지 않고
skill을 고정하거나 패치할 수 있습니다. 워크스페이스 Skills는 사용자가 소유하며
이름 충돌 시 둘 모두를 재정의합니다.
## 더 많은 Skills를 찾고 있나요?
@ -457,6 +424,6 @@ Skills를 고정하거나 패치할 수 있습니다. 워크스페이스 Skills
- [ClawHub](/ko/tools/clawhub) — 공개 Skills 레지스트리
- [Skills 만들기](/ko/tools/creating-skills) — 사용자 지정 Skills 빌드
- [Plugins](/ko/tools/plugin) — Plugin 시스템 개요
- [Skill Workshop plugin](/ko/plugins/skill-workshop) — 에이전트 작업에서 Skills 생성
- [Skills 구성](/ko/tools/skills-config) — Skills 구성 참조
- [Skill Workshop Plugin](/ko/plugins/skill-workshop) — 에이전트 작업에서 Skills 생성
- [Skills 구성](/ko/tools/skills-config) — skill 구성 참조
- [슬래시 명령](/ko/tools/slash-commands) — 사용 가능한 모든 슬래시 명령