🦞 10. OpenCode 연동

OpenClaw에서 받은 코드 요청을 OpenCode로 바로 실행하고, 결과를 다시 OpenClaw 대화에서 확인하는 표준 연동 가이드다. 복잡한 세팅 대신, 실제 운영에서 바로 쓰는 최소 단계로 정리했다.

이 문서로 되는 것

• OpenClaw 채팅에서 코드실행, 결과요약, 문서화로 동작
• OpenCode 실행 결과를 파일로 저장하고 재사용
• 팀/개인 모두 같은 방식으로 재현 가능

모델/런타임 전제 (중요)

이 가이드는 모델 중립(model-agnostic) 이다.
즉, OpenClaw 기본 모델이 Ollama든 OpenAI든 Anthropic이든 상관없이 동일하게 적용된다.

• 필수: openclaw, opencode 실행 가능
• 선택: Ollama / OpenAI / Anthropic / 기타 연결 모델
• 원칙: OpenCode 연동 로직은 모델 종류와 분리해서 이해한다

Ollama는 “가능한 예시”일 뿐, 필수 조건이 아니다.

전체 흐름 (표준)

flowchart LR
  A[OpenClaw 채팅\n코드실행] --> B[OpenClaw가 OpenCode 실행\nPTY 모드]
  B --> C[결과 파일 저장\narchive/opencode_result_*.md]
  C --> D[결과요약/문서화]
  D --> E[OpenClaw 채팅으로 보고]

1단계) 같은 머신에서 실행되는지 확인

OpenClaw와 OpenCode는 같은 로컬 머신에 있어야 가장 안정적이다.

hostname
which openclaw
which opencode
openclaw gateway status
opencode --version

정상 기준:

• which openclaw, which opencode 모두 경로가 출력됨
• openclaw gateway status가 정상 상태

2단계) 표준 브리지 스크립트 설치

mkdir -p ~/openclaw-bridge/{archive,bin}
 
cat > ~/openclaw-bridge/bin/trigger.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
 
BASE="$HOME/openclaw-bridge"
ARCHIVE="$BASE/archive"
TASK_FILE="$BASE/task.txt"
 
mkdir -p "$ARCHIVE"
 
