OpenAgent 详解：单二进制自托管 AI Agent 平台，30+ 模型接入、RAG 知识库、MCP 工具调用与 Casbin 工具权限

一、OpenAgent 是什么

OpenAgent 是一个开源的自托管 AI Agent 平台，由 Casbin 开源社区维护，后端 Go、前端 React，遵循 Apache 2.0 协议，GitHub 仓库 the-open-agent/openagent，目前 5.6k star、658 fork，最新版本 v2.93.0。

它与两类常见项目的区别需要先说清楚：

它不是 Agent 框架。 不需要用 Python 或 TypeScript 写编排代码。部署完成之后它自带 Web 界面、用户体系和管理后台，配置好模型 API Key，非技术人员也可以直接使用。

它不是套壳的聊天前端。 对话只是入口，平台内部还包含 RAG 知识库、BPMN 可视化工作流、定时任务、多租户、单点登录、审计日志和用量成本统计。

1.1 部署：一个可执行文件

OpenAgent 以单个二进制文件分发。前端构建产物通过 Go 的 embed 打包进二进制，默认静态资源和头像资源也一并内嵌，因此在没有外网、无法访问 CDN 的内网环境和气隙环境中同样可以正常渲染页面。

交叉编译覆盖 Linux 的 amd64 / arm64 / riscv64，以及 macOS 和 Windows 的 x86_64 / arm64。Windows 下原生运行，不需要 WSL，也不需要 Docker。

安装脚本会下载最新 release 并在 14000 端口启动服务：

# macOS / Linux / WSL
curl -fsSL https://raw.githubusercontent.com/the-open-agent/openagent/master/scripts/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/the-open-agent/openagent/master/scripts/install.ps1 | iex

可选环境变量：OPENAGENT_VERSION、INSTALL_DIR、BIN_DIR。

启动后访问 http://localhost:14000。内置 SQLite 与示例数据，无需预先准备数据库。

从源码构建需要 Go 1.25.0+ 与 Node.js 20+ / Yarn 1.x：

go build                      # 后端
cd web && yarn install && yarn start   # 前端开发服务器

也可以直接 docker-compose up。

二、核心能力

2.1 30+ 模型提供商

支持 OpenAI、Azure OpenAI、Anthropic Claude、Google Gemini、DeepSeek、Mistral、Grok、通义千问、豆包、Moonshot（Kimi）、智谱 ChatGLM、百川、文心一言、讯飞、HuggingFace、Cohere、Amazon Bedrock、OpenRouter、Ollama 等 30 余家，可以按会话切换，不需要改代码。

2.2 自主 Agent 循环与工具链

工具层位于仓库的 tool/ 目录，是自行实现的，主要包括：

工具	说明
browser-use	驱动真实浏览器完成导航、点击、填表、抓取和截图
Windows UIA	通过 Windows UI Automation 读取控件树并操作原生窗口
Shell	执行命令与脚本
Office	读写 Word / Excel / PowerPoint，支持 PPTX 模板填充、模板图片替换、SmartArt 文本编辑
Web 搜索与抓取	搜索网页并把实时内容拉进上下文，web_fetch 遇到 HTTP 403 时自动回退到浏览器抓取
MCP	接入任意 MCP Server，支持 SSE / Stdio / StreamableHTTP 三种传输

browser-use 有两种工作模式。一种是 chromedp 驱动的独立 Chrome；另一种通过 OpenAgent 官方 Chrome 扩展以 WebSocket 桥接到用户日常使用的浏览器实例，登录状态、Cookie 和已安装插件全部可用，规避了无头浏览器需要单独解决登录态的问题。

Windows UIA 工具走的是操作系统原生的 UI Automation 接口读取控件树，而不是截图后让模型识别坐标，对只有 Windows 客户端、没有开放 API 的传统软件更为可靠。

所有工具调用在界面上都是可展开的：每一次调用的工具名、传入参数和返回值都能逐步查看。

2.3 RAG 知识库

支持 PDF、Word、Excel 等文档上传，自动完成分块、向量化和索引。嵌入模型可选 OpenAI、Azure、Gemini、Qwen、Cohere、Jina、HuggingFace 以及本地模型。知识库之间相互隔离，可以按会话或按应用分配。每次生成前会先做语义检索，把最相关的片段注入上下文。

2.4 工作流与调度

BPMN 风格的拖拽式可视化编排，支持网关条件分支与并行执行，工作流和 Agent 任务都可以按周期定时触发。

2.5 消息渠道

pipe/ 目录下实现了十个平台的适配：Discord、Slack、Telegram、WhatsApp、微信公众号、微信扫码（Weixin Claw）、X 私信、Threads、Snapchat、Facebook Messenger，另有一个通用 HTTP Webhook。同一个 Agent 可以同时挂载到多个平台。

