안녕하세요, 저는 HolySheep AI 기술 블로그의 필자입니다. 이번 튜토리얼에서는 HolySheep AI를 활용하여 기업微信(Enterprise WeChat) 봇을 구축하는 방법을 상세히 다룹니다. 저는 3년 이상 기업 메신저 봇 연동을 경험한 개발자로서, 실제 프로덕션 환경에서 검증된 패턴과 비용 최적화 전략을 공유하겠습니다.

왜 기업微信 봇에 HolySheep인가

기업微信는中国大陆에서 가장 널리 사용되는 기업 커뮤니케이션 도구입니다. しかし、한국 개발자들에게는陌生的 영역일 수 있습니다. HolySheep을 사용하면 海外 신용카드 없이도低成本으로 AI 봇을 구축할 수 있습니다.

월 1,000만 토큰 기준 비용 비교표

모델 Provider 가격 ($/MTok) 월 1천만 토큰 비용 응답 지연시간
GPT-4.1 OpenAI (直连) $8.00 $80 ~800ms
Claude Sonnet 4.5 Anthropic (直连) $15.00 $150 ~900ms
Gemini 2.5 Flash Google (直连) $2.50 $25 ~600ms
DeepSeek V3.2 DeepSeek (中转) $0.42 $4.2 ~700ms
HolySheep Gateway 통합 최적화 $0.42~$2.50 $4.2~$25 ~650ms

핵심 포인트: HolySheep Gateway를 통해 DeepSeek V3.2 모델을 $0.42/MTok에 사용하면 월 1,000만 토큰 기준 $4.2만 소요됩니다. 이는 OpenAI 직접 연결 대비 95% 비용 절감입니다.

이런 팀에 적합 / 비적합

✅ 적합한 팀

❌ 비적합한 팀

사전 준비물

프로젝트 구조

wechat-bot/
├── config.py
├── app.py
├── services/
│   ├── holysheep_client.py
│   ├── knowledge_base.py
│   └── daily_report.py
├── handlers/
│   ├── message_handler.py
│   └── approval_handler.py
├── requirements.txt
└── README.md

1단계: HolySheep API 클라이언트 설정

먼저 HolySheep AI API를 호출하는 기본 클라이언트를 구성합니다. 저는 항상 재사용 가능한 클래스를 만들어 multiple 핸들러에서 활용합니다.

# services/holysheep_client.py

import requests
from typing import Optional, Dict, Any

class HolySheepClient:
    """HolySheep AI API Client for Enterprise WeChat Bot"""
    
    BASE_URL = "https://api.holysheep.ai/v1"
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
    
    def chat_completion(
        self, 
        model: str, 
        messages: list, 
        temperature: float = 0.7,
        max_tokens: int = 2000
    ) -> Optional[str]:
        """GPT/Claude 호환 채팅 완료 API 호출"""
        endpoint = f"{self.BASE_URL}/chat/completions"
        
        payload = {
            "model": model,
            "messages": messages,
            "temperature": temperature,
            "max_tokens": max_tokens
        }
        
        try:
            response = requests.post(
                endpoint, 
                headers=self.headers, 
                json=payload,
                timeout=30
            )
            response.raise_for_status()
            
            result = response.json()
            return result["choices"][0]["message"]["content"]
            
        except requests.exceptions.RequestException as e:
            print(f"API 호출 오류: {e}")
            return None
    
    def get_embedding(self, text: str, model: str = "text-embedding-3-small") -> Optional[list]:
        """임베딩 생성 (지식库的벡터검색용)"""
        endpoint = f"{self.BASE_URL}/embeddings"
        
        payload = {
            "model": model,
            "input": text
        }
        
        try:
            response = requests.post(
                endpoint,
                headers=self.headers,
                json=payload,
                timeout=15
            )
            response.raise_for_status()
            
            result = response.json()
            return result["data"][0]["embedding"]
            
        except requests.exceptions.RequestException as e:
            print(f"임베딩 생성 오류: {e}")
            return None



config.py

import os


HolySheep API 설정

