1. 项目概述一个为真实工作而生的持久化AI智能体如果你和我一样曾经被那些“演示很酷一用就废”的AI智能体项目折腾得够呛那么openShrimp的出现可能会让你眼前一亮。这不是又一个在干净数据集上跑通就宣告胜利的玩具而是一个我从实际研究工作中“逼”出来的工具。它的核心目标异常简单给你一个能真正“干完活”的AI助手而不是一个需要你不停喂指令、时刻担心它掉线的“半成品”。我最初是OpenClaw的用户那个项目在理念上非常吸引人——一个能自主上网研究的AI智能体。但在实际使用中我不断撞墙任务跑着跑着就没了下文中间过程像黑盒一样不可见想让它持续跟踪一个长期项目更是无从谈起。于是openShrimp诞生了。它本质上是一个基于LangGraph构建的、任务驱动的自主智能体但其设计哲学完全围绕“生产可用性”展开持久化的任务状态管理、零配置的Telegram交互界面、模块化的插件系统以及一个坚如磐石的后端PostgreSQL PGVector。你可以把它理解为一个不知疲倦的远程研究助理你通过Telegram给它派活它会在自己的“任务看板”上列出来然后默默地、持续地工作直到完成或确实需要你介入为止。注意openShrimp的设计强调“自治”而非“全自动”。它会在关键决策点如需要登录凭证时主动询问你但一旦获得授权就会自主推进无需你反复催促“继续”。2. 核心设计理念为什么选择这样的架构在动手搭建或使用openShrimp之前理解其背后的设计抉择至关重要。这能帮助你在遇到问题时知道该从哪个层面去思考和解决。2.1 状态持久化告别“失忆”的智能体绝大多数AI智能体项目包括早期的OpenClaw其运行状态是 ephemeral临时的。一次对话结束所有中间思考、执行步骤、收集到的资料瞬间清零。这对于严肃的研究或自动化工作流是致命的。openShrimp的解决方案将一切核心状态锚定在PostgreSQL数据库中。任务模型每个用户请求都会在数据库中创建一条Task记录包含状态待处理、进行中、等待人工输入、完成、失败、创建时间、最后心跳、关联项目等字段。这意味着即使整个应用重启未完成的任务依然存在并能从中断处恢复。记忆向量化通过集成PGVector扩展智能体与工具交互产生的关键信息如网页摘要、分析结论可以被存储和检索形成长期记忆。这使得智能体在后续任务中能“记得”之前了解过的内容。设计考量为什么是PostgreSQL而不是更简单的SQLite或内存存储答案在于并发可靠性与生态。PostgreSQL能更好地处理多用户、多任务并发写入PGVector是目前最成熟的开源向量数据库方案之一与LangChain等AI框架集成度极高同时它也为未来可能的分布式部署奠定了基础。2.2 Telegram作为首要交互界面极致的用户体验与部署便利性许多AI项目需要你部署一套复杂的前后端Web应用才能交互。openShrimp反其道而行之将Telegram Bot作为唯一的一线交互界面。这样做的好处是压倒性的零前端成本你不需要编写任何HTML、CSS或JavaScript。Telegram提供了现成的、跨平台的消息界面、按钮、菜单甚至文件传输功能。天然的异步与通知智能体可以主动向你发送消息例如“我需要XX网站的登录密码”而你可以在方便的时候回复。这种异步通信模型完美契合了长时间运行任务的需求。极简部署用户侧零配置。他们只需要在Telegram中搜索你的Bot点击“开始”即可。你作为部署者也只需关心后端服务无需维护复杂的Web服务器和SSL证书当然Dashboard部分仍需Web服务。内置身份与隔离每个Telegram用户ID天然就是一个唯一的用户标识。openShrimp利用这一点自动为每个新用户创建独立的数据库记录和文件系统工作空间workspaces/user_id/实现了开箱即用的多用户隔离。2.3 插件化架构如何优雅地扩展智能体的能力一个智能体的能力边界由其工具集决定。openShrimp采用了一种极其轻量级的插件系统让你可以像搭积木一样为智能体添加新功能。插件结构剖析 每个插件就是一个放置在src/plugins/下的文件夹例如src/plugins/weather/。其核心只有两个文件manifest.json: 描述插件元信息如名称、描述、版本。tool.py: 包含用tool装饰器定义的函数。这些函数就是智能体可以调用的“工具”。加载机制应用启动时会自动扫描src/plugins/目录加载所有合法插件中的工具并将其注入到LangGraph智能体的工具列表中。整个过程对核心代码无侵入。实操示例快速创建一个“发送邮件”插件新建目录mkdir -p src/plugins/send_email创建manifest.json:{ name: send_email, description: Tools for sending emails via SMTP., version: 1.0.0 }创建tool.py:import smtplib from email.mime.text import MIMEText from langchain.tools import tool tool def send_email(to_address: str, subject: str, body: str) - str: Send an email to a specified address. Args: to_address: Recipient email address. subject: Subject of the email. body: Body content of the email. Returns: A confirmation message. # 这里应从环境变量或凭证库读取SMTP配置 # 为示例简化假设已配置 msg MIMEText(body) msg[Subject] subject msg[From] your_botexample.com msg[To] to_address with smtplib.SMTP(smtp.example.com, 587) as server: server.starttls() server.login(your_botexample.com, your_password) server.send_message(msg) return fEmail sent successfully to {to_address}重启openShrimp服务智能体现在就能在任务中决定是否调用send_email这个工具了。心得插件化的关键在于工具函数的描述文档Docstring。LangGraph的LLM通过阅读这些描述来决定何时调用工具。因此务必用清晰、准确的语言描述工具的功能、参数和返回值。3. 从零开始部署与深度配置指南理解了“为什么”之后我们来动手“怎么做”。这里将详细拆解自托管openShrimp的每一步并解释每个配置项背后的意义。3.1 基础环境搭建与数据库初始化系统准备建议使用Linux服务器Ubuntu 22.04 LTS或类似版本。确保已安装Docker和docker-compose这是运行openShrimp所有组件的最简单方式。克隆与配置git clone https://github.com/JustinGuese/openshrimp.git cd openshrimp cp .env.example .env接下来是配置.env文件这是整个项目的控制中枢。我们逐一分析关键变量核心服务配置# 数据库配置 DATABASE_URLpostgresql://postgres:your_strong_passworddb:5432/openshrimp # 这是Docker Compose网络内的地址。db是数据库服务的容器名5432是PostgreSQL默认端口。 # 请务必修改your_strong_password为一个高强度的随机密码。 # PGVector扩展确保向量搜索功能正常。 PGVECTOR_DRIVERpsycopg2AI模型与OpenRouter配置# OpenRouter API密钥获取地址https://openrouter.ai/keys OPENROUTER_API_KEYsk-or-v1-... # 默认模型路由策略 OPENROUTER_MODELdeepseek/deepseek-v3.2 # 全局后备模型 OPENROUTER_MODEL_QUICKopenai/gpt-oss-120b # “快速”任务模型 OPENROUTER_MODEL_NORMALdeepseek/deepseek-v3.2 # “普通”任务模型 OPENROUTER_MODEL_DEEPz-ai/glm-5 # “深度”研究任务模型模型选择逻辑智能体会根据你消息中的关键词自动选择模型。例如你说“快速总结一下”它会使用更便宜、更快的gpt-oss-120b并限制工具调用次数为5次。你说“做一个深度市场分析”则会启用能力更强的glm-5并给予25次工具调用的预算。这是一种在成本与效果间的智能权衡。Telegram Bot配置# 从 BotFather 获取 TELEGRAM_BOT_TOKEN1234567890:AAHx7b4z3cD_ExampleToken_5rLk8JmN2oPq DEFAULT_AGENT_USER_ID1 # 通常留空系统会自动创建 DASHBOARD_BASE_URLhttp://localhost:8000 # 开发时用本地地址生产环境需改为公网URL重要提示DASHBOARD_BASE_URL是Bot生成Dashboard链接的基础。如果你通过docker-compose在本地运行并想通过Telegram手机App访问Dashboard你需要使用内网穿透工具如ngrok、localtunnel将本地的8000端口暴露为一个公网HTTPS地址并在此处填写该地址。3.2 使用Docker Compose一键启动配置好.env后启动所有服务变得非常简单docker-compose up -d这个命令会启动定义在docker-compose.yml中的所有服务db: 运行PostgreSQL PGVector的数据库。browserless: 一个无头Chrome远程服务供browser插件调用执行网页交互。frontend: 提供API和Web Dashboard的FastAPI服务。agent: 运行LangGraph智能体并与Telegram通信的核心服务。worker: 处理后台任务如定时任务、重试的Celery工作进程。验证服务是否健康docker-compose logs --tail50 agent # 查看智能体服务日志关注有无报错 curl http://localhost:8000/health # 检查前端API是否就绪如果一切正常你现在可以打开Telegram找到你创建的Bot发送/start或任何一条消息。你应该能立即收到回复并且任务系统开始运作。3.3 核心插件详解与实战配置openShrimp的强大能力来源于其插件。我们来深入看看几个核心插件如何工作及如何配置。3.3.1 Browser插件对抗反爬的智能浏览器这是智能体的“眼睛和手”。它不仅仅是获取网页HTML而是能进行点击、输入、提交表单等交互。# .env 中关于Browserless的配置 BROWSERLESS_ENDPOINThttp://browserless:3000 BROWSERLESS_STEALTH_MODEtrue CAPSOLVER_API_KEYyour_capsolver_key_optionalpyppeteer-stealth该库通过一系列技术如覆盖WebDriver属性、修改插件列表、伪装硬件指纹让Puppeteer驱动的浏览器看起来更像真人用户。BROWSERLESS_STEALTH_MODEtrue即启用此模式。CapSolver集成对于更顽固的验证码如Cloudflare Turnstile, reCAPTCHA v2可以配置CAPSOLVER_API_KEY。当浏览器插件检测到验证码时会自动调用CapSolver服务进行AI求解。这是一个付费服务但对于需要登录高防护网站的任务至关重要。实操技巧在测试阶段你可以在Telegram中发送/debug命令开启调试模式。此后智能体的每一个工具调用包括浏览器访问的URL、执行的点击操作都会实时流式发送到你的聊天窗口极大方便了调试。3.3.2 凭证保险库与任务调度实现真正自动化这是让智能体从“执行单次任务”升级到“管理长期工作流”的关键。凭证保险库 (credential_vault)生成加密密钥python -c from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())将输出的一长串字符设置为环境变量OPENSHRIMP_VAULT_KEYyour_generated_fernet_key_here在任务中使用智能体可以调用get_credential(name)获取存储的密码。一个典型的登录流程是智能体尝试访问一个需要登录的网站。它首先调用get_credential(twitter_login)。如果返回空即首次使用则调用ask_human工具向你询问账号密码。获得你的回复后立即调用store_credential(twitter_login, username:password)将其加密存储。下次执行同类任务时它就能直接获取凭证登录无需再打扰你。任务调度 (task_tracking) 智能体可以在完成任务A之后自动创建一个未来执行的任务B。例如“发布这篇博客后在4小时后检查一下评论和转发量。”“每天上午9点收集竞争对手官网的新闻动态。” 这是通过在工具函数中调用task_tracking.schedule_followup_task来实现的底层依赖于数据库中的scheduled_at和repeat_interval_seconds字段并由后台的worker服务轮询执行。4. 运维、监控与故障排查实战将系统跑起来只是第一步稳定运行才是关键。openShrimp内置了多种机制来保障可靠性但作为运维者你需要知道如何观察和干预。4.1 利用Dashboard进行任务监控Dashboard是你最重要的运维界面。通过Telegram发送/dashboard获取你的个人链接格式如http://your-domain/dashboard?tokenyour_secret_token。看板视图以Trello式的列展示不同状态待处理、进行中、等待中、完成、失败的任务卡片。你可以直接拖拽卡片来改变任务状态例如将一个失败的任务拖回“待处理”列让其重试。表格视图提供所有任务的搜索、筛选和排序。你可以查看每个任务的详细日志、创建时间、最后心跳时间、使用的模型、工具调用次数等。注意Dashboard默认是权限隔离的。普通用户只能看到自己的任务。如果你需要管理员视图查看所有用户任务需要在.env中设置DASHBOARD_ADMIN_TOKEN为一个强密码然后在访问Dashboard时使用?token你的管理员令牌。4.2 理解并处理任务生命周期与异常一个任务在数据库中的状态流转是理解系统健康度的核心。正常流程PENDING-IN_PROGRESS-COMPLETED。异常情况任务卡在IN_PROGRESS原因执行任务的agent进程可能意外崩溃如OOM被杀未能更新任务状态。处理系统有一个“看门狗”机制由HEARTBEAT_WATCHDOG_MINUTES默认10分钟控制。任何IN_PROGRESS的任务如果超过此时间未收到来自智能体的“心跳”更新会被自动重置为PENDING等待其他空闲的工作线程拾取。排查在Dashboard中检查该任务的“最后心跳”时间。如果远早于当前时间说明智能体执行线程已僵死。查看docker-compose logs agent寻找可能的错误如网络超时、模型API异常。任务进入WAITING_FOR_HUMAN状态原因智能体调用了ask_human工具正在等待你的回复。处理直接在Telegram对话中回复即可。智能体线程被阻塞并等待一旦收到回复任务会继续执行。设计保护为了防止智能体过度询问有两个限制a) 一个轻量级LLM评估器会先过滤掉那些明显可以自己搜索到答案的琐碎问题b) 每个任务有MAX_ASKS_PER_TASK默认2次的硬性上限。任务失败进入FAILED状态原因可能是不可恢复的错误如访问的网页不存在、API密钥无效、工具函数内部异常。处理Dashboard的表格视图可以点击查看失败任务的详细日志其中通常包含Python的错误回溯信息这是排查的第一手资料。自动重试对于网络超时、5xx服务器错误等瞬时故障系统会根据AGENT_MAX_RETRIES默认2次进行自动重试并伴有指数退避延迟避免加重对方服务器负担。4.3 日志分析与性能调优集中查看日志# 查看所有服务的实时日志 docker-compose logs -f # 仅查看智能体服务的日志并过滤错误 docker-compose logs agent | grep -i error关键性能指标工具调用延迟在日志中观察每次工具调用特别是browser访问网页的耗时。如果browserless服务响应缓慢考虑在docker-compose.yml中为其增加CPU和内存资源限制。LLM API消耗与成本关注不同“努力程度”任务所使用的模型和调用次数。如果“快速”任务也频繁调用昂贵模型可以调整.env中OPENROUTER_MODEL_QUICK的配置或优化提示词以减少不必要的思考步骤。数据库连接长时间运行后检查数据库连接数是否正常。可以在docker-compose.yml的db服务中设置POSTGRES_MAX_CONNECTIONS并确保应用端有正确的连接池配置。5. 高级应用场景与定制化开发当基础功能稳定运行后你可以根据自身需求将openShrimp定制成更强大的专属自动化助手。5.1 构建垂直领域的研究助手假设你是一个风险投资分析师需要每天追踪数十家初创公司的动态。创建专用插件开发一个src/plugins/vc_research/插件其中包含fetch_crunchbase(company_name),monitor_news(keywords),analyze_funding_trends(industry)等工具。配置定时任务在项目初始化时或通过一个管理命令创建一系列定时任务。例如每天上午10点执行“监控我投资组合中所有公司的新闻”任务。优化记忆与输出配置memory_rag插件让它将每天抓取到的新闻摘要存入向量库。当你下周问“某公司最近有什么技术突破”时智能体会先检索长期记忆再结合实时搜索给出答案。你还可以定制输出格式让它最终生成一份结构化的Word或PDF日报并通过filesystem插件保存甚至通过send_email插件发送给你。5.2 集成外部系统与APIopenShrimp的智能体可以成为你企业工作流的“胶水”。与项目管理工具集成创建一个jira或linear插件让智能体能够根据对话内容自动创建工单、更新状态或添加评论。与数据仓库交互创建一个bigquery插件赋予智能体编写SQL查询、获取业务数据并进行分析的能力。触发外部自动化通过调用webhook工具在任务完成时触发一个Zapier或Make的流程从而连接起成千上万的其他SaaS服务。开发外部API插件的要点安全性API密钥务必通过credential_vault管理切勿硬编码在插件中。错误处理在tool.py的函数中做好全面的异常捕获和日志记录返回清晰的错误信息给智能体以便它决定重试或转为ask_human。速率限制对于有调用限制的外部API需要在插件内部实现简单的限流逻辑或利用任务调度将密集操作分散到不同时间执行。5.3 模型路由与提示词工程优化openShrimp默认的“努力程度”路由是基于关键词的简单启发式方法。你可以根据你的使用模式进行优化。自定义路由规则你可以修改agent服务中检测努力程度的逻辑。例如对于来自特定用户或特定项目的所有任务都默认使用“深度”模型。或者根据消息的长度来判断复杂度。优化系统提示词系统提示词定义了智能体的“性格”和任务边界。它位于LangGraph智能体的构建代码中。你可以调整它来强调领域知识“你是一名专业的网络安全分析师你的回答应聚焦于漏洞、攻击向量和缓解措施...”约束输出格式“请始终以Markdown表格的形式总结你的发现包含‘来源’、‘关键点’、‘置信度’三列。”控制工具使用偏好“在尝试使用browser插件登录网站前务必先检查credential_vault中是否已有保存的凭证。”经过这些深度定制openShrimp将从一个通用的研究助手蜕变为嵌入到你日常工作流中的、高度专业化的智能协作伙伴。它的价值不再仅仅是“回答问题”而是持续、可靠、自主地帮你完成那些繁琐、重复但需要一定智能判断的数字化工作。