Haohao-end/openagent · 上手攻略

  • 仓库：Haohao-end/openagent
  • 链接：https://github.com/Haohao-end/openagent
  • 分类：skill / agent（Dify 式的全栈 AI 应用平台，含 Deep Research 与 A2A 委派）
  • 作者：Jay
  • 更新：2026-10-29

一、是什么

OpenAgent 是一个全栈 AI Agent 平台，官方仓库一句话概括是："What if OpenAI Deep Research and Dify were one platform?"——即把 Deep Research 式的深度推理循环和 Dify 式的可视化应用编排合成一个东西。仓库描述为 "harness architecture for rapidly building vertical AI agents"。

技术栈与 FIM One 那种"FastAPI + Next.js"风格不同，它走的是Flask + Vue 3 路线：

  • 后端：Python / Flask / SQLAlchemy / Celery / Flask-SocketIO / Redis / PostgreSQL
  • Agent 运行时：LangChain + LangGraph（工作流编译成图）
  • 检索：RAG，语义检索 + 全文检索 + 混合检索，Weaviate（主）/ FAISS
  • 前端：Vue 3 + TypeScript + Vite + TailwindCSS + Pinia + Vue Flow + Arco Design
  • 交付：Docker Compose + Nginx + OpenAPI + SSE
  • 模型接入：OpenAI、Atlas Cloud、DeepSeek、Grok、Google、Moonshot（月之暗面）、通义、文心、Ollama、智谱

GitHub 上约 774 stars，Python，MIT 许可（对比同类的 Source Available 友好得多）。最新 Release 是 v1.1.4（发布于 2026-06-15），由作者账号 Haohao-end 发布。

二、解决什么问题

它面向的是"要做 AI 应用，而不是只做聊天 demo"的团队。仓库自带的说明里列出的当前代码已支持能力：

  1. 首页助手通过 A2A 把用户请求路由到已发布的公开 Agent；也支持用自然语言描述需求直接触发 AI 应用创建流程。
  2. AI 应用工作台：草稿、发布、分析、版本对比、Prompt 对比。
  3. Deep Research：把复杂任务拆解成多步，在执行链上协调已绑定的能力。README 特别注明——"Deep Research" 这个词在代码里对应的是 enable_deep_thinking 背后的深度思考模式，不是另起炉灶的一套研究子系统。这是个重要的预期校准。
  4. 可视化工作流：节点涵盖 LLM、工具调用、数据集检索、代码执行、HTTP 请求、分支、文本处理、模板转换、结构化参数抽取。
  5. 数据集与文档管理：建数据集、传文档、看切片、把检索接进 Agent 与工作流。
  6. 应用商店：浏览公开应用、工具、工作流。
  7. 对外交付：发布后的应用通过 POST /api/openapi/chat 暴露 REST 与 SSE 接口，支持多轮会话标识。

架构上，从浏览器/外部客户端进来是 Flask HTTP API → handler/service → agent 与 LangGraph 工作流运行时 → LLM 提供商与工具/MCP/检索；异步任务走 Celery，落到 PostgreSQL 与 Weaviate。

三、快速安装

前置要求

  • Docker 20.10+、Docker Compose 2.x
  • 建议 8 GB+ 内存（全栈）
  • 至少一个模型提供商 API Key

全栈 Docker 启动

git clone https://github.com/Haohao-end/openagent.git
cd openagent

cp api/.env.example api/.env
# 编辑 api/.env

cd docker
docker compose up -d --build

服务地址：

服务 URL 说明
前端 http://localhost:3000 Vue 3 Web UI
API http://localhost:5001 Flask REST API
Nginx http://localhost 反向代理

api/.env 里必须填的最小集（来自仓库卡与 README）：

JWT_SECRET_KEY
POSTGRES_PASSWORD
REDIS_PASSWORD
WEAVIATE_API_KEY
VITE_API_PREFIX
# 再加至少一个 provider key，例如 OPENAI_API_KEY / DEEPSEEK_API_KEY / DASHSCOPE_API_KEY

JWT 密钥可用 openssl rand -hex 32 生成。

本地开发（只起基础设施）

架构文档明确建议：本地开发只起 PostgreSQL / Redis / Weaviate 三个支撑服务，API、UI、Celery 跑在宿主机上，避免每次改动都构建完整应用容器。