latest_file() {
  ls -t "$ARCHIVE"/*.md 2>/dev/null | head -n 1 || true
}
 
run_opencode() {
  local prompt="$1"
  local out="$ARCHIVE/opencode_result_$(date +%y%m%d_%H%M%S).md"
 
  {
    echo "# OpenCode Result"
    echo "- time: $(date '+%F %T')"
    echo
    opencode run "$prompt"
  } > "$out"
 
  echo "saved: $out"
}
 
do_run() {
  local inline="${*:-}"
  local prompt=""
 
  if [ -n "$inline" ]; then
    prompt="$inline"
  elif [ -f "$TASK_FILE" ]; then
    prompt="$(cat "$TASK_FILE")"
  else
    echo "오류: 프롬프트가 없어요."
    echo "- 방법1) 코드실행 뒤에 바로 요청 입력"
    echo "- 방법2) $TASK_FILE 파일 생성"
    exit 1
  fi
 
  run_opencode "$prompt"
}
 
do_summary() {
  local latest
  latest="$(latest_file)"
  [ -n "$latest" ] || { echo "요약할 결과 파일 없음"; exit 1; }
 
  local out="$ARCHIVE/summary_$(date +%y%m%d_%H%M%S).md"
  {
    echo "# 결과요약"
    echo "- source: $latest"
    echo "- time: $(date '+%F %T')"
    echo
    sed -n '1,160p' "$latest"
  } > "$out"
 
  echo "saved: $out"
}
 
do_docify() {
  local latest
  latest="$(latest_file)"
  [ -n "$latest" ] || { echo "문서화할 결과 파일 없음"; exit 1; }
 
  local out="$ARCHIVE/doc_$(date +%y%m%d_%H%M%S).md"
  {
    echo "---"
    echo "title: OpenCode 실행 결과 문서화"
    echo "tags: [domain-ai, topic-opencode, format-note, audience-practitioner, intent-apply, lang-ko]"
    echo "---"
    echo
    echo "## 원본"
    echo "- $latest"
    echo
    echo "## 내용"
    cat "$latest"
  } > "$out"
 
  echo "saved: $out"
}
 
cmd="${1:-}"
shift || true
 
case "$cmd" in
  코드실행) do_run "$@" ;;
  결과요약) do_summary ;;
  문서화) do_docify ;;
  *)
    echo "사용법: trigger.sh {코드실행|결과요약|문서화} [요청문]"
    exit 1
    ;;
esac
EOF
 
chmod +x ~/openclaw-bridge/bin/trigger.sh

3단계) 터미널에서 1분 스모크 테스트

bash ~/openclaw-bridge/bin/trigger.sh 코드실행 "파이썬 hello.py 작성, 실행 명령 1줄 포함"
bash ~/openclaw-bridge/bin/trigger.sh 결과요약
ls -lt ~/openclaw-bridge/archive | head -n 5

정상 기준:

• opencode_result_*.md 생성
• summary_*.md 생성

4단계) OpenClaw용 표준 규칙(복붙)

아래 블록을 OpenClaw 워크스페이스의 AGENTS.md에 붙인다.

## OpenCode 표준 트리거 규칙
사용자 메시지가 다음 패턴이면 OpenCode로 처리한다.
 
- 코드실행: <요청>
  - `bash ~/openclaw-bridge/bin/trigger.sh 코드실행 "<요청>"` 실행
  - 실행 시 PTY 모드 사용(코딩 에이전트 필수)
- 결과요약
  - `bash ~/openclaw-bridge/bin/trigger.sh 결과요약` 실행
- 문서화
  - `bash ~/openclaw-bridge/bin/trigger.sh 문서화` 실행
 
자동 라우팅:
- 사용자가 트리거를 직접 쓰지 않아도, 코딩 실행이 필요하면 내부적으로 `코드실행` 경로를 선택한다.
 
프리체크 모드(기본 ON):
- 요청이 애매하면 실행 전 1회 질문: `실행할까, 설명만 할까?`
- `코드실행` 명시 시 즉시 실행
- `설명만`/`실행하지 마` 명시 시 실행하지 않음
 
응답 형식:
1) 생성 파일 경로
2) 성공/실패
3) 다음 액션 1줄

5단계) OpenClaw 채팅에서 바로 사용

코드실행: FastAPI로 /health 엔드포인트 1개만 있는 최소 서버 코드 작성
결과요약
문서화

5-1단계) 프리체크 모드 사용 예시

애매한 요청에서는 바로 실행하지 않고 1회 확인한다.

예시 A: 자동 프리체크

사용자: 간단한 파이썬 스크립트 하나 만들어볼까?
에이전트: 실행할까, 설명만 할까?
사용자: 실행해줘
→ 내부적으로 코드실행 경로로 진행

예시 B: 즉시 실행

사용자: 코드실행: CSV 병합 파이썬 스크립트 작성
→ 즉시 실행 (프리체크 생략)

예시 C: 실행 금지

사용자: 설명만 해줘, 실행하지 마
→ 설명만 제공 (OpenCode 실행 안 함)

6단계) 자주 막히는 문제

1. command not found: opencode

• 해결: OpenCode 설치 후 셸 재시작, which opencode 재확인

2. 결과 파일이 안 생김

• 해결: ~/openclaw-bridge/archive 권한/경로 확인

3. OpenClaw가 실행은 했는데 출력이 이상함

• 해결: 코딩 에이전트 실행은 PTY 모드로 강제

4. 요청문 없이 코드실행만 입력

• 해결: ~/openclaw-bridge/task.txt를 만들어 기본 프롬프트 저장

7단계) 운영 체크리스트

• OpenClaw/OpenCode가 같은 머신에서 실행됨
• trigger.sh 실행 가능
• 코드실행/결과요약/문서화 3개 동작 확인
• archive에 결과 파일 생성 확인

📚 다음 읽기

• 🦞 13. Subagents 설계와 프롬프트 — 서브 에이전트로 확장
• 🦞 34. 세션툴 블로그 검수자동화 — 세션 관리 실전
• 🦞 14. SkillOps 운영전환 — 스킬 운영으로 이어가기
• 🔷 OpenCode 오리엔테이션 — OpenCode 전체 개요
• AI 코딩 에이전트 5종 비교 — 다른 코딩 에이전트와 비교

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안 작성 및 구조화를 수행했으며, 최종 공개 전 사람이 검토·보정한다.