# 通用AI智能体解决方案部署手册

**Repository Path**: low-code-dev-lab/openclaw-enterprise-terminal-oc

## Basic Information

- **Project Name**: 通用AI智能体解决方案部署手册
- **Description**: 企业级通用AI智能体解决方案部署手册
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-29
- **Last Updated**: 2026-04-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于 OpenClaw 和活字格低代码开发平台的企业级通用AI智能体解决方案部署手册

## 用途

快速构建**能使用现有业务系统能力**的企业级通用AI智能体。

## 系统架构

解决方案由 Agent 交互层、Agent 执行层和业务系统层组成，连接了用户和业务数据。

```mermaid
flowchart TB
    U[用户]
    I[Agent交互层]
    E[Agent执行层]
    B[业务系统层]
    D[业务数据]

    U --> I --> E --> B --> D
```

## 网络拓扑

位于DMZ隔离网络的`OC端`（安装有OpenClaw） --- Internet ---→ MQTT Broker（如EMQX Cloud）/ 七牛云  --- Internet ---→ 位于安全网络的`服务器端`（安装有活字格服务器端，含Agent交互界面和业务系统）

推荐做法：

- `OC端`与 `服务器端` 之间推荐采用网络隔离，符合国安部关于使用 OpenClaw 的指导建议
- 将 `OC端` 部署在 DMZ 网络中，实现内网到 `OC端` 的单向通讯，在确保安全的前提下，提升管理的便利性，如可以在内网通过 SSH 直接操作 `OC端`

## 关于 npm 和 ClawHub 的使用说明

- 本方案中 `OpenClaw`、`@kadbbz/mqtt-channel`、`huozige-web-app-cli` 均需要通过 npm 安装，为了避免因为网络波动带来的困扰，建议使用国内的 npm 镜像站，如 `https://www.npmmirror.com/`
- 如需通过 ClawHub 安装 Skills，为了避免因为网络波动带来的困扰，建议使用国内的 ClawHub 镜像站，如 `https://cn.clawhub-mirror.com`

## 0、准备 OpenClaw

按照实际项目需要，部署 OpenClaw（测试环境中使用的版本为2026.4.5），并确保其正常工作。

推荐配置：

- 系统架构 ： x64
- 操作系统 ： Ubuntu 24.x 或更新版本
- 硬件 ： 2 Core / 8 GB RAM （10+并发）
- LLM ：公网的大模型服务，如 GPT5.4、Qwen3.5-Plus 等
- 开发环境 ： Python等（让 OpenClaw 能够通过编写脚本来覆盖长尾需求场景）
- 网络 ：需要确保该服务器可以连接到互联网（包括 MQTT Broker 和七牛云）

本方案已经对 OpenClaw 采用了隔离部署方式，推荐关闭内置的沙箱机制和命令执行限制，最大程度上释放其通用型智能体的能力。具体做法为修改 openclaw.json （通常位于 `~/.openclaw/openclaw.json` ) 的 agents 根节点下 defaults 下 sandbox 节点，将 mode 属性设置为 off ：

```json
      "sandbox": {
        "mode": "off"
      },
```

然后在 tools 根节点下 exec 节点，将 security 属性设置为 full，ask 属性设置为 off ：

```json
    "exec":{
      "security": "full",
      "ask": "off"
    }
```

因为常用而且需要安装依赖项目，推荐由技术人员为所有 Agent 安装的Skills：