cd docker
docker compose up -d --no-build llmops-db llmops-redis llmops-weaviate
docker compose ps llmops-db llmops-redis llmops-weaviate

然后：

# 终端 1：API
cd api
pip install -r requirements.txt
flask run --port 5001

# 终端 2：Celery
cd api
celery -A app.http.app:celery worker --loglevel=info

# 终端 3：前端
cd ui
npm install
npm run serve        # Vite 默认 5173，/api 代理到 Flask

注意本地 .env 里数据库/Redis/Weaviate 要填 localhost 及已发布端口；Docker 内部则用服务名（llmops-db 等），compose 会自动覆盖。

四、核心用法

4.1 环境变量分层（最容易踩的地方）

仓库把配置分成三层，README 与 docker/README 都强调这点：

  • docker/.env：Docker Compose 基础设施配置——端口映射、镜像标签、PostgreSQL/Redis 端口、Weaviate HTTP 8080 / gRPC 50051。
  • api/.env：业务配置——LLM Key、插件 Key、OAuth、JWT、对象存储、邮件、LangSmith 追踪。
  • Compose 的 environment 段：覆盖 MODE（api/celery）、MIGRATION_ENABLED、以及各中间件的容器内连接地址。

关键约束：llmops-ui 镜像构建时会直接读取 api/.env 中的 VITE_API_PREFIX，缺这个值 UI 镜像在构建阶段就失败。改完 VITE_API_PREFIX 必须重新 build llmops-ui。

4.2 模型接入

.env.example 里预置的 provider 包括 Moonshot、SiliconFlow、DeepSeek、OpenAI、Atlas Cloud、Grok、百度千帆（qianfan_ak/qianfan_sk）、通义、文心等：

OPENAI_API_KEY=sk-your-openai-key-here
OPENAI_API_BASE=https://api.openai.com/v1
LLM_REQUEST_TIMEOUT=120

DEEPSEEK_API_KEY=sk-your-deepseek-key-here
DEEPSEEK_API_BASE=https://api.deepseek.com/v1

ATLASCLOUD_API_KEY=your-atlascloud-key-here
ATLASCLOUD_API_BASE=https://api.atlascloud.ai/v1

深度思考沙箱另有一套：SANDBOX_PROFILE=lite（文档说 lite 档位建议对应 2 CPU / 2048 MiB 的自定义模板）、SANDBOX_URL（腾讯云 SCF 函数的 URL）。多模态还有 IMAGE_REQUEST_POLICY（strict = 纯文本模型收到图片直接报错；auto_upgrade = 配置了视觉兜底模型则自动切换）。

4.3 应用工作台

左侧绑定模型、Prompt 与能力；右侧做实时调试、执行轨迹与结果核对。能力绑定面很宽：插件、MCP、Skills、子 Agent 应用、工作流、数据集。启用 Deep Research 后，应用能把工作拆成步骤，在更长执行链上协调已绑定能力，并支持脚本执行、文件生成、附件导出等"需要具体产物"的场景。

4.4 可视化工作流

节点类型覆盖 LLM、tool、dataset retrieval、code、HTTP request、template transform、text processor、variable assigner、parameter extractor、if/else、start、end。工作流服务在 api/internal/core/workflow 编译成 LangGraph 图，节点可调用语言模型、工具或检索。

4.5 对外交付

发布后的应用走 POST /api/openapi/chat，支持标准响应与流式响应，并支持多轮对话标识。

4.6 测试

cd api && pytest
cd ui && npm run test:unit -- --run
cd ui && npm run type-check
cd ui && npm run lint
cd ui && npm run build

五、典型适用场景

  • 垂直业务 Agent 快速搭建：把一个行业流程拆成应用 + 工作流 + 数据集三天内上线，而不是从 LangGraph 裸写。
  • Deep Research 式长任务：需要多步分解 + 协调多种能力的调研/分析类任务。
  • 多 Agent 协作：一个应用通过 A2A 调用另一个已发布的应用，配合子 Agent 绑定。
  • 把内部知识接进工作流：数据集 + 文档切片 + 检索节点，给工作流加私域知识。
  • 对外提供 API：应用发布后用 OpenAPI + SSE 交付给前端或第三方系统。
  • 国内模型可用：DeepSeek / 通义 / 文心 / 智谱 / Moonshot / 千帆都在支持列表里，接国内模型不用自己写适配层。

六、坑与注意

