코딩 에이전트

코딩 에이전트은(는) 무엇을 하나요?

백그라운드 기능 개발, PR 리뷰, 대규모 리팩토링, 이슈-to-PR 루프에 사용하세요. 단순 편집, 읽기 전용 조회, ACP 스레드 바운드 작업, 또는 ~/.openclaw, $OPENCLAW_STATE_DIR 또는 활성 OpenClaw 상태 디렉토리 내에서는 실행하지 마세요.

엄격한 규칙

• 항상 background:true로 실행합니다.
• Codex와 OpenCode: pty:true를 사용합니다.
• Codex: 주변 환경의 CODEX_HOME이나 기본 ~/.codex를 절대 상속하지 마세요. 별도로 인증된 코딩 에이전트 홈을 사용하고 각 Codex 명령어에 범위를 지정하세요.
• Claude Code: PTY를 사용하지 않으며 claude --permission-mode bypassPermissions --print를 사용하세요.
• 워커를 생성하기 전에 실제 알림 경로를 캡처하세요.
• 워커는 openclaw message send를 통해 완료/실패를 보내야 합니다.
• 하트비트, 시스템 이벤트 또는 종료 시 알림에 의존하지 마세요.
• process로 모니터링하고, 이유 없이 느린 워커를 종료하지 마세요.
• 사용자가 특정 에이전트를 요청한 경우 해당 에이전트를 사용하세요.
• 워커가 실패/멈춤 시 재시작하거나 질문하고, 조용히 직접 코딩하지 마세요.
• ~/Projects/openclaw에서 브랜치를 체크아웃하거나 백그라운드 코딩 에이전트를 실행하지 마세요. 격리된 체크아웃을 사용하세요.
• 체크아웃 또는 워크트리 생성 전에 소스 ref를 신뢰 또는 비신뢰로 분류하세요. 기여자 제어 ref를 리포지토리의 승인된 비신뢰-PR 샌드박스/리뷰 워크플로 외부에서 절대 구체화하지 말고, 해당 샌드박스 내에서 권한 우회 워커를 실행하지 마세요.
• Git 기반 프로젝트를 수정하는 작업의 경우, 실행 전에 Git 작업 트리를 준비하고 확인한 후 워커 프롬프트에 정확한 Git 준비 블록을 포함하세요.

필수 Git 준비

Git 기반 프로젝트를 수정하는 작업을 위해 Codex, Claude Code 또는 OpenCode를 실행하기 전에:

1. 대상 리포지토리를 설정한 후 정식 원격(remote)을 선택하세요. upstream이 존재하고 대상과 일치하면 선호하고, 그렇지 않으면 origin을 확인하세요. 선택한 원격의 기본 브랜치를 동적으로 결정하세요. 명시적 작업 브랜치 또는 권위 있는 기존 PR 메타데이터에서 대상 베이스를 결정하고, 다른 공유 브랜치의 경우 설정/추적된 베이스를 증명하거나 질문하세요. 다른 지정된 베이스가 없는 새 작업에는 정식 기본 브랜치를 사용하세요. 리포지토리, 원격 또는 대상 베이스를 증명할 수 없으면 중지하세요.
2. 체크아웃 또는 워크트리 생성 전에 소스 ref를 신뢰 또는 비신뢰로 분류하세요. 기여자 제어 ref의 경우 리포지토리의 승인된 비신뢰-PR 샌드박스/리뷰 워크플로를 사용하세요. 이 워크플로는 샌드박스 내에서 ref 구체화를 소유해야 하며, 그렇지 않으면 중지하세요. 나머지 단계와 실행 형식은 신뢰되는 ref에만 해당됩니다.
3. 신뢰되는 새 작업의 경우, <canonical>/<targetBaseBranch>에서 새 격리 워크트리와 브랜치를 생성하기 직전에 git fetch --prune <canonical>을 실행하세요.
4. 신뢰되는 새 작업의 경우 워크트리의 초기 HEAD가 가져온 대상 베이스 SHA와 같은지 확인하세요. 정식 원격, 정식 기본 브랜치, 대상 베이스 브랜치, 베이스 SHA, 워크트리 경로 및 브랜치를 기록하세요.
5. 신뢰되는 기존 PR 또는 공유 브랜치의 경우, 가져온 소스 브랜치에서 격리 워크트리를 생성하기 직전에 정식 대상 베이스와 소스 브랜치를 가져오세요. 해당 소스 ref와 시작 SHA를 기록하고, 새로 고쳐진 대상 베이스와의 차이를 보고하며, 자동으로 리베이스, 병합, 리셋, 강제 푸시 또는 공유 기록을 다시 쓰지 마세요.
6. 워커를 기본 체크아웃이 아닌 격리 워크트리에서 실행하세요. OpenClaw의 경우 ~/Projects/openclaw의 기본 체크아웃은 금지됩니다.

Git 기반 프로젝트를 수정하는 작업의 경우, 실제 값으로 이 블록을 워커 프롬프트에 추가하세요:

Git 준비 (편집 전 필수):
- 정식 원격: <canonicalRemote>
- 정식 기본 브랜치: <canonicalDefaultBranch>
- 대상 베이스 브랜치: <targetBaseBranch>
- 가져온 대상 베이스 SHA: <targetBaseSha>
- 준비 모드: <new work | existing PR/shared branch>
- 체크아웃 신뢰도: trusted
- 준비된 소스 ref: <canonicalRemote/targetBaseBranch | fetched trusted source ref>
- 준비된 시작 SHA: <preparedStartSha>
- 격리 워크트리: <worktreePath>
- 작업 브랜치: <branch>
- 준비 영수증: <new work: `<canonicalRemote>/<targetBaseBranch>`에서 생성 직전 `git fetch --prune <canonicalRemote>`가 실행되었습니다 | existing branch: 정식 대상 베이스와 신뢰 소스 ref가 `<preparedSourceRef>`의 `<preparedStartSha>`에서 워크트리가 생성되기 직전에 가져와졌습니다>

