# openclaw-openwebui-moss：在 Open WebUI 中集成 OpenClaw Moss AI 代理

> 这是一个生产级的 OpenClaw 插件，让 Moss AI 代理能够在 Open WebUI 中运行，提供安全的多代理路由、严格的访问控制和基于频道的工作流，适用于编辑、开发和运维场景。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-22T15:46:17.000Z
- 最近活动: 2026-04-22T15:56:55.447Z
- 热度: 159.8
- 关键词: Open WebUI, OpenClaw, Moss, AI代理, 插件, OpenAI兼容, 多代理, 自托管
- 页面链接: https://www.zingnex.cn/forum/thread/openclaw-openwebui-moss-open-webui-openclaw-moss-ai
- Canonical: https://www.zingnex.cn/forum/thread/openclaw-openwebui-moss-open-webui-openclaw-moss-ai
- Markdown 来源: ingested_event

---

# openclaw-openwebui-moss：在 Open WebUI 中集成 OpenClaw Moss AI 代理

Open WebUI 是目前最流行的自托管大语言模型 Web 界面之一，它提供了类似 ChatGPT 的用户体验，但完全运行在自己的服务器上。而 OpenClaw 是一个新兴的 AI 代理平台，支持创建和管理多个具有不同身份和能力的 AI 代理（称为 Moss）。openclaw-openwebui-moss 项目将这两者连接起来，让你可以在 Open WebUI 中无缝使用 OpenClaw 的 Moss 代理。

## 项目定位与核心价值

这个插件的核心价值在于桥接两个优秀的开源项目：

- **Open WebUI**：提供美观、易用的 Web 聊天界面，支持多模型、多用户、对话历史等功能
- **OpenClaw Moss**：提供灵活的 AI 代理定义，支持自定义身份、上下文、工作流

通过将它们结合，你可以让团队成员通过熟悉的 Web 界面访问专门的 AI 代理——比如专门用于代码审查的 "moss-dev"、专门用于内容编辑的 "moss-editorial"，每个代理都有自己的知识库和行为规范。

## 架构设计：OpenAI 兼容层

插件的核心设计非常巧妙：它实现了一个 OpenAI 兼容的 API 层，让 Open WebUI 以为它在连接一个标准的 OpenAI 服务。

工作流程如下：

1. Open WebUI 发送标准的 OpenAI API 请求（`GET /v1/models` 或 `POST /v1/chat/completions`）
2. 插件接收请求，从文件系统加载对应的 Moss 代理配置
3. 插件构建完整的提示词（包括 IDENTITY.md + 上下文文件 + 用户消息）
4. 插件将请求转发给 OpenClaw 的 API
5. OpenClaw 返回结果，插件转换为 OpenAI 兼容格式返回给 Open WebUI

这种设计的优点是：
- Open WebUI 不需要任何修改就能使用 Moss 代理
- 任何兼容 OpenAI API 的客户端都可以使用这个服务
- 代理配置完全基于文件，版本控制友好

## 模型发现机制

插件从文件系统动态发现可用的 Moss 代理：

```
~/.openclaw/workspace/moss-models/
├── moss-dev/
│   ├── IDENTITY.md
│   └── docs/
│       └── architecture.md
└── moss-editorial/
    └── IDENTITY.md
```

每个文件夹成为一个模型，规则如下：
- 文件夹名称成为 `model.id`
- IDENTITY.md 是必需的，定义代理的身份和行为
- 递归加载所有 `.md` 和 `.txt` 文件作为额外上下文
- 无效的配置会被跳过并记录警告

这种设计让添加新代理变得非常简单——只需创建一个新文件夹并放入 IDENTITY.md。

## 提示词构建流程

当收到聊天完成请求时，插件按以下步骤构建提示词：

1. 找到请求指定的模型文件夹
2. 加载 IDENTITY.md 作为系统消息的基础
3. 从同一文件夹树加载所有上下文文件
4. 构建系统消息，包含代理身份和上下文
5. 将完整的 OpenAI 消息历史转发给 OpenClaw，前置上述系统消息

最终的提示词结构大致如下：

```
System:
<IDENTITY.md 内容>

Context:
<所有 .md/.txt 文件内容拼接>

Messages:
<完整的 OpenAI 聊天历史>
```

这让 Moss 代理能够基于预定义的上下文理解用户问题，同时保留对话的连续性。

## 可选配置

每个模型文件夹可以包含一个 `config.json` 来覆盖默认行为：

```json
{
  "agentId": "main",
  "limits": {
    "maxContextBytes": 51200
  }
}
```

- `agentId`：指定使用哪个 OpenClaw 代理（默认为 main）
- `maxContextBytes`：限制上下文大小，防止超长提示词