每坑按"现象 / 影响 / 修复"三段式整理。

坑 1：VITE_API_PREFIX 缺失导致 UI 构建直接失败。 - 现象：docker/README 明确写"缺少 VITE_API_PREFIX 时，UI 镜像会在构建阶段直接失败"，因为 llmops-ui 构建时直接读取 api/.env。 - 影响：docker compose up -d --build 在 UI 阶段报错，容易误以为是网络或依赖问题。 - 修复：cp api/.env.example api/.env 后第一件事就是填 VITE_API_PREFIX（本地示例 http://127.0.0.1:5001）；改这个值之后必须重新 build llmops-ui。

坑 2："Deep Research" 名不副实。 - 现象：README 自己声明 "the README term Deep Research maps to the deep thinking mode behind enable_deep_thinking"。 - 影响：如果你按 OpenAI Deep Research 的期望（自主多轮检索、引用、报告产出）去规划，落地会发现它就是深度思考开关，能力边界小得多。 - 修复：把"深度研究"当深度思考模式评估，别当独立子系统排期；真要深度研究能力得自己用 LangGraph + 检索节点拼。

坑 3：Docker 与本地的连接地址不同，混用就连不上。 - 现象：容器内部用服务名（llmops-db、llmops-redis、llmops-weaviate），本地开发用 localhost + 已发布端口。 - 影响：同一份 .env 在两种模式下不能通用，报错是连接超时/认证失败，根因却是地址写法。 - 修复：本地起基础设施时，把 api/.env 的 SQLALCHEMY_DATABASE_URI、REDIS_HOST、WEAVIATE_HTTP_HOST 都写成本地端口；容器模式下交给 compose 的 environment 覆盖。

坑 4：Weaviate 只能逐个小版本升级。 - 现象：docker/README 明确 Weaviate 只支持逐个小版本升级（如 1.28 → 1.29 → 1.30），不能跳版本。 - 影响：升级 compose 里的 Weaviate 版本时若直接跳号，数据目录不兼容，服务起不来。 - 修复：已有旧版本数据时先备份 docker/volumes/weaviate，再依次用每个中间小版本的最新补丁版启动一次（等 /v1/.well-known/ready 就绪）后才能切到目标版本；全新部署无此步骤。

坑 5：改密码不能只改环境变量，docker compose down -v 更不能碰。 - 现象：PostgreSQL 数据目录已存在时，改 POSTGRES_PASSWORD 不会更新数据库角色密码。 - 影响：轮换密码后 API 连不上数据库，看起来像迁移问题。 - 修复：先 docker compose exec llmops-db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"'，在 psql 里用 \password 改密码，再更新 .env 并只重建相关服务；切勿用 docker compose down -v，那会删掉数据库、Redis、Weaviate 的持久化卷。

坑 6：.env 里有大量密钥，提交即泄露。 - 现象：api/.env.example 里含几十个 Key 占位（OpenAI、Grok、千帆、LangSmith、Pinecone、COS、OAuth 客户端密钥、GITHUB_ACCESS_TOKEN、WEAVIATE_API_KEY 等）。 - 影响：一次误提交 api/.env 就是一轮密钥轮换。 - 修复：.env 一律进 .gitignore，只提交 .env.example；docker/README 开头就有"所有敏感信息必须存在 .env，绝不提交到 Git"的安全提示。

坑 7：多模态默认严格模式，纯文本模型收到图片会直接报错。 - 现象：IMAGE_REQUEST_POLICY=strict 时，图片请求发给纯文本模型直接失败；auto_upgrade 才会在配置了视觉兜底模型时自动切换。 - 影响：用户上传图片报的是模型侧错误，容易被误判为前端 bug。 - 修复：默认保持 strict 以便暴露问题；生产需要兼容时改 auto_upgrade 并配 VISION_FALLBACK_PROVIDER / VISION_FALLBACK_MODEL。

坑 8：资源门槛与组件数量都不低。 - 现象：全栈需要 PostgreSQL + Redis + Weaviate + API + Celery + UI + Nginx，README 建议 8 GB+ 内存。 - 影响：小机器上直接 docker compose up -d --build 会出现服务反复重启或 Weaviate OOM。 - 修复：开发期按 4.2 的"只起三个支撑服务"流程走；生产部署前确认内存 ≥8 GB 并给 Weaviate 单独算配额。