实现上通过接口区分平台能力：支持流式更新消息的平台实现 StreamPipe（先发送再持续编辑），Discord 这类必须先响应 Webhook 再处理消息的平台实现 ImmediateWebhookResponder，WhatsApp 的 hub.challenge 校验握手对应 WebhookVerifier。

2.6 OpenAI 兼容端点

配置好的 Agent 可以作为标准的 /v1/chat/completions 端点对外提供服务，并签发 API Key。外部客户端按调用 OpenAI 的方式接入即可，而实际执行的是带 RAG 检索和工具调用的 Agent，所有对话仍然写入 chat / message 日志，可查询可审计。

2.7 平台与管理后台

单点登录支持 OIDC / OAuth2 / LDAP / SAML；多租户按用户或组织隔离工作区；全部功能提供 REST API 与 Swagger UI；内置文件、图片、视频存储。

管理后台包含四块：用量统计（按应用、用户、模型维度的 Token 与成本，含图表和热力图）、活动监控（实时操作、成功率与错误率、操作类型分布与趋势）、工具管理（所有 Agent 工具的集中增删改查）、请求日志（完整请求与响应载荷，支持 JSON 格式化与过滤）。

三、最近三个月的新增功能

3.1 Agent Hub：以代码托管平台的形态管理 Agent

一个 Agent 本质上是「system prompt + 知识库 + 工具配置 + 模型选择」这样一份配置。Agent Hub 把这份配置当作可以被分享和协作的对象来管理：

• Star / Watch / Fork，计数展示在 Hub 卡片上并支持按此排序，另有 stargazers / watchers / forks 三个列表页；
• Fork 他人发布的 Agent 到自己名下继续修改；
• Issue，每条具有独立 URL，刷新不丢失视图；
• 评论区，富文本编辑器，用户名悬停显示个人卡片；
• Insights 面板，包含 Pulse（活跃度）、Contributors（贡献者）、Traffic（访问流量，自带 PV 采集）、Word Cloud（提问词云，按选定时间段统计）、Cost（成本）五个子页；
• Agent 详情页内嵌 Chat 标签页，无需跳转即可试用；
• 上架 Hub 需通过发布状态权限校验与资格检查。

其中 Word Cloud 统计的是用户实际提问内容，对于校准 Agent 的定位有直接参考价值。

3.2 工具权限：一个可复用的 Casbin 引擎

当 Agent 具备执行 Shell、操作浏览器、读写文件的能力之后，「它被允许做什么」就成为必须回答的问题。

OpenAgent 将这部分实现为独立的 guard 包，不依赖平台自身的任何类型 （不 import object、model、beego），宿主将一次工具调用映射为 Request 传入，得到一个 Effect，设计上即可被其他 Agent 项目直接复用。

判定结果为三态：

const (
    EffectAllow Effect = "allow" // 放行
    EffectAsk   Effect = "ask"   // 需要带外审批
    EffectDeny  Effect = "deny"  // 拒绝
)

ask 的具体交互由宿主实现（SSE 弹窗、Webhook、无人值守时自动拒绝），引擎只负责判定。

匹配采用四元组：

type Request struct {
    Subject  string // 调用方身份或角色
    Tool     string // 工具名，如 shell、web_fetch
    Category string // 能力类别：read / write / exec / network / sensitive
    Resource string // 本次调用中最具安全意义的参数
}

Category 用于书写粗粒度规则，避免逐个列举工具；Resource 由宿主按工具选择：Shell 工具取命令行，文件工具取路径，网络工具取域名。规则支持 * / ? 通配、角色继承与优先级排序，底层由 Casbin 完成角色解析与优先级判定，model 定义如下：

[request_definition]
r = sub, tool, cat, res

[policy_definition]
p = sub, tool, cat, res, effect, eft, rank, name

[role_definition]
g = _, _

[policy_effect]
e = priority(p.eft) || deny

[matchers]
m = (p.sub == "*" || g(r.sub, p.sub)) && gmatch(r.tool, p.tool) && gmatch(r.cat, p.cat) && gmatch(r.res, p.res)

这里有两个实现细节值得注意：策略中真实的三态效果存放在自定义的 effect 列，Casbin 的 eft 列恒为 allow，借助 priority effector 的首个匹配胜出取到最高优先级规则，再读取其真实效果；最后一列命名为 rank 而非 priority，是因为 priority 属于 Casbin 保留 token，一旦字段索引建立就会按数值升序重排策略，破坏代码中已建立的降序加载顺序。

shellcmd：解析命令行中实际会执行的程序