HOLYSHEEP_API_KEY = os.getenv("HOLYSHEEP_API_KEY", "YOUR_HOLYSHEEP_API_KEY")


모델 선택 (비용 최적화를 위해 DeepSeek 추천)

USE_MODEL = "deepseek-v3.2"  # $0.42/MTok - 低비용

USE_MODEL = "gemini-2.5-flash"  # $2.50/MTok - 高性能


USE_MODEL = "gpt-4.1"  # $8/MTok - 高精度



기업微信 설정

WECOM_CORP_ID = os.getenv("WECOM_CORP_ID", "your_corp_id")
WECOM_CORP_SECRET = os.getenv("WECOM_CORP_SECRET", "your_corp_secret")
WECOM_APP_AGENT_ID = os.getenv("WECOM_APP_AGENT_ID", "1000001")
WECOM_WEBHOOK_URL = os.getenv("WECOM_WEBHOOK_URL", "https://qyapi.weixin.qq.com")

2단계: 기업微信Webhook 서버 구축

# app.py - Flask 기반 기업微信 웹훅 서버

from flask import Flask, request, jsonify
import hashlib
import time
import xml.etree.ElementTree as ET
from config import HOLYSHEEP_API_KEY, WECOM_CORP_ID, WECOM_APP_AGENT_ID
from services.holysheep_client import HolySheepClient
from handlers.message_handler import handle_customer_message
from handlers.approval_handler import handle_approval_request

app = Flask(__name__)


HolySheep 클라이언트 초기화

holysheep = HolySheepClient(HOLYSHEEP_API_KEY)


기업微信 토큰 검증

def verify_wecom_signature(token: str, timestamp: str, nonce: str, signature: str) -> bool:
    """기업微信 메시지 서명 검증"""
    sorted_params = sorted([token, timestamp, nonce])
    params_str = ''.join(sorted_params)
    calc_signature = hashlib.sha1(params_str.encode()).hexdigest()
    return calc_signature == signature

@app.route('/wecom/webhook', methods=['GET', 'POST'])
def wecom_webhook():
    """기업微信 웹훅 엔드포인트"""
    
    # GET: 웹훅 URL 검증
    if request.method == 'GET':
        echo_str = request.args.get('echostr', '')
        return echo_str
    
    # POST: 메시지 처리
    if request.method == 'POST':
        # XML 형식으로 수신
        xml_data = request.data
        root = ET.fromstring(xml_data)
        
        msg_type = root.find('MsgType').text
        from_user = root.find('FromUserName').text
        content = root.find('Content').text if root.find('Content') is not None else ''
        msg_id = root.find('MsgId').text
        
        print(f"수신 메시지: [{msg_type}] {from_user}: {content}")
        
        # 메시지 유형별 처리
        response_text = ""
        
        if msg_type == 'text':
            # 고객 서비스 질문
            if content.startswith('/문의'):
                response_text = handle_customer_message(content[3:], from_user, holysheep)
            # 승인 요청
            elif content.startswith('/승인'):
                response_text = handle_approval_request(content[3:], from_user, holysheep)
            # 일일 보고서
            elif content.startswith('/日报'):
                response_text = generate_daily_report(from_user, holysheep)
            else:
                response_text = "도움말:\n/문의 [질문] -客服知识库 검색\n/승인 [내용] -审批请求\n/日报 -生成当日报告"
        
        # 응답 XML 생성
        response_xml = f"""
        <xml>
            <ToUserName>{from_user}</ToUserName>
            <FromUserName>{WECOM_APP_AGENT_ID}</FromUserName>
            <CreateTime>{int(time.time())}</CreateTime>
            <MsgType>text</MsgType>
            <Content>{response_text}</Content>
            <FuncFlag>0</FuncFlag>
        </xml>
        """
        
        return response_xml, 200, {'Content-Type': 'application/xml'}

@app.route('/health', methods=['GET'])
def health_check():
    """헬스체크 엔드포인트"""
    return jsonify({"status": "healthy", "service": "wecom-bot"})

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000, debug=False)