- agent-browser-clawdbot ： 网页爬虫，需要安装Chromium、[配置安全策略](https://chromium.googlesource.com/chromium/src/+/main/docs/security/apparmor-userns-restrictions.md)
- rag-kb : RAG知识库，需要安装Python、pip等
- excel-xlsx ： 处理Excel文件，需要安装Python
- word-docx ： 处理Word文件，需要安装Python
- powerpoint-pptx： 处理PPT文件，需要安装Python

建议：**在 OC端 建立监控机制，如基于 ELK 的日志收集与分析方案，基于 Prometheus + Grafana 的指标监控与告警方案。具体配置方案，请参考 OpenClaw 的官方文档与社区教程。**

## 1、准备 活字格

按照官方的帮助手册，在`服务器端`安装`活字格服务管理器`程序，并确保其正常工作。

推荐配置：

- 系统架构 ： x64
- 操作系统 ： Ubuntu 24.x 或更新版本
- 硬件 ： 8 Core / 16GB RAM （20+并发）
- 数据库 ： MySQL 8 或更新版本
- 网络 ： 需要确保该服务器可以连接到互联网（包括 MQTT Broker 和七牛云）

## 2、准备 MQTT Broker

> 以 EMQX Cloud 为例，其他 MQTT Boroker 同理。

EMQX Cloud的地址：`https://cloud.emqx.com/console/`

1. 按照官方说明注册 EMQX Cloud 账号并登录
2. 新建一个 Serverless 部署 （截止 2026年4月8日，EMQX Cloud 为 Serverless 部署提供每月100万分钟的连接时间，可满足基本的验证测试要求）
3. 在新建的部署中，创建一个客户端认证，保管好用户名和密码
4. 在部署概览中，获取 MQTT 连接信息，如包含访问地址和 MQTT over TLS/SSL 端口
5. 使用 EMQX Cloud 提供的在线调试功能，尝试发布和订阅，确保该部署可以正常工作

这一步需要记录以下信息备用：

- 访问地址 ：nc166001.ala.cn-hangzhou.emqxsl.cn
- 端口 ： 8883
- 用户名 ： ？
- 密码 ： ？

## 3、准备 七牛云

> 以七牛云Kodo对象存储为例，其他对象存储的实现原理类似，但需要修改本项目中 `FILE-TRANSFER.md` 适配该服务

七牛云对象存储的官网：`https://www.qiniu.com/products/kodo`

1. 按照官方说明注册 七牛云 账号并登录
2. 按照页面提示完成实名认证（截止 2026年4月8日，七牛云为用户创建的桶提供少量的免费配额，可满足基本的验证测试要求）
3. 在控制台的密钥管理页面，启用密钥访问
4. 创建一个新的密钥，保存好AK和SK

这一步需要记录以下信息备用：

- AK：？
- SK：？

## 4、安装 MQTT-Channel

通过 npm 安装 `@kadbbz/MQTT-Channel` 插件：

```bash
openclaw plugins install @kadbbz/mqtt-channel
```

修改 openclaw.json 的 channels 根节点节点，为每一个 Agent 配置对应的 account。

假如，我们分别为两个团队创建了不同的 Agent，Workspace 和 Tools 均做好隔离，id分别是 hummer 和 lowcode。

```json
  "channels": {
    "mqtt-channel": {
      "accounts": {
        "hummer": {
          "brokerUrl": "<步骤2中记录的访问地址和端口，如mqtts://xxxxxx.ala.cn-hangzhou.emqxsl.cn:8883>",
          "username": "<步骤2中记录的用户名>",
          "password": "<步骤2中记录的的密码>",
          "topics": {
            "inbound": "<入站的Topic名，如openclaw/inbound-admin，不要和其他Agent重复，下同>",
            "outbound": "<出站的Topic名，如openclaw/outbound-admin>"
          },
          "qos": 1,
          "disableBlockStreaming": false
        },
        "lowcode": {
          "brokerUrl": "<步骤2中记录的访问地址和端口，如mqtts://xxxxxx.ala.cn-hangzhou.emqxsl.cn:8883>",
          "username": "<步骤2中记录的的用户名>",
          "password": "<步骤2中记录的的密码>",
          "topics": {
            "inbound": "<入站的Topic名，如openclaw/inbound-lowcode>",
            "outbound": "<出站的Topic名，如openclaw/outbound-lowcode>"
          },
          "qos": 1,
          "disableBlockStreaming": false
        }
      }
    }
  }
```

然后修改 bindings 根节点，添加 Agent 和 channel + account 的关联关系。

```json
  "bindings": [
    {
      "agentId": "hummer",
      "match": {
        "channel": "mqtt-channel",
        "accountId": "hummer"
      }
    },
    {
      "agentId": "lowcode",
      "match": {
        "channel": "mqtt-channel",
        "accountId": "lowcode"
      }
    }
  ]
```

最后，确保 OpenClaw 的会话模式为 `per-channel-peer`。通过 session 根节点的 `dmScope` 属性配置。

```json
  "session": {
    "dmScope": "per-channel-peer"
  },
```

重启 OpenClaw gateway，让上述修改生效。

```bash
openclaw gateway restart
```

这一步需要记录以下信息备用：

- 每个 Agent 对应的 Account 的 inboud 和 outbound Topic
  - Agent名称
  - inbound
  - outbound

## 5、部署 OC 端文件

通过 npm 安装 `活字格 Web App Cli` 程序。

```bash
sudo npm install huozige-web-app-cli -g
```

运行以下命令，测试是否安装成功。

```bash
huozige-web-app-cli status
```

创建 `/opt/openclaw_enterprise_terminal/` 目录，并确保 OpenClaw 的运行身份有 read 权限。

```bash
sudo mkdir -p /opt/openclaw_enterprise_terminal/
sudo chown <OpenClaw 的运行身份> /opt/openclaw_enterprise_terminal/ -R 
sudo chmod 755 /opt/openclaw_enterprise_terminal/
```

将本项目中的 `FILE-TRANSFER.md` 、 `HZG-INVOKE.md` 和 `bin` 目录全部上传到该目录。

修改 openclaw.json 的 env 根节点下 var 节点，配置环境变量。

```json
  "env": {
    "vars": {
      "QINIU_ACCESS_KEY": "<步骤3中记录的AK>",
      "QINIU_SECRET_KEY": "<步骤3中记录的SK>",
      "HZG_CLI_MQTT_BROKER":"<步骤2中记录的访问地址和端口，mqtts://nc166001.ala.cn-hangzhou.emqxsl.cn:8883>",
      "HZG_CLI_USERNAME":"<步骤2中记录的的用户名>",
      "HZG_CLI_PASSWORD":"<步骤2中记录的的密码>",
      "HZG_CLI_REQUEST_TOPIC":"<发送请求用的Topic名，如openclaw/hzgcli/req>",
      "HZG_CLI_RESPONSE_TOPIC":"<接收响应用的Topic名，如openclaw/hzgcli/res>",
      "HZG_CLI_TIMEOUT":"<超时时间，单位是秒，如500>",
    }
  },
```

重启 OpenClaw gateway，让上述修改生效。

```bash
openclaw gateway restart
```

这一步需要记录以下信息备用：

- HZG_CLI_REQUEST_TOPIC
- HZG_CLI_RESPONSE_TOPIC

## 6、修改 AGENTS 文件

修改每个 Agent 的 Workspace 下 `AGENTS.md` 文件（OpenClaw在构建提示词时必然会加载的文件），确保该 Agent 可以和活字格服务器正常交互。

注意： **新创建 Agent 后，也需要修改新创建 Agent 的对应文件。**

```markdown

## 安全红线

- 禁止执行需要提升权限的脚本或命令！
- 禁止修改、禁止删除 `openclaw.json` 或 `AGENTS.md`！
- 禁止创建、修改或删除 Agent！

## 业务系统优先

回答问题前，需要先阅读 `/opt/openclaw_enterprise_terminal/HZG-INVOKE.md` ,优先调用现有系统的接口，然后继续规划和执行。

## 文件传输

接收到文件 Uri 或者需要将文件发送给用户时，需要先阅读 `/opt/openclaw_enterprise_terminal/FILE-TRANSFER.md` 采用 `Qshell` 完成文件传输。

```

## 7、配置活字格 Agent 门户应用

使用活字格设计器打开 `https://gitee.com/low-code-dev-lab/open-claw-enterprise-terminal` 示例工程，将其导入到您的工程，适配您的数据库、用户管理、界面风格后再发布到 `服务器端`，成为 Agent 门户应用（如命名为 claw）。您也可以直接将这个示例工程，修改认证方式为普通认证后，发布到 `服务器端`，做学习和验证使用，默认的应用管理员角色为：`OpenClaw管理员`。

### 7.1 管理控制台

在管理控制台上，设置 claw 应用的全局变量：

- MQTT_BROKER_HOST ： 步骤2中记录的访问地址
- MQTT_BROKER_PORT ： 步骤2中记录的端口
- MQTT_BROKER_USER ： 步骤2中记录的用户名
- MQTT_BROKER_PASSWORD ： 步骤2中记录的密码
- OPENCLAW_CLIENT_NAME ： 在 OpenClaw 日志中出现的名字，如你的公司名
- MQTT_RES_CHANNEL_NAME ： 步骤5中记录的 `HZG_CLI_REQUEST_TOPIC` （**不是步骤4中的！**）
- MQTT_REQ_CHANNEL_NAME ： 步骤5中记录的 `HZG_CLI_RESPONSE_TOPIC`
- QINIU_AK ： 步骤3中记录的 AK
- QINIU_SK ： 步骤3中记录的 SK
- QINIU_BUCKET_IN ：用于存放发给 `OC端` 的文件的桶名，如：openclaw-in

### 7.2 Agent 门户应用

登录到 `claw` 后，在 `Agent管理` 页面中注册你的 Agent，与步骤4的 Agent 配置一一对应。每一个希望让用户操作的 OpenClaw Agent，都需要在这里注册。

- Agent/小组名称 ： 步骤4中记录的 Agent 名称
- Inbound-Channel ： 步骤4中记录的该 Agent 对应的 `inbound` （**不是步骤5中的！**）
- Outbound-Channel ： 步骤4中记录的该 Agent 对应的 `outbound`

然后修改 `Template` 提示词模板，其中提供了三个用于替换的关键字：

- [Input] ： 用户输入的问题，必须保留
- [Session] : `服务器端`的会话 ID，“一个用户+一个 Agent 的组合”对应了一个会话。这个信息会影响鉴权，必须保留
- [UserName] ： 当前使用的用户名，可选

最后修改 `Users` 字段，设置有权限使用该 Agent 的用户列表，多个用户间采用半角逗号分隔。

建议： **为小组建立共享的 Agent，而不是为每个员工建立 Agent，这样能通过工作文件共享来提升协作效率**

重要： **注册 Agent 后，需要在管理控制台中重启活字格应用方可生效！**

### 7.3 测试一下

在 `开始对话` 页面中，选择一个 `AI助理`（即 Agent/小组），和 AI 交流。如上传一个文本文件，让AI阅读后告诉你文件中的内容，以确保系统工作正常、通讯链路顺畅。

## 8、连接活字格 App

### 8.1 生成并上传 Ontology 文档

`Ontology文件` 是 OpenClaw 可以像人类员工一样操作使用活字格开发的 Web App的关键。 `Ontology文件` 中包含了该 App 中所有实体、动作和关系，可以帮助 AI 理解企业的业务本身，更好的选择最合适的 WebAPI。

`Ontology文件` 是一个包含了诸多 markdown 文件的文件夹，使用 `huozige-ontology-builder` 生成。

安装生成工具：

```bash
npm install -g huozige-ontology-builder
```

使用生成工具：

```bash
huozige-ontology-builder https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample --workdir /tmp/hzg-workspace
```

其中 `https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample` 为您需要添加的应用的活字格元数据（协同工程）地址，`/tmp/hzg-workspace` 是用来存放生成结果的目录，结果在该目录的时间戳子文件夹的 results 目录下。

`Ontology文件` 统一存储在 `OC端` 的 `/opt/openclaw_enterprise_terminal/ontology` 文件夹中（如果不存在，需要手动创建）。每个 App 对应了一个子文件夹，如 wms App（活字格中应用名是 wms ）的 `Ontology文件` 需要上传到 `/opt/openclaw_enterprise_terminal/ontology/wms`，上传时需要注意，`index.md` 务必要直接放到该文件夹，不要再套一层子文件夹。

为了进一步提升 OpenClaw 操作业务系统的准确性，推荐按照以下最佳实践，对活字格的应用进行重构：

- 确保表、列、服务端命令和输入输出参数的命名具有业务含义，不要使用无意义的词语，如 `abc` 等
- 表名、列名和参数名需要使用名词，而且该名词需要在整个企业内统一，如将 `Order`、`订单`、`PO单` 等统一称为`订货单`；将 `SN`、`序列号`、`串号`统一称为`单号`。
- 服务端命令需要使用名词和动词的组合，且名词需要和表名、列名保持一致，如 `创建订货单`、`修改订货单的单号`
- 服务端命令中的参数如果是枚举值，需要在备注中补充可以接受的值，如 `修改产品状态` 的 `状态` 参数，需要在备注中写清 `0为正常，1为仅直销，2为停售`
- 为表、列设置别名，为服务端命令增加描述，为参数增加备注，都能帮助 AI 更好的理解您的业务，但需要确保这些人工编写的信息和实际业务逻辑保持一致，修改逻辑时，也要同步修改这些内容
- 对于能够建立起关联的表，尽量建立关联，这将会帮助 AI 更好的理解相关业务
- 保持服务端命令的“单一职责”，尽量避免用同一个服务端命令承载多项业务（通过参数来做区分具体的业务逻辑）。如果不能进行逻辑层面的重构，也可以尝试为该参数增加备注，能够在一定程度上缓解 AI 的误解风险
- 保持数据表的设计满足主流数据库设计范式，每张表中仅存放一类业务数据，该数据需要和表名的业务含义保持一致。字典表也要遵循本原则。如不要将 `客户` 和 `供应商` 存放在同一张表，也不要将 `供应商类型枚举` 与 `单据类型枚举` 存放在同一张表。
- 如果某个表仅通过 `图文列表`、`图表`、`ELementPlus系列` 单元格类型（如 `EL选择器`）绑定使用， `Ontology文件` 中将不会包含读取该表数据的能力，这在主数据、字典数据上并不罕见，建议专门开发查询该表的服务端命令或在孤立的页面中放置绑定了该表的 `表格`，作为补充

注意：**更新发布 Web App 后，需要在将工程推送至 Git 后，重新生成 Ontology 文件，并上传到 OC 端，确保 AI 能够理解最新版 App 的操作方法。**

### 8.2 注册 App 信息

登录到 claw 后，在 `应用管理` 页面，注册该应用。

- 应用名称： 发布到服务器上的应用名
- 应用访问地址： 该应用的访问地址，通常为 `http://localhost:{port}/{appName}`

### 8.3 测试一下

在 `开始对话` 页面中，选择一个 `AI助理`（即 Agent/小组），和 AI 交流。如询问 AI 该应用开放的能力清单，以确保 `Ontology文件` 被成功加载；请 AI 帮你执行一个简单的查询操作，以确保 `活字格Web APP Cli` 和通讯链路正常运行。

### 8.4 技术限制

截止活字格 v11.0 Update 1 版本，本方案存在以下技术限制：

- 无法读取活字格 App 存储在数据库的文件（含附件和图片），也无法上传文件到活字格 App。这将导致附件/图片类型的列，和附件/图片类型的参数在调用时被忽略

## 协议

MIT