配套的 shellcmd 包解决的问题是：Shell 工具的权限控制不应依赖对整条命令做子串匹配。若 rm 位于黑名单，sudo rm、xargs rm、sh -c 'rm ...'、find . -exec rm {} \; 都可以绕过。

该包将命令行解析为「实际会执行哪些程序名」，会展开的场景包括命令链接与管道、子 Shell、sudo / env / xargs / timeout / nohup 等包装器（并处理会吃掉下一个 token 的短选项）、sh -c 的内联脚本、find -exec、控制关键字以及带路径前缀的程序名。

对 python -c、node -e、perl -e 这类非 Shell 解释器，只上报解释器本身而不解析其内联脚本，拦截依赖解释器名称本身。当命令无法解析为确定的程序名时（例如动态的 $CMD），返回 certain=false，由调用方按失败关闭（fail closed）处理，避免通过制造解析失败来绕过检查。

当前状态 ：guard 引擎、ToolPolicy 策略表与后台策略管理页均已合入 master，但尚未接入工具执行路径，目前处于「策略可配置、尚未生效」的阶段，审计日志中的 effect / reason / rule 字段为此预留，接通前为空。

3.3 结构化审计日志

每次工具调用输出一行 JSON（JSONL 格式），字段包含时间戳、会话 ID、类型、工具名、MCP Server、模型、参数长度、执行结果与耗时。

设计上有两点取舍：

按会话分文件，文件名即会话标识，读取方无需从交错的日志流中拆分会话。

不阻塞被审计的操作。写入交由后台协程处理，队列容量 4096，队列满时丢弃事件而非阻塞------审计目录若位于网络挂载点并出现卡顿，不能拖慢或失败正在记录的工具调用。

日志存放于二进制同级目录（与 SQLite 采用相同的目录策略），可通过 OPENAGENT_AUDIT_DIR 覆盖。外部工具以只读方式 tail 即可获取全部工具活动，无需访问数据库。

3.4 从 OpenClaw 等 Agent 迁移

支持识别服务端路径下的配置目录、其 ZIP 包，或单个 openclaw.json（JSON5 格式）。可迁移的对象包括 Agent、技能（直接读取 SKILL.md）、MCP Server、模型提供商、渠道配置，以及归档的历史会话转录与 live session 的 sqlite 文件。

迁移流程为先生成计划再执行：规划阶段实现为纯函数，计算出需要创建哪些实体、名称冲突时采取跳过 / 覆盖 / 重命名、哪些内容与现有完全一致可以不动，确认后再写入数据库，执行过程带进度反馈。

3.5 人工纠错经验库

面向的场景是：模型答错之后，如何低成本地让它不再错。改 prompt 会让 system prompt 不断膨胀并互相冲突，微调的成本与周期又与问题规模不匹配。

OpenAgent 的做法是在对话界面为每条回答提供纠正入口，直接修改文本（带 diff 对照），保存为一条 Experience 记录：

字段	含义
Question	原问题
OriginalText	模型原始回答
CorrectedText	人工修正后的回答
Reason	修改理由
Category	Fact（事实）/ Style（风格）/ Format（格式）/ Scope（边界）

召回基于向量相似度，设置两档阈值：相似度超过 0.95 时，该条人工答案被视为已批准答案直接使用；超过 0.75 时作为示例进入上下文。此外可将某条修正提升为全局规则（上限 20 条），不受相似度限制，每次生成均携带。

3.6 模型清单与计费修正

近几个版本刷新了 Silicon Flow（含 DeepSeek-V4）、智谱 GLM、Kimi、阿里百炼 Qwen、火山引擎 Doubao 的可用型号，新增 APIMart 提供商，并将新建提供商时的默认模型改为当前有效型号（此前默认值指向已下线型号，会导致首次配置即报错）。

计费方面修正为输入 Token 与输出 Token 分开计价------两者单价通常相差数倍，按单一价格计算的成本统计不具备参考价值。

3.7 其他

新增用户通知收件箱，聊天输入框支持直接粘贴文件与图片，修复 PDF 查看器与 Office Online 预览的多项 UI 问题，支持不启动服务即可读取版本号，release 二进制命名由 amd64 改为 x86_64。

四、在线体验与相关链接

环境	地址	说明
Live Demo	https://demo.openagentai.org	只读参观，无需注册
Playground	https://try.openagentai.org	可写，数据每 5 分钟重置

• 项目仓库：https://github.com/the-open-agent/openagent
• 官方文档：https://www.openagentai.org
• Discord：https://discord.gg/5rPsrAzK7S

利益相关：作者为 Casbin 开源社区成员，OpenAgent 是该社区的项目。