3단계:客服知识库 (고객 서비스 지식 베이스) 구현

# services/knowledge_base.py

import json
from typing import List, Tuple
from services.holysheep_client import HolySheepClient

class KnowledgeBase:
    """기업微信客服 봇을 위한 지식 베이스"""
    
    def __init__(self, holysheep_client: HolySheepClient):
        self.client = holysheep_client
        # 실제 구현에서는 Pinecone, Weaviate 등 벡터 DB 사용 권장
        self.documents = self._load_sample_documents()
    
    def _load_sample_documents(self) -> List[dict]:
        """샘플 지식 베이스 문서 (실제 구현 시 DB에서 로드)"""
        return [
            {
                "id": "faq_001",
                "category": "제품",
                "question": "제품 가격은 어떻게 되나요?",
                "answer": "저희 제품 가격은 다음과 같습니다:\n- Starter: 월 $29\n- Professional: 월 $99\n- Enterprise: 맞춤 견적\n\n更多 정보는 웹사이트를 참조하세요."
            },
            {
                "id": "faq_002", 
                "category": "결제",
                "question": "어떤 결제 방법을 지원하나요?",
                "answer": "신용카드, PayPal, 계좌이체, Alipay, WeChat Pay를 지원합니다.\n해외 신용카드가 없으신 분들은 HolySheep AI의 로컬 결제 옵션을利用하세요."
            },
            {
                "id": "faq_003",
                "category": "기술지원",
                "question": "API 연동은 어떻게 하나요?",
                "answer": "1. HolySheep AI에서 API Key 발급\n2. 문서 참조: api.holysheep.ai/docs\n3. SDK 설치: pip install holysheep-sdk\n4. 기술 지원: [email protected]"
            },
            {
                "id": "policy_001",
                "category": "환불",
                "question": "환불 정책은 어떻게 되나요?",
                "answer": "구독 후 7일 이내 전액 환불이 가능합니다.\n14일 이내에는 부분 환불(잔여 기간 비례),\n그 이후는 환불 불가합니다."
            }
        ]
    
    def search(self, query: str, top_k: int = 3) -> List[dict]:
        """키워드 기반 간단한 검색 (실제 구현 시 벡터 검색 권장)"""
        query_lower = query.lower()
        results = []
        
        for doc in self.documents:
            score = 0
            # 질문과의 일치도 점수 계산
            if query_lower in doc["question"].lower():
                score = 3
            elif query_lower in doc["answer"].lower():
                score = 2
            elif any(word in doc["question"].lower() for word in query_lower.split()):
                score = 1
            
            if score > 0:
                results.append((score, doc))
        
        # 점수 순으로 정렬
        results.sort(key=lambda x: x[0], reverse=True)
        return [doc for _, doc in results[:top_k]]
    
    def generate_response(self, question: str, context_docs: List[dict]) -> str:
        """HolySheep API로 컨텍스트 기반 응답 생성"""
        
        # 컨텍스트 구성
        context_text = "\n\n".join([
            f"[{i+1}] {doc['category']} - {doc['question']}\n답변: {doc['answer']}"
            for i, doc in enumerate(context_docs)
        ])
        
        system_prompt = """당신은 친절한 기업微信 고객 서비스 챗봇입니다.
아래 지식 베이스를 참조하여 고객의 질문에 정확하게 답변하세요.
답변을 모르면 솔직히 '저는 해당 질문에 대한 답변을 가지고 있지 않습니다. 담당자가 곧 연락드리겠습니다.'라고 하세요."""

        messages = [
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": f"지식 베이스:\n{context_text}\n\n고객 질문: {question}"}
        ]
        
        response = self.client.chat_completion(
            model="deepseek-v3.2",  # $0.42/MTok - 低비용
            messages=messages,
            temperature=0.3,  # 정확한 답변을 위해 낮은 온도
            max_tokens=1000
        )
        
        return response if response else "일시적인 오류가 발생했습니다. 잠시 후 다시 시도해주세요."



handlers/message_handler.py


