OpenClaw가 OpenAI의 강력한 이미지 모델인 gpt-image-2를 직접 호출하도록 만들고 싶다면, 가장 먼저 어떤 방법이 떠오르시나요? 아마 대부분은 에디터를 열고 requests.post(...)가 포함된 파이썬 스크립트를 작성한 뒤, 이를 도구 함수로 만들어 에이전트에게 전달하는 방식을 생각하실 겁니다.
물론 이 방법도 가능하지만, 다음과 같은 네 가지 번거로움에 즉시 직면하게 됩니다.
multipart/form-data를 통한 참조 이미지 업로드 처리- 재시도/타임아웃/429 제한 로직 작성
- 각 시나리오(텍스트-이미지 변환, 이미지-이미지 변환, 마스크, 일괄 처리)마다 별도의 캡슐화 필요
- OpenClaw 클라이언트(또는 Claude Code, Cursor)를 바꿀 때마다 매번 재통합
2026년의 해답은 바뀌었습니다. 코드를 작성하지 말고, Skill을 설치하세요.
OpenClaw는 완전한 Skills 생태계를 지원하며, ClawHub 레지스트리에는 현재 5,700개 이상의 커뮤니티 기여 Skill이 등록되어 있습니다. 이번 글에서는 APIYI 팀이 expert-skills-hub 저장소에 기여한 두 가지 공식 gpt-image-2 Skill을 소개합니다.
apiyi-gpt-image-2-gen(정방향 / 정밀 제어, 추천)apiyi-gpt-image-2-all-gen(역방향 / 경제 모드)
Skill 설치는 명령어 한 줄이면 충분하고, API 키 설정은 export 한 줄이면 끝납니다. 이제 OpenClaw에게 "4K 세라믹 컵 상품 이미지 하나 그려줘"라고 말하기만 하면, 에이전트가 자동으로 Skill을 선택하고 파라미터를 입력하며 파일을 저장합니다.
이 OpenClaw gpt-image-2 연동 튜토리얼을 따라 하시면 다음을 얻게 됩니다.
- "코드 작성 vs Skill 설치"의 명확한 비교를 통해 후자가 왜 더 나은지 이해
- 고품질 출력과 경제적인 일괄 처리 시나리오를 모두 커버하는 두 가지 즉시 사용 가능한 공식 Skill
- 5단계로 완료하는 최소 예제 (Node.js 및 Python 각 1개)
- 세 가지 실전 명령어 (4K 포스터 / 다중 참조 이미지 합성 / 일괄 초안 생성)
- Claude Code, Cursor에서 동일한 Skill 세트를 재사용하는 방법
1. 왜 Skills가 OpenClaw gpt-image-2 연동의 최적의 해법인가
1.1 OpenClaw의 Skills 체계: 에이전트에 날개를 달아주는 표준 방식
OpenClaw는 크로스 플랫폼 오픈소스 AI 어시스턴트(GitHub 저장소 github.com/openclaw/openclaw)로, 단순히 "또 하나의 채팅창"이 아니라 "에이전트에게 조합 가능한 도구 상자를 제공"하는 것을 목표로 합니다. 이 도구 상자의 기본 단위를 Skill이라고 부릅니다.
Skill의 본질은 다음과 같습니다.
skill-package/
├── SKILL.md # 에이전트에게 이 Skill의 기능을 설명
├── scripts/
│ ├── generate_image.js # Node.js 런타임
│ └── generate_image.py # Python 런타임
└── requirements.txt / package.json
"커피 컵 하나 그려줘"라고 말하면 OpenClaw는 다음과 같이 동작합니다.
- 설치된 모든 Skill의
SKILL.md요약을 스캔 - "이미지 생성" 작업에
apiyi-gpt-image-2-gen이 가장 적합하다고 판단 - 자연어에서 파라미터(크기, 품질, 출력 형식) 추출
- 해당
generate_image.js/py호출 - 생성된 이미지 경로를 반환
이 과정에서 코드를 작성하거나, 라우팅을 설정하거나, SDK를 조정할 필요가 없습니다. 이것이 전통적인 "플러그인 작성" 방식 대비 OpenClaw 생태계가 가진 핵심 강점입니다.
1.2 코드 작성 vs Skill 설치: 한눈에 보는 비교
| 비교 항목 | 직접 HTTP 코드 작성 | 공식 Skill 설치 |
|---|---|---|
| 시작 비용 | 최소 30분 | 명령어 1줄, 30초 |
| HTTP 세부 사항 | multipart, 재시도, 타임아웃 직접 처리 | Skill 내부에서 캡슐화 완료 |
| 참조 이미지 업로드 | base64 인코딩 직접 구현 | 파일 경로만 전달 |
| 다중 런타임 | Node 또는 Python 선택 | Node.js + Python 모두 지원 |
| 에이전트 인지 | 도구 설명 직접 작성 | SKILL.md 자체 포함 |
| 클라이언트 확장 | 환경 변경 시 재통합 | Claude Code / Cursor / OpenClaw 모두 호환 |
| 업데이트 경로 | OpenAI API 업데이트 직접 대응 | npx skills update 한 번으로 해결 |
| 회선 전환 | 코드 수정 | 환경 변수 수정 |
즉, 코드를 작성하는 것은 스스로 끊임없이 유지보수해야 하는 '글루(glue) 노동자'가 되는 길이고, Skill을 설치하는 것은 유지보수 작업을 전문 Skill 제작자에게 맡기는 것입니다.
1.3 두 Skill의 역할 분담: 도구를 먼저 선택하고 이미지를 생성하세요
APIYI 팀은 expert-skills-hub 저장소에 gpt-image-2를 위한 두 가지 Skill을 기여했으며, 각각 완전히 다른 시나리오를 지향합니다.
| Skill 이름 | 모델 별칭 | 포지셔닝 | 가격 모델 | 최적 시나리오 |
|---|---|---|---|---|
apiyi-gpt-image-2-gen |
gpt-image-2 |
정방향 / 정밀 제어 | 토큰당 과금 | 포스터, 상업 촬영, 커버, 4K 출력 |
apiyi-gpt-image-2-all-gen |
gpt-image-2-all |
역방향 / 경제 모드 | 고정 $0.03/장 | 일괄 컨셉 초안, 중국어 프롬프트, 초안 탐색 |
두 Skill은 동일한 APIYI_API_KEY를 공유하며, 백엔드는 APIYI 게이트웨이를 통합니다. 두 가지를 동시에 설치하여 OpenClaw 에이전트가 시나리오에 따라 자동으로 선택하게 할 수 있습니다. 포스터 생성은 정방향으로, 100장의 변형 이미지는 역방향으로 처리하는 식입니다.
{OpenClaw에 gpt-image-2를 연동합니다}
{Skills · 코딩 없이 · 자연어로 한 문장 만에 이미지 생성}
{OpenClaw}
{오픈소스 AI 어시스턴트}
{🧩 기술}
{APIYI-GPT-이미지-2-생성}
{정방향 · 정밀 제어 · 4K}
{APIYI-GPT-이미지-2-올-젠}
{반전 · 경제적 · $0.03/이미지}
{GPT}
{gpt-image-2}
{OpenAI · 2026}
{⚡ 노코드}
{자연어 트리거}
{⏱ 5분 만에 실행하기}
{apiyi.com}
{OpenClaw의 gpt-image-2 연동 · 두 가지 경로 비교}
{30분 걸리던 자체 구축에서 한 줄 명령어로 설치 완료까지, 2026년의 해답은 이미 바뀌었습니다}
{❌ HTTP 코드를 직접 작성하는 것}
{전통적인 방식 · 뒤로 갈수록 더 힘듦}
{✗}
{30분부터 시작}
{SDK 캡슐화 / 디버깅 / 최소 예제 실행}
{✗}
{참조 이미지를 멀티파트 방식으로 업로드}
{Base64 / form-data 직접 처리}
{✗}
{재시도 / 타임아웃 / 429 속도 제한}
{완벽한 에러 처리 루틴은 직접 작성해야 합니다.}
{✗}
{클라이언트 간 통합을 다시 수행해야 합니다}
{Claude Code / Cursor로 다시 시도해 보세요}
{✗}
{에이전트가 반드시 자율적으로 모델 호출을 할 수 있는 것은 아닙니다.}
{도구 설명은 직접 정성스럽게 작성해야 합니다.}
{2026}
{더 나은 해결책}
{✅ 공식 Skill 설치}
{2026 추천 · 사용할수록 가벼워지는 APIYI}
{✓}
{1줄 명령어로 30초 만에 설치 완료}
{npx skills add … –skill …}
{✓}
{HTTP 세부 사항 완전 캡슐화}
{참조 이미지는 파일 경로로 직접 전달하세요}
{✓}
{Node.js + Python 듀얼 런타임}
{동일한 Skill, 두 가지 호출 방식}
{✓}
{클라이언트 간 동일 소스 재사용}
{OpenClaw / Claude Code / Cursor}
{✓}
{에이전트 자동 스킬 선택}
{SKILL.md는 AI가 무엇을 사용해야 하는지 이해하도록 돕습니다}
{한 번의 설치 · 다중 클라이언트 재사용 · OpenClaw / Claude Code / Cursor 동일 소스 · APIYI 통합 백엔드}
1.4 백엔드: APIYI apiyi.com 3개 회선
두 Skill의 HTTP 요청은 기본적으로 APIYI의 메인 사이트인 api.apiyi.com으로 전송됩니다.
🎯 회선 제안: 프로덕션 환경에서는 OpenClaw의
APIYI_BASE_URL을 APIYI apiyi.com의 고성능 회선인vip.apiyi.com으로 변경하는 것을 권장합니다. 특히 일괄 이미지 생성 시 더욱 효과적입니다. 메인 사이트api.apiyi.com은 일상적인 단일 이미지 호출에 적합하며, VIP 회선vip.apiyi.com은 일괄/야간 큐 작업에,b.apiyi.com은 자동 적용되는 백업용으로 적합합니다. 세 회선 모두 하나의 키를 공유하므로 환경 변수 하나만 수정하면 바로 전환됩니다.
2. 5분 만에 OpenClaw에 gpt-image-2 연결하기
2.1 사전 환경 점검
OpenClaw에 gpt-image-2를 연결하기 전에, 먼저 환경이 준비되었는지 확인해 보세요.
| 항목 | 요구 사항 | 확인 명령어 |
|---|---|---|
| OpenClaw 설치 | 최신 버전 | openclaw --version |
| Node.js | 18+ | node --version |
| Python | 3.10+ (선택 사항) | python3 --version |
| npx | Node.js에 포함 | npx --version |
| 네트워크 | github.com 및 api.apiyi.com 접속 가능 여부 | curl -I api.apiyi.com |
| APIYI 키 | api.apiyi.com 콘솔에서 발급 |
sk- 접두사 확인 |
⚠️ 주의: 만약 사용 중인 OpenClaw 버전에서
npx skills명령어를 찾을 수 없다면, 최신 버전으로 업데이트(openclaw update)해 주세요. Skills CLI는 OpenClaw 2026 생태계의 핵심 기능이라 이전 버전에는 없을 수 있습니다.
2.2 Step 1: 명령어 한 줄로 Skill 설치하기
터미널을 열고 사용 환경에 맞는 Skill을 설치하세요. 두 가지 모두 설치하는 것을 권장합니다.
# 정방향 (일상적인 사용 권장)
npx skills add https://github.com/wuchubuzai2018/expert-skills-hub \
--skill apiyi-gpt-image-2-gen
# 역방향 (대량 작업/중국어 프롬프트에 최적화)
npx skills add https://github.com/wuchubuzai2018/expert-skills-hub \
--skill apiyi-gpt-image-2-all-gen
설치가 완료되면 Skill은 OpenClaw 기본 Skill 디렉토리(보통 ~/.openclaw/skills/)에 저장됩니다. 아래 명령어로 확인해 보세요.
npx skills list
# 예상 출력:
# - apiyi-gpt-image-2-gen ✓ installed
# - apiyi-gpt-image-2-all-gen ✓ installed
2.3 Step 2: API 키 설정
OpenClaw에 gpt-image-2를 연결하려면 환경 변수 하나만 설정하면 됩니다.
# macOS / Linux
export APIYI_API_KEY="sk-your-key-here"
# Windows PowerShell
$env:APIYI_API_KEY = "sk-your-key-here"
이 설정을 ~/.zshrc 또는 ~/.bashrc에 추가하여 영구적으로 적용하는 것을 추천합니다.
🎯 키 발급 단계: APIYI
apiyi.com에 접속하여 로그인 후, 콘솔 → API Keys → 새 키 생성을 클릭하세요. "사용량 제한" 기능을 활성화하여 OpenClaw 전용 키에 일일 한도(예: 50위안)를 설정해 두면 예기치 못한 과도한 사용을 방지할 수 있습니다.
3가지 라인 전환 옵션: 대량 작업 시 고성능이 필요하다면 아래 설정을 활용하세요.
export APIYI_BASE_URL="https://vip.apiyi.com/v1" # VIP 라인
# 또는
export APIYI_BASE_URL="https://b.apiyi.com/v1" # 예비 라인
설정하지 않으면 기본적으로 https://api.apiyi.com/v1을 사용합니다.
2.4 Step 3: 첫 번째 이미지 생성 (Node.js)
Skill을 설치하면 예제 스크립트가 함께 제공됩니다. 가장 간단한 확인 방법은 다음과 같습니다.
cd ~/.openclaw/skills/apiyi-gpt-image-2-gen
node scripts/generate_image.js \
-p "A minimalist poster with the text 'HELLO 2026' centered" \
-s "1024x1024" \
-q "medium" \
-o "png" \
-f "./hello_2026.png"
약 20~40초 후 터미널에 다음과 같은 메시지가 나타납니다.
✔ Image generated: ./hello_2026.png (1024x1024, png, 312 KB)
hello_2026.png 파일을 열어보세요. 중앙에 "HELLO 2026"이라는 글자가 선명하게 적힌 미니멀한 포스터가 보일 것입니다. 글자가 깨지지 않고 잘 나온다면 전체 경로(OpenClaw Skill → APIYI api.apiyi.com → OpenAI gpt-image-2)가 정상적으로 연결된 것입니다.
2.5 Step 4: 첫 번째 이미지 생성 (Python 버전)
Python 환경을 주로 사용하신다면, 동일한 Skill에 포함된 Python 스크립트를 사용하세요.
cd ~/.openclaw/skills/apiyi-gpt-image-2-gen
python3 scripts/generate_image.py \
-p "A minimalist poster with the text 'HELLO 2026' centered" \
-s "1024x1024" \
-q "medium" \
-o "png" \
-f "./hello_2026.png"
매개변수는 Node.js 버전과 완전히 동일하며, -p/-s/-q/-o/-f 단축 옵션 또는 긴 옵션(--prompt/--size/--quality/--output-format/--filename)을 사용할 수 있습니다.
💡 런타임 전환 불필요: 하나의 Skill 패키지에 두 스크립트가 모두 포함되어 있어, 프로젝트 내에서 Node(프론트엔드 친화적)와 Python(데이터 과학 친화적)을 자유롭게 섞어 써도 됩니다. OpenClaw의 gpt-image-2 Skill은 양쪽 모두에서 완벽하게 작동합니다.
2.6 Step 5: OpenClaw에서 자연어로 호출하기
위의 CLI 명령어는 Skill이 잘 작동하는지 확인하는 용도입니다. 실제로는 OpenClaw가 스스로 호출하게 만드는 것이 핵심입니다. OpenClaw를 실행한 후 자연어로 이렇게 말해 보세요.
사용자: gpt-image-2를 사용해서 4K 해상도의 세라믹 찻잔 상품 이미지를 그려줘.
아침 햇살 같은 부드러운 조명, 심플한 배경, PNG 형식으로 ./output/tea_cup.png에 저장해 줘.
OpenClaw: 알겠습니다. 요청하신 작업을 처리하기 위해 apiyi-gpt-image-2-gen Skill을 사용하겠습니다.
설정: size=3840x2160, quality=high, output-format=png
생성 중...
✔ 완료: ./output/tea_cup.png (3840x2160, 2.4 MB)
OpenClaw의 추론 엔진은 다음과 같이 작동합니다:
- 작업 유형(이미지 생성) 식별
- 두 Skill의
SKILL.md를 비교하여apiyi-gpt-image-2-gen선택 (4K + PNG 요구사항 충족) - "4K"를
3840x2160으로 변환하고, "아침 햇살"을 프롬프트에 반영 generate_image.js실행 후 파일 경로 반환
과정 전체에서 사용자는 한국어 문장 하나만 입력했을 뿐, 복잡한 Python이나 Node 코드는 전혀 작성하지 않았습니다. 이것이 바로 OpenClaw와 gpt-image-2를 Skill로 연결하는 핵심 가치입니다.
3. OpenClaw 호출 gpt-image-2 파라미터 빠른 참조
3.1 정방향(Forward) Skill: apiyi-gpt-image-2-gen
정밀 제어형으로, 기본적으로 이 방식을 사용하는 것을 권장합니다. 전체 파라미터 표는 다음과 같습니다.
| 옵션 | 긴 옵션 | 값 범위 | 기본값 | 설명 |
|---|---|---|---|---|
-p |
--prompt |
텍스트 | 필수 | 이미지 설명, 영어+한국어 키워드 혼용 권장 |
-s |
--size |
WIDTHxHEIGHT |
1024x1024 |
16의 배수, 최대 3840x3840 이내 |
-q |
--quality |
low/medium/high/auto | auto |
포스터는 high, 초안은 low 권장 |
-o |
--output-format |
png/jpeg/webp | png |
투명 배경은 반드시 png 사용 |
-c |
--output-compression |
0-100 | 85 |
jpeg/webp에만 적용 |
-i |
--input-image |
경로(중복 가능) | 없음 | 최대 5장의 참조 이미지 |
-m |
--mask |
경로 | 없음 | 흑백 마스크, 흰색=편집 영역 |
-f |
--filename |
경로 | ./output.png |
출력 파일 |
자주 사용하는 사이즈 참조:
| 용도 | 추천 사이즈 |
|---|---|
| 카카오톡 프로필 | 1080x1080 |
| 인스타그램 피드 | 1080x1350 |
| 유튜브 썸네일 | 1920x1080 |
| 블로그 대표 이미지 | 1600x900 |
| 4K 포스터 | 3840x2160 |
| 긴 배너 | 2400x800 |
| 스마트폰 배경화면 | 1170x2532 |
3.2 역방향(Reverse) Skill: apiyi-gpt-image-2-all-gen
경제적인 대량 생성형으로, 장당 약 $0.03의 비용이 발생합니다. 파라미터가 더 간결합니다.
| 옵션 | 긴 옵션 | 값 범위 | 설명 |
|---|---|---|---|
-p |
--prompt |
텍스트 | 설명, 사이즈/비율을 텍스트에 직접 기재 |
-r |
--response-format |
url / b64_json | url은 24시간 CDN 링크, b64_json은 Base64 반환 |
-i |
--input-image |
경로(중복 가능) | 최대 5장의 참조 이미지 |
-f |
--filename |
경로 | 출력 파일 (url 모드 시 자동 다운로드) |
역방향 Skill은 -s/-q/-o 옵션을 제공하지 않습니다. 기본 모델이 대화형이므로 사이즈는 프롬프트 내에서 직접 지정해야 합니다.
# 올바른 예시
-p "16:9 가로형 배경화면 생성, SF 도시 야경, 네온 조명"
# 잘못된 예시 (역방향 모드는 -s를 지원하지 않음)
-p "SF 도시 야경" -s "1920x1080" # ❌
3.3 실전 명령어 3가지
실전 1: 4K 영화 포스터 (정방향)
node scripts/generate_image.js \
-p "Cinematic poster for sci-fi novel 'NEON HORIZON', \
dark blue and magenta gradient sky, lone silhouette on cliff, \
bold serif title centered at top, subtle tagline bottom, \
35mm film grain" \
-s "3840x5760" \
-q "high" \
-o "png" \
-f "./poster_neon_horizon.png"
- 2:3 비율 4K 세로형
- quality=high로 텍스트 선명도 확보
- 약 3~5분 소요 (4K 생성 시간은 quality와 밀접한 관련)
실전 2: 마스크 부분 재작성 (정방향 + 이미지 + 마스크)
node scripts/generate_image.js \
-p "Replace the background with luxurious white marble countertop, \
soft natural window light from the left, \
keep product subject pixel-stable" \
-i "./coffee_cup.png" \
-m "./coffee_cup_mask.png" \
-s "2048x2048" \
-q "high" \
-f "./coffee_cup_marble.png"
- 흰색 픽셀 = 변경할 배경
- 검은색 픽셀 = 상품 본체 (픽셀 고정)
- gpt-image-2는 상품 형태를 훼손하지 않습니다.
실전 3: 대량 컨셉 초안 생성 (역방향 + 루프)
# 의상 컨셉 100개, 장당 $0.03, 총 비용 약 $3
for i in $(seq 1 100); do
node scripts/generate_image.js \
-p "사이버펑크 캐릭터 디자인 초안 #${i}, 개량 한복, 네온 톤, 전신 입화" \
-r "url" \
-f "./concepts/concept_${i}.png"
done
- 역방향 Skill은 한국어 프롬프트 지원이 더 안정적입니다.
-r url모드에서는 스크립트가 로컬로 자동 다운로드합니다.- 대량 생성 시
APIYI_BASE_URL=https://vip.apiyi.com/v1설정을 권장합니다.
4. OpenClaw와 gpt-image-2의 고급 조합
4.1 Agent가 스스로 Skill을 선택하게 하기
정방향과 역방향 Skill을 모두 설치하면, OpenClaw가 사용자의 언어에 따라 자동으로 적절한 Skill을 선택합니다. Agent가 더 정확하게 선택하도록 하려면 요청 시 프롬프트 신호를 포함하세요.
| 사용자의 표현 | Agent의 선택 경향 |
|---|---|
| "고품질", "4K", "포스터", "상업 촬영" | 정방향 apiyi-gpt-image-2-gen |
| "초안", "대량", "컨셉", "한국어" | 역방향 apiyi-gpt-image-2-all-gen |
| "일단 10장만 보여줘" | 역방향 (경제적) |
| "마스크로 배경 변경" | 정방향 (역방향은 마스크 미지원) |
| "장당 $0.03 고정" | 역방향 |
🎯 프롬프트 팁: 키워드에 "정밀 제어" 또는 "경제적 대량 생성"과 같은 용어를 포함하면 OpenClaw가 거의 100% 확률로 해당 Skill을 정확히 선택합니다.
docs.apiyi.com의 Skill 생태계 섹션에서 더 많은 트리거 단어를 확인해 보세요.
4.2 Skill 체인: 이미지 생성 → OCR → 번역
Skill은 Agent에 의해 자유롭게 조합될 수 있으므로, OpenClaw와 gpt-image-2를 연결하여 다단계 파이프라인을 구축할 수 있습니다. 예: "영어 문구가 포함된 포스터를 생성한 뒤, 동일한 구도로 일본어 버전 생성"
사용자: "Less is more"라는 영어 문구가 담긴 미니멀 포스터를 생성하고,
동일한 구도에 문구만 일본어로 바꾼 버전을 생성해 줘.
OpenClaw:
Step 1: apiyi-gpt-image-2-gen (영어 버전)
→ ./en_poster.png
Step 2: apiyi-gpt-image-2-gen (일본어 버전, en_poster.png를 참조 이미지로 사용)
-i ./en_poster.png
-p "Same layout, replace text with 'より少なく、より豊かに'"
→ ./jp_poster.png
이것이 Skill 생태계의 가장 강력한 점입니다. 개별 Skill은 하나의 기능만 수행하고, Agent가 이를 조합해 복잡한 워크플로우를 완성합니다.
4.3 CI/CD에 Skill 통합하기
두 Skill의 스크립트는 표준 CLI 기반이므로 CI/CD 파이프라인에 매끄럽게 통합할 수 있습니다.
# .github/workflows/generate-og-image.yml
name: Generate OG image on release
on:
release:
types: [published]
jobs:
og-image:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '20' }
- run: npx skills add https://github.com/wuchubuzai2018/expert-skills-hub --skill apiyi-gpt-image-2-gen
- env:
APIYI_API_KEY: ${{ secrets.APIYI_API_KEY }}
run: |
node ~/.openclaw/skills/apiyi-gpt-image-2-gen/scripts/generate_image.js \
-p "Release ${{ github.event.release.tag_name }} cover image" \
-s "1200x630" \
-q "high" \
-f "./og-image.png"
- uses: actions/upload-artifact@v4
with: { name: og-image, path: ./og-image.png }
릴리스 때마다 자동으로 OG 이미지가 생성되며, Agent와 CI가 동일한 Skill 정의를 공유합니다.
4.4 Claude Code 및 Cursor에서 재사용
본 가이드는 OpenClaw에 초점을 맞췄지만, apiyi-gpt-image-2-gen / apiyi-gpt-image-2-all-gen 두 Skill은 범용 Skill 표준을 완전히 준수하므로 다음과 같이 활용 가능합니다.
| 클라이언트 | 지원 여부 | 비고 |
|---|---|---|
| OpenClaw | ✅ | 본 가이드의 메인 환경 |
| Claude Code | ✅ | ~/.claude/skills/에 배치 시 즉시 사용 |
| Cursor | ✅ | Rules 파일을 통한 참조 |
| Windsurf | ✅ | Skill 규격 호환 |
| 자체 구축 Agent (LangChain 등) | ⚠️ | Tool Adapter 래핑 필요 |
"한 번 설치로 여러 클라이언트에서 재사용"할 수 있어, 주력 도구를 변경해도 이미지 생성 기능을 그대로 가져갈 수 있습니다.
五、OpenClaw 接入 gpt-image-2 常见问题 FAQ
Q1：npx skills add 报 "command not found"？
确保 OpenClaw 已升级到最新版（openclaw update），旧版没有 Skills CLI。如果仍然报错，可以手动克隆仓库到 ~/.openclaw/skills/ 目录作为兜底。
Q2：跑脚本提示 "APIYI_API_KEY is not set"？
三步排查：
echo $APIYI_API_KEY看变量是否导出成功- 确认 Key 带
sk-前缀 - 如果刚写入
~/.zshrc，开个新终端让它生效
Q3：如何把调用切到 vip.apiyi.com 高并发线路？
两种方式：
# 方式 1：全局环境变量
export APIYI_BASE_URL="https://vip.apiyi.com/v1"
# 方式 2：单次调用前缀
APIYI_BASE_URL="https://vip.apiyi.com/v1" node scripts/generate_image.js ...
备用域名同理：b.apiyi.com。三个域名共用同一把 Key，主站抖动时手工切到 VIP 通常能立刻恢复，具体策略也可以参考 APIYI 官方文档 docs.apiyi.com 的线路切换指南。
Q4：反转和正转到底怎么选？
对照这张决策表：
| 如果你需要… | 选 |
|---|---|
精确控制分辨率（比如 1920x1080） |
正转 |
| 使用 Mask 局部重绘 | 正转 |
| 4K 以上高质量海报 | 正转 |
| 批量跑 50+ 张 | 反转 |
| 中文 프롬프트 占主导 | 反转 |
| 成本可预测（$0.03/张） | 反转 |
最省心的做法：两个都装，让 OpenClaw Agent 根据你的自然语言自动选。
Q5：能在 Claude Code 里用吗？
可以。把 Skill 包从 ~/.openclaw/skills/ 软链接或复制到 ~/.claude/skills/，Claude Code 会自动识别 SKILL.md 并把它注册为可调用工具。同一把 APIYI_API_KEY 共用。
Q6：Skill 安全吗？
社区 Skill 生态需要警惕。2026 年 2 月曾曝出 341 个恶意 Skill 通过 ClawHub 分发 Atomic Stealer 恶意软件。建议：
- 只装来自可信仓库的 Skill（本文的
wuchubuzai2018/expert-skills-hub是 APIYI 官方源） - 安装后审阅
SKILL.md和 scripts 内容，尤其注意curl | bash或连接陌生域名的代码 - 用
npx skills inspect <skill-name>查看 Skill 会访问哪些网络地址
官方 APIYI Skill 的所有请求都只打向 *.apiyi.com，可以安全审计。
Q7：4K 出图很慢怎么办？
- 正常现象。
quality=high+3840x2160大约需要 3–5 分钟 - 在脚本外层加超时保护（Bash 里
timeout 360 node ...） - 如果需要快速预览，先用
size=2048x1152 quality=medium出草图，确认效果再升 4K
Q8：如何做成本监控？
在 APIYI apiyi.com 控制台开启「日预算告警」和「按 Key 统计」。给 OpenClaw 专用 Key 单独设额度，既能观察消耗，也能在意外情况下及时停损。
六、OpenClaw 接入 gpt-image-2 总结
回过头看，OpenClaw 接入 gpt-image-2 在 2026 年的最佳路径已经从"写代码"转向"装 Skill"。原因非常朴素：
- 更快：
npx skills add+export KEY两条命令，30 秒完成 - 更稳：HTTP 细节、重试策略、参数校验全都封在 Skill 里，升级跟着 Skill 作者走
- 更广：同一个 Skill 在 OpenClaw / Claude Code / Cursor 里通用
- 更聪明：Agent 看得懂
SKILL.md，能自己决定什么时候用、用哪一个
APIYI 贡献的两个 Skill apiyi-gpt-image-2-gen（精细控制）与 apiyi-gpt-image-2-all-gen（经济批量）正好覆盖了最常见的两类场景。同时安装它们就是目前最省心的起点——后续不管是 4K 海报还是 100 张概念稿，OpenClaw Agent 都能自动选对 Skill。
🎯 落地建议：先去 APIYI
apiyi.com申请一把测试 Key（建议设置 ¥20–50 的日上限），按本文 §2 的 5 步跑通最小示例；确认链路通畅后，回到 §3 的实战命令尝试 4K 海报和 Mask 重绘；遇到线路抖动时随时把APIYI_BASE_URL切到vip.apiyi.com或b.apiyi.com。需要更复杂的 Skill 组合或 CI/CD 样例，可以查阅 APIYI 官方文档docs.apiyi.com的 Skills 生态专栏。
至此，你已经拥有一套完整的、跨客户端可复用的 OpenClaw gpt-image-2 接入方案。接下来要做的唯一事情，就是把"写一个图像调用工具"这件事从你的 todo list 上永久删掉——交给 Skill 就好。
作者: APIYI 技术团队
相关资源:
- Skills 仓库: github.com/wuchubuzai2018/expert-skills-hub
- OpenClaw 主页: github.com/openclaw/openclaw
- APIYI 官网: apiyi.com
- APIYI 文档: docs.apiyi.com
- APIYI 主站: api.apiyi.com（备用 vip.apiyi.com / b.apiyi.com）
