环曜Claw实操：30分钟完成企业AI Agent本地私有化部署

企业部署AI Agent时面临一个核心矛盾：云服务方便但数据出境风险大，自建系统功能完整但搭建周期按周计。传统路径——采购服务器、安装系统、配置网络、部署数据库、搭建后端、配置模型、对接知识库——一个完整流程走下来，没有3-5天搞不定。

环曜Claw的思路是将AI Agent平台的通用能力（对话引擎、RAG知识库、工具调用、工作流编排）容器化打包，提供开箱即用的docker-compose部署方案。本文完整演示从git clone到创建第一个Agent的30分钟全流程。

一、环曜Claw方案简介

环曜Claw是一个开源的、本地优先的AI智能体执行网关，核心特性如下：

二、环境准备（5分钟）

硬件要求

软件前置条件

# 1. 检查Docker和Compose
docker --version  # 需要 Docker 24.0+
docker compose version  # 需要 Docker Compose v2.0+

# 2. 检查系统资源
free -h  # 确认内存 ≥ 16GB
df -h /  # 确认磁盘 ≥ 50GB

# 3. 安装Docker（如未安装）
curl -fsSL https://get.docker.com | bash
sudo usermod -aG docker $USER  # 退出重新登录生效

预期输出示例：

$ docker --version
Docker version 24.0.7, build afdd53b

$ docker compose version
Docker Compose version v2.24.2

三、一键部署（15分钟）

3.1 下载部署包

# 克隆环曜Claw部署仓库
git clone https://github.com/huanyao-claw/deploy.git
cd deploy

# 查看目录结构
ls -la
# 预期输出: docker-compose.yml  .env  config/  data/  logs/

3.2 配置环境变量

# 复制配置模板
cp .env.example .env

# 编辑核心配置（用vim或nano）
vim .env

关键配置项说明：

3.3 启动服务

# 启动所有服务
docker compose up -d

# 查看启动状态
docker compose ps

# 预期输出（关键服务就绪）：
# NAME                   STATUS
# claw-engine            Up 0.0.0.0:8080->8080
# claw-knowledge         Up 0.0.0.0:8081->8081
# claw-chat              Up 0.0.0.0:8082->8082
# postgres               Up 0.0.0.0:5432->5432
# elasticsearch          Up 0.0.0.0:9200->9200

# 查看启动日志（确认无Error）
docker compose logs --tail=50 | grep -i error
# 预期输出：无错误日志

3.4 验证部署

# 验证后端API
curl -s http://localhost:8080/api/health | python3 -m json.tool
# 预期输出：
# {
#   "status": "ok",
#   "version": "1.0.0",
#   "services": {
#     "database": "connected",
#     "elasticsearch": "connected",
#     "llm": "connected"
#   }
# }

# 访问前端页面
# 浏览器打开 http://localhost:8080
# 默认账号: admin@huanyao.com / 密码: 首次登录时设置

四、基础配置与创建Agent（10分钟）

4.1 接入AI模型

在系统设置中配置模型连接，支持三种方式：

# 方式1：本地Ollama模型（推荐）
# 在Ollama中拉取模型后，设置LLM_BASE_URL=http://ollama:11434
# 已测试兼容模型：qwen2.5:7b、llama3.1:8b、deepseek-coder:6.7b

# 方式2：云端API（需外网）
# 设置LLM_BASE_URL=https://api.openai.com/v1
# 设置API_KEY=sk-xxx

# 方式3：企业专有模型
# 设置LLM_BASE_URL=http://internal-model:8000/v1
# 需符合OpenAI API协议

4.2 创建第一个Agent

通过Web界面：登录后台 → 智能体管理 → 创建智能体 → 填写名称/描述/模型/工具 → 保存

或者通过API：

curl -X POST http://localhost:8080/api/agents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "企业知识助手",
    "description": "基于企业知识库的智能问答助手",
    "model": "qwen2.5:7b",
    "tools": ["knowledge_search", "web_search", "code_executor"],
    "knowledge_ids": ["kb-001"]
  }'
# 预期输出：{"id": "agent-001", "status": "active"}

五、踩坑记录与避坑指南

常见问题 Q&A

Q1：服务启动后无法访问前端？

A1：90%的原因是防火墙未放行8080端口，检查firewall-cmd --list-ports（CentOS）或ufw status（Ubuntu）。也可能是SELinux导致，运行setenforce 0临时关闭确认。

Q2：模型加载后对话不响应？

A2：检查模型名称是否正确——Ollama中ollama list查看实际名称，注意大小写和版本号（如qwen2.5:7b而非qwen2.5）。

Q3：Elasticsearch内存不足导致启动失败？

A3：ES默认占用1/2系统内存，在.env中设置ES_HEAP_SIZE=2g限制为2GB，同时确保系统vm.max_map_count ≥ 262144：sudo sysctl -w vm.max_map_count=262144。

Q4：知识库文档上传后检索不到？

A4：文档需先经过embedding处理，检查embedding模型是否已加载。首次使用建议先上传3-5个测试文档，确认检索正常后再批量上传。

六、性能验证与对比

七、适用边界与风险提示

本方案适用于单机部署，高可用集群部署需额外配置（负载均衡、主从复制、数据备份）。对于日均请求量大于10万次的场景，建议使用Kubernetes集群模式。

本地模型效果受限于硬件配置，4核16G环境下7B模型推理延迟约2-5秒。如需更低延迟，建议升级GPU或使用云端API模式。

生产环境注意数据备份：PostgreSQL和Elasticsearch数据目录需纳入定期备份策略。建议配置凌晨自动备份脚本。

常见问题 FAQ