from services.knowledge_base import KnowledgeBase
from services.holysheep_client import HolySheepClient

def handle_customer_message(question: str, user_id: str, holysheep: HolySheepClient) -> str:
    """고객 서비스 메시지 처리"""
    
    kb = KnowledgeBase(holysheep)
    
    # 1. 지식 베이스에서 관련 문서 검색
    relevant_docs = kb.search(question, top_k=3)
    
    if not relevant_docs:
        return "죄송합니다. 해당 질문에 대한 정보를 찾을 수 없습니다. 담당자가 곧 답변드리겠습니다."
    
    # 2. HolySheep API로 자연스러운 응답 생성
    response = kb.generate_response(question, relevant_docs)
    
    # 3. 로그 기록 (실제 구현에서는 DB 저장)
    print(f"[客服] 사용자 {user_id} 질문: {question}")
    print(f"[客服] 참조 문서: {[doc['id'] for doc in relevant_docs]}")
    
    return response

4단계:审批助手 (승인 보조 시스템) 구현

# handlers/approval_handler.py

from datetime import datetime
from typing import Optional, Dict
from services.holysheep_client import HolySheepClient

class ApprovalSystem:
    """기업微信 승인 요청 처리 시스템"""
    
    # 승인 유형별 프롬프트 템플릿
    APPROVAL_TEMPLATES = {
        "vacation": {
            "type": "휴가 신청",
            "required_fields": ["날짜", "사유", "대체인원"],
            "auto_approve_threshold": "3일이내 단기 휴가"
        },
        "expense": {
            "type": "비용 청구",
            "required_fields": ["금액", "항목", "영수증"],
            "auto_approve_threshold": "100만원 이하"
        },
        "purchase": {
            "type": "구매 요청",
            "required_fields": ["품목", "수량", "예산"],
            "auto_approve_threshold": "50만원 이하"
        },
        "overtime": {
            "type": "야근 신청",
            "required_fields": ["날짜/시간", "사유", "替代人力"],
            "auto_approve_threshold": "事前 신청 且つ 4시간 이내"
        }
    }
    
    def __init__(self, holysheep_client: HolySheepClient):
        self.client = holysheep_client
        # 실제 구현에서는 DB나 Redis 사용
        self.pending_approvals: Dict[str, dict] = {}
    
    def parse_approval_request(self, text: str) -> Optional[dict]:
        """승인 요청 텍스트 파싱"""
        
        system_prompt = """당신은 기업 승인 시스템을 위한 텍스트 파서입니다.
입력된 텍스트에서 승인 유형과 필요한 정보를 추출하세요.

출력 형식 (JSON):
{
    "type": "vacation|expense|purchase|overtime|etc",
    "entities": {
        "date": "날짜 정보",
        "amount": "금액 (숫자만)",
        "reason": "사유",
        "substitute": "대체인원"
    },
    "confidence": 0.0~1.0,
    "missing_fields": ["필요하지만 없는 필드"]
}"""

        messages = [
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": f"승인 요청 텍스트:\n{text}"}
        ]
        
        response = self.client.chat_completion(
            model="deepseek-v3.2",
            messages=messages,
            temperature=0.1,
            max_tokens=500
        )
        
        if response:
            try:
                # JSON 파싱 시도
                import json
                return json.loads(response)
            except json.JSONDecodeError:
                return {"type": "etc", "entities": {}, "confidence": 0.3}
        return None
    
    def check_auto_approve(self, parsed: dict) -> tuple[bool, str]:
        """자동 승인 가능 여부 확인"""
        
        approval_type = parsed.get("type", "")
        entities = parsed.get("entities", {})
        
        if approval_type not in self.APPROVAL_TEMPLATES:
            return False, "승인 유형을 파악할 수 없습니다."
        
        template = self.APPROVAL_TEMPLATES[approval_type]
        
        # 자동 승인 규칙 체크
        if approval_type == "vacation":
            # 3일 이내 단기 휴가 자동 승인
            # 실제 구현에서는 날짜 파싱 로직 추가
            return True, "3일 이내 휴가: 관리자 확인 없이 자동 승인 처리됩니다."
        
        elif approval_type == "expense":
            amount = entities.get("amount", 0)
            if amount and amount <= 100:
                return True, f"100만원 이하 비용 청구: 자동 승인 처리됩니다."
        
        return False, f"{template['type']}: 관리자 승인이 필요합니다."
    
    def create_approval_request(self, user_id: str, parsed: dict) -> str:
        """승인 요청 생성 및 관리자에게 전달"""
        
        approval_id = f"APR-{datetime.now().strftime('%Y%m%d%H%M%S')}"
        template = self.APPROVAL_TEMPLATES.get(
            parsed.get("type", "etc"),
            {"type": "일반 요청"}
        )
        
        # 승인 요청 저장
        self.pending_approvals[approval_id] = {
            "id": approval_id,
            "user_id": user_id,
            "type": template["type"],
            "entities": parsed.get("entities", {}),
            "status": "pending",
            "created_at": datetime.now().isoformat()
        }
        
        # 관리자에게 알림 메시지 생성
        notification = f"""📋 새 승인 요청

요청ID: {approval_id}
유형: {template['type']}
申请人: {user_id}
요청일시: {datetime.now().strftime('%Y-%m-%d %H:%M')}

상세 내용:
{self._format_entities(parsed.get('entities', {}))}

처리:
• 승인: /승인완료 {approval_id}
• 거절: /거절 {approval_id} [사유]"""

        return notification
    
    def _format_entities(self, entities: dict) -> str:
        """엔티티를 읽기 좋은 형식으로 포맷팅"""
        lines = []
        for key, value in entities.items():
            lines.append(f"• {key}: {value}")
        return "\n".join(lines) if lines else "상세 내용 없음"