## 安装与部署

### 本地开发模式

```bash
# 安装依赖
corepack pnpm install
corepack pnpm build

# 设置环境变量
export OPENCLAW_API_URL=http://127.0.0.1:18789/v1/chat/completions
export OPENCLAW_MODEL=openai-codex/gpt-5.4
export OPENCLAW_GATEWAY_TOKEN=your-openclaw-gateway-token
export MOSS_MODELS_DIR=$HOME/.openclaw/workspace/moss-models
export MOSS_PROVIDER_PORT=4000

# 启动服务
node dist/provider-standalone.js
```

如果没有设置 `OPENCLAW_GATEWAY_TOKEN`，插件会尝试从 `$OPENCLAW_CONFIG_PATH` 或 `~/.openclaw/openclaw.json` 读取配置。

### Docker 部署

项目包含 Docker Compose 配置，适合生产部署：

```bash
docker compose up -d --build
```

Compose 文件会：
- 暴露 4000 端口
- 挂载主机的 `moss-models` 目录到容器
- 默认指向 `http://host.docker.internal:18789` 的 OpenClaw 服务
- 使用 `openai-codex/gpt-5.4` 作为默认网关模型（可通过环境变量覆盖）

### 嵌入 OpenClaw 运行

当作为 OpenClaw 插件加载时，嵌入的 provider 默认在 `127.0.0.1:18790` 启动，除非被 `MOSS_PROVIDER_HOST` 或 `MOSS_PROVIDER_PORT` 覆盖。

## 与 Open WebUI 集成

部署完成后，在 Open WebUI 的管理面板中添加一个新的 OpenAI 兼容连接：

1. 进入 Settings → Connections
2. 添加 OpenAI API 连接
3. API URL 设置为 `http://your-provider-host:4000`
4. API Key 可以填任意值（插件不验证）

保存后，Open WebUI 会自动发现并显示所有 Moss 代理作为可用模型：
- moss-dev
- moss-editorial
- 任何在 `moss-models/` 中添加的新代理

用户可以在聊天界面中选择这些模型，就像选择 GPT-4 或 Claude 一样。

## 应用场景

这个插件特别适合以下场景：

### 编辑团队
创建一个专门用于内容审核和编辑的 Moss 代理，配置编辑规范、风格指南、常见错误检查清单。编辑团队可以通过 Open WebUI 的统一界面访问这个代理，获得一致的辅助。

### 开发团队
为不同技术栈创建专门的 Moss 代理——比如一个专注于 React 的前端代理、一个专注于 Python 的后端代理、一个专门审查安全代码的安全代理。每个代理加载对应的文档和最佳实践。

### 运维团队
创建运维代理，配置运行手册、故障排查流程、常用命令参考。运维人员可以通过聊天界面询问 "如何处理这个告警"，代理会基于预定义的知识给出指导。

### 多租户环境
通过不同的模型文件夹隔离不同团队或项目的代理配置，每个代理只能访问自己的上下文，实现安全的多租户。

## 安全与访问控制

项目强调 "安全的多代理路由" 和 "严格的访问控制"。虽然具体实现细节需要查看代码，但从设计来看，安全机制包括：

- **文件系统隔离**：每个代理的上下文来自独立的文件夹，天然隔离
- **配置验证**：无效的配置会被跳过，防止错误配置导致的安全问题
- **Token 认证**：通过 OpenClaw Gateway Token 验证请求来源
- **请求时扫描**：新模型在请求时才会被发现和加载，避免恶意文件被自动执行

## 当前局限与未来方向

作为 MVP（最小可行产品），当前版本有一些已知局限：

- 只实现了非流式 `chat.completions`，流式响应尚未支持
- 构建 OpenClaw 提示词时只使用最后一条用户消息，完整的对话历史处理可能不完整
- 上下文加载是简单的文件拼接，没有更复杂的 RAG 或向量搜索
- 附件、工具、嵌入、向量搜索等功能超出当前范围

这些局限为未来发展留下了空间。可能的改进方向包括：
- 添加流式响应支持，提升用户体验
- 实现更智能的上下文管理，支持长对话
- 集成向量数据库，支持基于语义搜索的上下文检索
- 支持工具调用，让代理能够执行操作

## 结语

openclaw-openwebui-moss 是一个设计精良的桥接项目，它让两个优秀的开源生态系统能够协同工作。通过文件系统驱动的模型发现、OpenAI 兼容的 API 层、以及灵活的上下文配置，它为团队提供了一个强大的 AI 代理管理平台。如果你正在使用 Open WebUI 和 OpenClaw，这个插件值得尝试。