坑 9：本地开发路径容易走偏。 - 现象：docs/README 与 architecture.md 都特别写明"不要暗示每次修改都必须构建完整应用容器"，且 Celery 是独立进程，容易被漏起。 - 影响：漏起 Celery 时表现为异步任务（如文件处理、后台任务）永远不完成，且没有明显报错。 - 修复：本地开发固定三终端（API / Celery / UI）；排查任务不落库时先看 Celery worker 日志。

坑 10：历史上修过三个安全漏洞，值得留意安全响应质量。 - 现象：README 致谢列表包含：Johns Hopkins University 的 Rui Yang 与 Haoyu Wang 报告的内置工具图标 URL Host Header 投毒问题、Ryan B 报告的自定义 API 工具服务器 URL 的 SSRF 漏洞、汪钶楠报告的 macOS 截图助手 AppleScript 参数处理隐患。 - 影响：说明出站请求与 URL 构造路径历史上出过问题。 - 修复：使用最新版（v1.1.4 之后仍有 main 分支更新，2026-10-29 有提交）；若自建请复查自定义 API 工具的出站地址白名单。

七、与同类对比

维度 OpenAgent Dify FIM One 裸 LangGraph
后端/前端 Flask + Vue 3 Flask + Next.js FastAPI + Next.js 自己写
编排 可视化工作流 + LangGraph 可视化工作流 + 迭代/Chatflow 可视化工作流 + 动态 DAG 代码
深度研究 enable_deep_thinking 模式 无专门深度模式 ReAct + DAG 编排层 自己拼
A2A 委派 有（首页助手路由到公开 Agent） 有插件/Agent 节点 跨系统编排 自己写
许可 MIT Apache-2.0 + 商业条款 Source Available（禁多租户 SaaS/白标） 自定
数据库 必须 PostgreSQL（无 SQLite 路径） 默认可 SQLite SQLite（开发）/ PG（生产） 自选
交付 OpenAPI + SSE API Portal / API / iframe 自建

一句话对比：要 MIT 许可、要中文文档、要国内模型开箱即用、要"深度思考 + 工作流"组合 → OpenAgent；要做多租户 SaaS 或想避开许可限制 → OpenAgent；要做企业系统统一接入 + 中国信创数据库 + 确定性审批 Hook → FIM One；想要最成熟的开源低代码生态 → Dify；只写一个 Agent、不想维护平台 → 裸 LangGraph。

八、一句话推荐结论

推荐：OpenAgent 是少数把 "Deep Research 式长任务 + 可视化工作流 + 数据集 RAG + A2A 委派 + OpenAPI/SSE 交付" 装进一个 MIT 许可全栈里的项目，对国内团队尤其友好（中文文档、中文模型一应俱全），拿来做垂直行业 Agent 的内部平台是合适的；注意它的重（7 个组件、8 GB 内存起步）、"Deep Research" 只是深度思考模式这一预期落差，以及必须硬性执行 PostgreSQL 迁移的事实——它是"能落地但要规划运维"的选项，不是"clone 完 3 分钟跑起来"的玩具。

资料来源与核验状态

  • GitHub README（https://github.com/Haohao-end/openagent，已 fetch，2026-10-29）
  • docs/architecture.md（raw.githubusercontent.com，已 fetch，2026-10-29）
  • docs/README.md 与 docs/README.zh-CN.md（已 fetch）
  • docker/README.md（Docker 部署配置说明，中文，已 fetch，2026-10-29）
  • api/.env.example（已 fetch，节选前半部分）
  • GitHub API /releases/latest → tag v1.1.4，发布于 2026-06-15

不确定/待核： - 版本对应关系：v1.1.4 发布于 2026-06-15，而 main 分支 2026-10-29 仍有提交，README 描述的功能可能超出 v1.1.4 release tag；本文以 main 分支为准，未逐条比对 tag。 - docker/.env 中 IMAGE_VERSION 默认值为 0.1.0，与 GitHub Release 的 v1.1.4 不一致，两者关系未核实。 - README 顶部赞助方为 Atlas Cloud 与 Bloome（商业赞助），对产品中立性可能有影响，此处仅作事实记录。 - 许可为 MIT 依据仓库卡标注，未逐条核对仓库 LICENSE 文件原文。 - 节点类型数量、工作流节点清单取自 README 描述与 architecture.md，未 clone 核对源码注册表。