개요
AstrBot은 오픈소스 올인원 AI 에이전트 채팅 플랫폼으로, 주요 인스턴트 메신저 소프트웨어와 통합됩니다. 대규모 언어 모델 대화, 플러그인 확장, 멀티모달, 에이전트 샌드박스 및 지식 베이스를 지원하며, 개인과 팀이 AI 애플리케이션을 빠르게 구축하는 데 적합합니다.
README 미리보기
\n\n\n\n\n简体中文 ｜\n繁體中文 ｜\n日本語 ｜\nFrançais ｜\nEspañol ｜\nРусский \n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\nDocumentation ｜\nBlog ｜\nRoadmap ｜\nIssue Tracker ｜\nEmail Support\n\n\nAstrBot is an open-source all-in-one Agent chatbot platform that integrates with mainstream instant messaging apps. It provides reliable and scalable conversational AI infrastructure for individuals, developers, and teams. Whether you're building a personal AI companion, intelligent customer service, automation assistant, or enterprise knowledge base, AstrBot enables you to quickly build production-ready AI applications within your IM platform workflows.\n\n\n\n## Key Features\n\n1. 💯 Free & Open Source.\n2. ✨ AI LLM Conversations, Multimodal, Agent, MCP, Skills, Knowledge Base, Persona Settings, Auto Context Compression.\n3. 🤖 Supports integration with Dify, Alibaba Cloud Bailian, Coze, and other agent platforms.\n4. 🌐 Multi-Platform: QQ, WeChat Work, Feishu, DingTalk, WeChat Official Accounts, Telegram, Slack, and [more](#supported-messaging-platforms).\n5. 📦 Plugin Extensions with 1000+ plugins available for one-click installation.\n6. 🛡️ [Agent Sandbox](https://docs.astrbot.app/use/astrbot-agent-sandbox.html) for isolated, safe execution of code, shell calls, and session-level resource reuse.\n7. 💻 WebUI Support.\n8. 🌈 Web ChatUI Support with built-in agent sandbox and web search.\n9. 🌐 Internationalization (i18n) Support.\n\n\n\n\n \n 💙 Role-playing & Emotional Companionship\n ✨ Proactive Agent\n 🚀 General Agentic Capabilities\n 🧩 1000+ Community Plugins\n \n \n \n \n \n \n \n\n\n## Quick Start\n\n### One-Click Deployment\n\n> [!NOTE]\n> Requires [uv](https://docs.astral.sh/uv/) to be installed.\n> For macOS users: due to macOS security checks, the first run of the `astrbot` command may take longer (about 10-20s).\n\nFor users who want to quickly experience AstrBot, are familiar with command-line usage, and can install a `uv` environment on the
FAQ (5)
문제 해결AstrBot이 QQ Official (qq_official) 어댑터에서 중복 메시지를 수신하고 여러 번 답장하는 이유는 무엇인가요?
이것은 AstrBot v4.19.2의 알려진 버그입니다. 원인: (1) qq_official 어댑터에 message_id 기반 메시지 중복 제거 기능이 없어 QQ Official webhook 재시도(Tencent는 확인 응답을 받지 못하면 최대 3회까지 알림을 재전송함)가 반복적으로 처리되었고, (2) UI에서 어댑터를 비활성화할 때 어댑터 이벤트 핸들러가 정리되지 않아 재시작 후 중복 처리가 발생했습니다. 해결 방법: AstrBot을 최신 버전으로 업그레이드하세요. PR #6320에서 QQ Official webhook 재시도로 인한 중복 메시지 처리가 수정되었습니다. 이전 버전에서의 임시 해결 방법: 웹 UI에서 어댑터를 토글하는 대신 AstrBot 프로세스/컨테이너를 완전히 재시작하고, 어댑터를 자주 활성화/비활성화하지 마세요. 중복 응답은 API rate-limit 차단을 유발할 수 있으므로 업그레이드를 강력히 권장합니다.
문제 해결AstrBot 백그라운드 작업 또는 subagent가 완료되었는데도 사용자가 메시지를 받지 못하고 경고 로그도 남지 않는 문제를 해결하는 방법은?
영향받는 버전: AstrBot 4.29.0-beta.1. 백그라운드 작업 깨우기 턴은 일반 메시지 파이프라인을 우회하며, 메인 에이전트가 send_message_to_user를 호출할 때만 출력을 전달합니다. astrbot/core/astr_agent_tool_exec.py:662의 기존 경고는 llm_resp가 비어 있을 때만 발생했기 때문에, 전달 시도가 없는 정상 응답은 완전히 아무런 알림 없이 지나갔습니다.
수정 방법: PR #10398이 포함된 AstrBot 릴리스로 업그레이드하세요(issue #10395 수정). Windows 데스크톱에서는 AstrBotLauncher를 통해 업데이트한 후 재시작하세요. Git 배포의 경우:
cd AstrBot
git pull
# 배포 환경에 필요한 대로 의존성을 설치/업데이트하세요
# 그런 다음 AstrBot을 재시작하세요다음 명령으로 수정 사항을 확인하세요:
grep -n "_has_send_oper" astrbot/core/astr_agent_tool_exec.py이 수정은 runner.step_until_done() 및 get_final_llm_resp() 이후에 cron_event._has_send_oper를 확인합니다. 백그라운드 작업이 결과를 생성했지만 현재 대화에 아무것도 전달되지 않은 경우, AstrBot은 이제 task_id와 tool_name이 포함된 WARNING을 로깅합니다. 이 플래그는 전달이 성공한 후에만 설정되므로, 전송 실패나 다른 세션으로의 전송도 감지됩니다.
모델이 의도적으로 침묵을 유지할 수 있으므로 자동 재전송은 추가되지 않았습니다. 전달을 보장해야 하는 경우, _has_send_oper가 false일 때 llm_resp.completion_text를 일반 응답 경로를 통해 전송하는 폴백을 추가로 구현해야 합니다. 이는 동작을 변경하므로 신중하게 테스트해야 합니다.
이전 버전에서의 임시 완화 조치: 의미 있는 결과를 가진 완료된 백그라운드 작업이 반드시 send_message_to_user를 호출하도록 메인 에이전트 프롬프트를 강화하거나, 기존 if not llm_resp 분기 근처에 _has_send_oper WARNING 확인 로직을 수동으로 추가하세요. 결과는 에이전트 상태에서 손실되지 않으며 대화 기록에 [BackgroundTask] ... Result: ... 형태로 유지되지만, 사용자에게는 알림이 전달되지 않습니다.
문제 해결이미지 URL이 C:\api\v1\files\tokens\...로 바뀔 때 AstrBot "Model image preparation failed; skipping image (FileNotFoundError)" 오류를 해결하는 방법
이 문제는 AstrBot v4.28.1에 영향을 줍니다. /api/v1/files/tokens/<token>과 같은 루트 상대 플러그인 URL은 URL로 인식되지 않습니다. MediaResolver는 존재 여부를 확인하지 않고 이를 로컬 파일로 취급하므로, Windows에서는 C:\api\v1\...로 해석됩니다. 이후 읽기가 실패하고 이미지가 아무 알림 없이 건너뛰어집니다.
영구적인 해결 방법:
1. issue #10264에 대한 PR Fix/reject unresolvable image refs가 포함된 릴리스로 AstrBot을 업그레이드하세요. 이제 프레임워크는 가짜 로컬 경로를 반환하는 대신 해석할 수 없는 미디어 참조를 거부합니다.
2. URL을 생성하는 플러그인(예: astrbot_plugin_qqwebui v1.1.0)을 수정하여 /로 시작하는 경로가 아닌 절대 HTTP URL을 반환하도록 하세요:
image.url = f'{PUBLIC_BASE_URL.rstrip("/")}/api/v1/files/tokens/{token}'
# 예시: http://127.0.0.1:6185/api/v1/files/tokens/<token>유효한 미디어 입력은 http(s)://..., 존재하는 로컬 파일 경로, file://..., data:... 또는 유효한 Base64입니다.
즉시 업그레이드할 수 없는 경우, astrbot/core/utils/media_utils.py 파일의 _materialize_media_ref() 내부에 있는 폴백 분기를 패치하세요:
path = Path(media_ref)
if path.is_file():
return _LocalMediaFile(path=path, mime_type=_guess_mime_type(path))
raise ValueError(f'Unresolvable media reference: {media_ref}')변경 후 AstrBot을 다시 시작하세요. 이전 대화 기록에는 여전히 유효하지 않은 [Image Attachment: path ...] 플레이스홀더가 남아 있을 수 있으므로, 동일한 코드 경로를 사용하는 인용 이미지와 전달된 이미지를 포함하여 새로 전송한 이미지로 테스트하세요.
문제 해결astrbot_plugin_temp_chat_fix 플러그인을 삭제한 후에도 AstrBot 로그에 해당 플러그인 오류가 계속 표시되는 이유는 무엇인가요? 어떻게 해결하나요?
이는 해당 플러그인이 main.py:52에서 aiocqhttp의 call_action을 몽키 패치했지만, 삭제 또는 언인스톨 시 terminate()에서 이를 복원하지 않았기 때문입니다. AstrBot 프로세스가 여전히 실행 중인 동안에는 메모리의 bot 객체가 이전 래퍼 함수를 그대로 유지하고 있어 호출 스택이 계속 삭제된 플러그인 경로를 가리키게 됩니다. 해결 방법은 AstrBot 프로세스를 완전히 재시작하는 것입니다. Docker 배포 환경에서는 docker restart <AstrBot 컨테이너명>을 실행하면 되고, 네이티브 배포 환경에서는 서비스를 중지한 후 다시 시작하면 됩니다. 재시작 후 data/plugins/astrbot_plugin_temp_chat_fix 디렉터리가 삭제되었는지 확인하면 됩니다. 로그의 retcode=100, no such temp session은 QQ 임시 세션이 만료되었음을 의미하며, 사용자가 임시 세션을 다시 시작해야 합니다. 이는 플러그인 잔재 오류와는 별개의 문제이므로, astrbot_plugin_temp_chat_fix 리포지토리에 별도로 피드백하여 작성자가 terminate()에서 call_action을 복원하도록 해야 합니다.
문제 해결요약 모델이 HTTP 429 할당량 소진 오류를 반환한 후 기본 채팅 모델을 전환해도 AstrBot이 몇 분 동안 멈추는 문제를 해결하는 방법
AstrBot v4.28.2에서 컨텍스트 압축기는 request_max_retries 없이 text_chat()을 호출하므로, 프로바이더는 지수 백오프와 함께 총 5회 시도라는 기본값을 사용합니다. HTTP 429는 재시도되며, 모든 시도가 실패할 때까지 응답이 차단됩니다. 멈춘 요청은 별도로 구성된 요약 모델을 사용하고 있기 때문에 메인 모델을 변경해도 도움이 되지 않습니다. 폴백 역시 truncate_by_halving()을 한 번만 호출하며 남은 히스토리가 맞는지 다시 확인하지 않습니다.
수정 방법: PR #10436이 포함된 AstrBot 빌드(master에서 커밋 800fdcc 이후)로 업그레이드하세요. 해당 수정은 요약 요청에 request_max_retries=1을 전달하고(1은 0이 아니라 총 1회 시도를 의미합니다) 즉시 잘라내기로 폴백합니다. 이 수정은 선행 시스템 메시지를 보존하고, 남은 히스토리를 완전한 라운드로 분할하며, 추정된 컨텍스트가 맞을 때까지 가장 오래된 라운드를 반복적으로 제거하고, 최신 라운드를 유지하며, 도구 호출이 해당 도구 결과와 짝을 이루도록 유지합니다.
v4.28.2에서의 임시 해결 방법:
1. /new를 실행하여 새 대화를 시작하세요. 이 방법은 응답을 복원하는 것으로 확인되었습니다.
2. 요약 모델 쿼터/API 자격 증명을 복원하거나 사용 가능한 요약 모델을 구성하세요.
3. 사용 불가능한 요약 모델을 즉시 해결할 수 없는 경우 독립 LLM 컨텍스트 압축을 비활성화하세요.
메인 채팅 모델만 변경하는 것은 요약 모델을 변경하지 않기 때문에 해결 방법이 아닙니다. 나중에 도구 호출과 관련된 API에서 확인된 컨텍스트 오버플로 오류가 발생하면 issue #7225의 짝을 이루는 record-pop 수정이 포함된 빌드도 사용하세요.