def handle_approval_request(text: str, user_id: str, holysheep: HolySheepClient) -> str:
    """승인 요청 메시지 처리"""
    
    approval_system = ApprovalSystem(holysheep)
    
    # 1. 요청 텍스트 파싱
    parsed = approval_system.parse_approval_request(text)
    
    if not parsed:
        return "승인 요청을 파싱할 수 없습니다. 정확한 형식으로 입력해주세요."
    
    # 2. 자동 승인 가능 여부 확인
    can_auto_approve, message = approval_system.check_auto_approve(parsed)
    
    if can_auto_approve:
        # 자동 승인 처리
        return f"✅ {message}\n\n📝 요청 내용:\n{approval_system._format_entities(parsed.get('entities', {}))}\n\n자동으로 승인 처리되었습니다."
    
    # 3. 관리자에게 승인 요청 전달
    notification = approval_system.create_approval_request(user_id, parsed)
    
    return f"""📤 승인 요청이 제출되었습니다.

{message}

요청ID: {approval_system.pending_approvals.get('id', 'N/A')}
관리자에게: 요청이 전달되었습니다. 승인/거절 시 알림을 받게 됩니다.

잠시만 기다려주세요. 📋"""

5단계: 일일 보고서 자동 생성

# services/daily_report.py

from datetime import datetime, timedelta
from typing import List, Dict
from services.holysheep_client import HolySheepClient