편집 전에 현재 디렉토리가 격리 워크트리이고 초기 HEAD가 <preparedStartSha>와 같은지 확인하세요. 새 작업의 경우 해당 SHA는 <targetBaseSha>와 같아야 합니다. 기본 체크아웃을 편집하지 마세요. 기존 PR/공유 브랜치 작업의 경우 차이를 보고하고 명시적으로 요청하지 않는 한 리베이스, 병합, 리셋, 강제 푸시 또는 공유 기록을 다시 쓰지 마세요.
새로 작성된 작업의 최종 푸시 또는 PR 직전에 `git fetch --prune <canonicalRemote>` 및 `git merge-base --is-ancestor <canonicalRemote>/<targetBaseBranch> HEAD`를 실행하세요. 조상 확인에 실패하면 최신 대상 베이스로 새 브랜치를 업데이트하고 관련 증명을 다시 실행한 후에만 푸시하세요(강제 푸시 없음). 기존 PR/공유 브랜치 작업의 경우 조상 확인 실패를 보고하고 브랜치를 다시 쓰지 않고 리포지토리 워크플로를 따르세요.

신뢰되는 ref의 경우 실행기는 편집 워커를 시작하기 전에 워크트리를 생성하고 확인해야 합니다. 워크트리 생성을 해당 워커에 위임하지 마세요. 승인된 비신뢰-PR 워크플로는 샌드박스 내에서 체크아웃 및 워크트리 구체화를 소유해야 합니다. ~/Projects/openclaw에서 워커를 시작하지 마세요. 읽기 전용 작업 및 비프로젝트 스크래치 작업은 Git 준비 블록이 필요하지 않습니다.

알림 블록

모든 워커 프롬프트에 실제 값으로 이 형식을 추가하세요:

알림 경로:
- 채널: <notifyChannel>
- 대상: <notifyTarget>
- 계정: <notifyAccount or omit>
- reply_to: <notifyReplyTo or omit>
- thread_id: <notifyThreadId or omit>

완료 시 다음 명령어를 사용하여 정확히 하나의 완료 또는 실패 메시지를 보내세요:
openclaw message send --channel <channel> --target '<target>' --message '<brief result>'
위에 있을 때만 --account, --reply-to 또는 --thread-id를 추가하세요.
openclaw 시스템 이벤트 또는 하트비트를 사용하지 마세요.

신뢰할 수 있는 경로가 없으면 완료 자동 알림을 사용할 수 없다고 말하세요.

실행 형식

먼저 워커 프롬프트를 임시 파일에 작성하세요. 이는 필수 알림 블록에 따옴표나 줄바꿈이 포함될 때 셸 따옴표 버그를 방지합니다.

PROMPT=$(mktemp -t openclaw-worker-prompt.XXXXXX)
cat >"$PROMPT" <<'EOF'
Task.
<필수 Git 준비 블록>
<알림 블록>
EOF
printf '프롬프트 파일: %s\n' "$PROMPT"

동일한 셸/세션에서 실행할 때 $PROMPT를 사용하세요. 별도의 도구 호출을 사용하는 경우 출력된 경로를 대체하세요. 아래 실행 형식은 신뢰되는 체크아웃에만 해당됩니다. 비신뢰 기여자 ref는 리포지토리의 승인된 샌드박스/리뷰 워크플로가 필요합니다.

호스트에서 첫 번째 Codex 워커를 실행하기 전에 포그라운드에서 전용 인증 홈을 준비하세요. 주변 환경의 ~/.codex에서 auth.json 또는 기타 자격 증명을 복사하지 말고 이 홈을 별도로 인증하세요. Codex는 CODEX_HOME으로 파일 및 키링 자격 증명의 범위를 지정합니다.

CODEX_WORKER_HOME="$HOME/.codex-coding-agent"
mkdir -p "$CODEX_WORKER_HOME"
if ! env -u CODEX_API_KEY -u CODEX_ACCESS_TOKEN -u OPENAI_API_KEY \
  CODEX_HOME="$CODEX_WORKER_HOME" codex login status >/dev/null 2>&1; then
  printf 'Codex 코딩 에이전트 로그인이 필요합니다: %s\n' "$CODEX_WORKER_HOME"
  env -u CODEX_API_KEY -u CODEX_ACCESS_TOKEN -u OPENAI_API_KEY \
    CODEX_HOME="$CODEX_WORKER_HOME" codex login --device-auth
fi
printf 'Codex 워커 홈: %s\n' "$CODEX_WORKER_HOME"

로그인은 백그라운드 워커가 아닌 대화형 포그라운드 설정 단계입니다. 실행 명령은 고정된 따옴표가 있는 홈을 반복하고 주변 환경의 Codex 및 OpenAI 인증 재정의를 제거합니다. 워커 홈을 OpenClaw 게이트웨이 환경으로 내보내지 마세요.

Codex:

bash pty:true background:true workdir:/path/isolated-worktree command:"env -u CODEX_API_KEY -u CODEX_ACCESS_TOKEN -u OPENAI_API_KEY CODEX_HOME=\\