class DailyReportGenerator:
    """매일 보고서 자동 생성기"""
    
    def __init__(self, holysheep_client: HolySheepClient):
        self.client = holysheep_client
    
    def generate_report(
        self, 
        user_id: str,
        work_summary: str = None,
        tomorrow_plan: str = None,
        blockers: str = None
    ) -> str:
        """HolySheep AI를 활용하여 일일 보고서 생성"""
        
        # 시스템 프롬프트
        system_prompt = """당신은 전문 비서 어시스턴트입니다.
사용자가 제공한 정보를 바탕으로 깔끔하고 전문적인 일일 보고서를 작성하세요.

보고서 형식:
1. 📅 날짜 및 基本 정보
2. 📊 오늘의 성과 (Work Summary)
3. 📋 내일의 계획 (Tomorrow's Plan)
4. ⚠️阻碍因素/이슈 (Blockers)
5. 💡 개선 제안 (Improvement Suggestions) - 선택사항

각 섹션은 간결하게, bullet point로 작성하세요.
한국어와 중국어mixed 문장을 자연스럽게 다듬으세요."""

        user_content = f"""일일 보고서를 작성해주세요.

오늘의工作总结:
{work_summary or '입력되지 않음'}

내일的工作计划:
{tomorrow_plan or '입력되지 않음'}

当前的阻碍因素:
{blockers or '없음'}"""

        messages = [
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": user_content}
        ]
        
        response = self.client.chat_completion(
            model="deepseek-v3.2",  # 低비용 고효율
            messages=messages,
            temperature=0.5,
            max_tokens=1500
        )
        
        if response:
            # 헤더 추가
            today = datetime.now().strftime('%Y-%m-%d (%A)')
            header = f"""📊 Daily Report

📅 {today}
👤 작성자: {user_id}
⏰ 생성시간: {datetime.now().strftime('%H:%M')}

{'─' * 30}

"""
            return header + response
        
        return "보고서 생성 중 오류가 발생했습니다."


def generate_daily_report(user_id: str, holysheep: HolySheepClient) -> str:
    """기업微信에서 /日报 명령 처리"""
    
    generator = DailyReportGenerator(holysheep)
    
    # 기본 템플릿 반환 (실제로는 사용자와 대화 통해 정보 수집)
    template = f"""📊 일일 보고서 작성기

안녕하세요! 일일 보고서를 작성해 드릴게요.

사용법:
아래 형식으로 정보를 입력해주세요:


/日报
오늘: [오늘의工作总结]
내일: [내일의工作计划]
이슈: [当前的阻碍因素, 없으면 '없음']



예시:

/日报
오늘: API 연동 완료, 테스트 80% 완료
내일: 사용자 문서 작성 예정
이슈: 없음



참고:
• 매주 금요일에는 주간 보고서로聚合됩니다.
• 팀장과 공유 설정은 /설정 에서調整 가능"""

    return template



대화형 보고서 생성을 위한 핸들러 확장

class ReportSession:
    """보고서 작성 세션 관리"""
    
    SESSION_TIMEOUT = 300  # 5분
    
    def __init__(self):
        self.sessions: Dict[str, dict] = {}
    
    def start_session(self, user_id: str) -> str:
        """보고서 작성 세션 시작"""
        self.sessions[user_id] = {
            "started_at": datetime.now(),
            "work_summary": None,
            "tomorrow_plan": None,
            "blockers": None,
            "step": 0
        }
        return """📝 일일 보고서 작성 세션 시작!

1/3단계 - 오늘의工作总结
오늘 완료한 작업을 입력해주세요.
(마쳤으면 '건너뛰기' 입력)"""
    
    def continue_session(self, user_id: str, input_text: str) -> str:
        """세션 계속 진행"""
        if user_id not in self.sessions:
            return "세션이 만료되었습니다. /日报로 다시 시작해주세요."
        
        session = self.sessions[user_id]
        
        # 타임아웃 체크
        elapsed = (datetime.now() - session["started_at"]).seconds
        if elapsed > self.SESSION_TIMEOUT:
            del self.sessions[user_id]
            return "세션이 만료되었습니다. /日报로 다시 시작해주세요."
        
        # 단계별 입력 처리
        if session["step"] == 0:
            session["work_summary"] = input_text if input_text != '건너뛰기' else '없음'
            session["step"] = 1
            return """✅ 기록되었습니다!

2/3단계 - 내일의工作计划
내일 작업할 내용을 입력해주세요.
(마쳤으면 '건너뛰기' 입력)"""
        
        elif session["step"] == 1:
            session["tomorrow_plan"] = input_text if input_text != '건너뛰기' else '없음'
            session["step"] = 2
            return """✅ 기록되었습니다!

3/3단계 -阻碍因素
현재阻碍이나 이슈가 있으면 입력해주세요.
(없으면 '없음' 입력)"""
        
        elif session["step"] == 2:
            session["blockers"] = input_text if input_text != '없음' else '없음'
            
            # 모든 정보 수집 완료
            from services.daily_report import DailyReportGenerator
            
            generator = DailyReportGenerator(HolySheepClient.__new__(HolySheepClient))
            generator.client = HolySheepClient("YOUR_HOLYSHEEP_API_KEY")
            
            report = generator.generate_report(
                user_id=user_id,
                work_summary=session["work_summary"],
                tomorrow_plan=session["tomorrow_plan"],
                blockers=session["blockers"]
            )
            
            # 세션 정리
            del self.sessions[user_id]
            
            return report + "\n\n✅ 보고서 작성 완료! 즐거운 하루 되세요! 🎉"
        
        return "알 수 없는 오류가 발생했습니다."

ngrok로 로컬 서버 테스트

# 실행 방법


1. 의존성 설치

pip install flask requests python-dotenv


2. 환경변수 설정 (.env 파일)

echo "HOLYSHEEP_API_KEY=YOUR_HOLYSHEEP_API_KEY" > .env
echo "WECOM_CORP_ID=your_corp_id" >> .env
echo "WECOM_CORP_SECRET=your_corp_secret" >> .env


3. ngrok 설치 및 실행 (별도 터미널)


https://ngrok.com/download 에서 다운로드 후

ngrok http 5000


4. Flask 서버 실행

python app.py


5. ngrok에서 받은 HTTPS URL을 企业微信 관리자 콘솔에 등록


예: https://abc123.ngrok.io/wecom/webhook

자주 발생하는 오류 해결

오류 1: HolySheep API 키 인증 실패

# ❌ 오류 메시지

Error: 401 Unauthorized - Invalid API Key



원인: API 키가 잘못되었거나 만료됨



✅ 해결 방법


1. HolySheep 대시보드에서 API 키 확인


https://www.holysheep.ai/dashboard



2. 환경변수 올바르게 설정되었는지 확인

import os
print(f"API Key 설정됨: {bool(os.getenv('HOLYSHEEP_API_KEY'))}")


3. 키가 'sk-'로 시작하는지 확인

API_KEY = "YOUR_HOLYSHEEP_API_KEY"
if not API_KEY.startswith("sk-"):
    print("⚠️ HolySheep API 키 형식이 올바르지 않을 수 있습니다")
    print("대시보드에서 새 키를 발급받아 주세요")


4. 테스트 코드

from services.holysheep_client import HolySheepClient
client = HolySheepClient("YOUR_HOLYSHEEP_API_KEY")
test = client.chat_completion("deepseek-v3.2", [{"role": "user", "content": "test"}])
print(f"연결 테스트 결과: {'✅ 성공' if test else '❌ 실패'}")

오류 2: 기업微信 웹훅 URL 검증 실패

# ❌ 오류 메시지

企业微信 管理端: "URL校验失败"



원인: GET 요청 시Echo 검증 실패



✅ 해결 방법


1. GET 요청 핸들러 확인

@app.route('/wecom/webhook', methods=['GET'])
def wecom_webhook():
    if request.method == 'GET':
        # echostr 파라미터를 그대로 반환해야 함
        echo_str = request.args.get('echostr', '')
        # ❌ 절대 encrypt 처리하지 마세요
        # ❌ return jsonify({"echostr": echo_str}) <- 이것도 오류
        return echo_str  # ✅ plain text로 반환


2. Content-Type 확인

@app.route('/wecom/webhook', methods=['GET'])
def wecom_webhook():
    echo_str = request.args.get('echostr', '')
    return echo_str, 200  # ✅ 상태코드 명시


3. Flask 디버그 모드 끄기 (프로덕션에서 중요)


app.run(debug=False)  # ✅



4. ngrok HTTPS URL 사용 확인


http:// -> https://ngrok.io/wecom/webhook (필수!)

오류 3: 메시지 인코딩 문제 (한글/중국어 깨짐)

# ❌ 오류 메시지

显示: 璇风爜绉帮紵 / ﾃﾞｰ


관련 리소스
관련 문서