## 🦞 家用 Linux 系统 OpenClaw 部署保姆级教程
从零开始配置5个智能体 · 图文并茂 · 终端命令详解
📖 字数：5000+👶 适合新手📦 包含完整部署流程📑 目录导航
## 1. 什么是OpenClaw？
OpenClaw是一个开源的多渠道AI网关系统，它能够让你的AI助手同时在多个平台（如企业微信、QQ、飞书、钉钉、Telegram等）上运行，并且支持自定义智能体（Agents）来处理不同类型的任务。
当前最新版本为**2026.4.22**，采用MIT开源许可证，完全免费使用。项目地址：GitHub，官方文档：docs.openclaw.ai。
> 💡**核心理念**：”一个AI，多平台运行”。通过统一的后端管理系统，你可以在不同平台上部署相同的AI能力，同时根据每个平台的特点进行个性化定制。
## 2. OpenClaw能做什么
### ✅ 多渠道集成
支持20+种消息渠道，包括：飞书、钉钉、企业微信、QQ 等。
### ✅ 智能体系统
支持创建和管理多个专业智能体，每个智能体可以有不同的角色、模型和工作空间。智能体之间可以相互调用和协作。
### ✅ 强大的工具集成
内置文件操作、网络请求、浏览器控制、系统命令执行、图片生成、语音合成、视频生成等工具。
### ✅ 安全与权限管理
提供基于令牌的访问控制、权限分级、API密钥自动脱敏、完整的操作日志记录等安全机制。
## 3. 部署硬件条件
### 💻 操作系统要求
* **Ubuntu**（推荐）— 用户友好，社区支持强大
* **Debian**— 稳定可靠，适合长期运行
* **Fedora**— 较新软件包，适合技术爱好者
* **CentOS Stream**— 企业级稳定性
### ⚙️ 硬件要求
> 📝**说明**：以下硬件要求为经验估算值，实际需求取决于使用场景和并发量。
* **CPU**：2核以上（推荐 4核）
* **内存**：4GB RAM（推荐 8GB 或更多，运行多个智能体时需要）
* **存储**：至少 10GB 可用磁盘空间
* **网络**：稳定的互联网连接
### 📦 软件依赖
* **Node.js**：v22 LTS 或更高版本（OpenClaw 使用了 Node.js 22 的新特性）
* **npm**：v8.x 或更高版本
* **Git**：用于版本控制和更新
* **编译工具**：build-essential（Debian/Ubuntu）或 Development Tools（RHEL/CentOS/Fedora），某些 npm 包需要编译
## 4. Linux系统详细部署步骤
1 系统更新
BASH`# Ubuntu/Debiansudo apt update &&sudo apt upgrade -y# Fedorasudo dnf update -y# CentOS/RHELsudo yum update -y`
2 安装基础开发工具
BASH`# Ubuntu/Debiansudo apt install -y build-essential git curl# Fedorasudo dnf groupinstall -y “Development Tools”sudo dnf install -y git curl# CentOS/RHELsudo yum groupinstall -y “Development Tools”sudo yum install -y git curl`
3 安装 Node.js v22 LTS
#### 方法A：使用 NodeSource 官方仓库（推荐）
BASH`# Ubuntu/Debian — 添加 NodeSource 仓库并安装 Node.js 22curl -fsSL https://deb.nodesource.com/setup_22.x |sudo -E bash -sudo apt-get install -y nodejs# Fedora/RHEL — 添加 NodeSource 仓库并安装 Node.js 22curl -fsSL https://rpm.nodesource.com/setup_22.x |sudo bash -sudo yum install -y nodejs# 验证安装node –versionnpm –version`
#### 方法B：使用 nvm（Node Version Manager）
BASH`# 1. 安装 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh # 建议使用最新稳定版本，访问 https://github.com/nvm-sh/nvm/releases 查看|bash# 2. 重新加载 shell 配置source ~/.bashrc# 3. 安装 Node.js 22 LTSnvm install 22nvm use 22nvm alias default 22# 4. 验证安装node –versionnpm –version`
4 全局安装 OpenClaw
BASH`# 全局安装 OpenClawnpm install -g openclaw# 国内用户如遇网络问题，可配置镜像源npm install -g openclaw –registry https://registry.npmmirror.com# 验证安装openclaw –version`
> 💡**推荐：配置 npm 全局目录（避免权限问题）**
>
> `mkdir ~/.npm-globalnpm config set prefix ‘~/.npm-global’echo’export PATH=~/.npm-global/bin:$PATH’>> ~/.bashrcsource ~/.bashrc`
5 安装系统依赖（可选，浏览器功能需要）
BASH`# Ubuntu/Debian — 安装浏览器和多媒体依赖sudo apt-get install -y libx11-dev libx11-xcb-dev libsecret-1-dev libgtk-3-dev libnotify-dev libglib2.0-dev libnss3-dev libasound2-dev libxtst-dev xauth xvfb ffmpeg`
6 启动 OpenClaw
BASH`# 启动 Gateway 服务openclaw gateway start# 检查服务状态openclaw gateway status`
启动成功后，你会看到类似输出：
OUTPUTOpenClaw gateway listening on http://localhost:18789
> 💡**小贴士**：OpenClaw默认监听端口**18789**。你可以在浏览器中访问`http://localhost:18789`打开Web管理界面。
## 5. 基础配置
### 配置文件位置
OpenClaw 的配置文件位于`~/.openclaw/openclaw.json`。首次启动时 OpenClaw 会自动创建该文件。如果未自动创建，可以手动创建：`mkdir -p ~/.openclaw && touch ~/.openclaw/openclaw.json`
### 配置AI模型
编辑配置文件，添加AI模型API密钥。以下是使用**通义千问（Qwen）**的示例：
JSON`{“models”: {“providers”: {“generic”: {“baseUrl”: “https://dashscope.aliyuncs.com/compatible-mode/v1″,”apiKey”: “your-dashscope-api-key-here”,”api”: “openai-completions”,”models”: [ {“id”: “qwen3.6-plus”,”name”: “Qwen 3.6 Plus”,”contextWindow”: 999999,”maxTokens”: 4096 } ] } } }}`
### 修改默认端口（可选）
如果需要修改默认端口（18789），在配置文件中添加：
JSON`{“gateway”: {“port”: 18790 }}`
### 查看配置
BASH`# 查看当前配置openclaw gateway config# 使用记事本或编辑器手动编辑nano ~/.openclaw/openclaw.json`
## 6. 配置5个智能体
OpenClaw的强大之处在于其智能体系统。通过配置5个不同角色的智能体，你可以实现专业的任务分工。
### 5个智能体的角色介绍
🎨
美术设计师
art-designer
图像生成、视觉设计、UI/UX设计
✍️
营销文案专家
marketing-writer
文案写作、营销内容创作
🛠️
系统运维工程师
sys-ops
系统监控、故障排查、性能优化
🔍
资料搜集研究员
data-researcher
信息搜集、数据分析、市场调研
🦐
虾兵T800
shrimp-t800
编程开发、代码调试、技术方案设计
1 创建智能体工作目录
BASH`# 进入 OpenClaw 工作目录cd ~/.openclaw# 创建 workspace-agents 目录mkdir -p workspace-agents# 为每个智能体创建独立的工作目录mkdir -p workspace-agents/{art-designer,marketing-writer,sys-ops,data-researcher,shrimp-t800}`
2 为每个智能体创建 IDENTITY.md 文件
在每个智能体的工作目录中创建`IDENTITY.md`，定义身份信息。这是 OpenClaw Agent 工作空间的约定文件。
MARKDOWN`# art-designer/IDENTITY.md# IDENTITY.md- Name: 美术设计师- Creature: 视觉创意专家- Vibe: 创意、艺术、细致- Emoji: 🎨# marketing-writer/IDENTITY.md# IDENTITY.md- Name: 营销文案专家- Creature: 文案创作专家- Vibe: 专业、有说服力、创意- Emoji: ✍️# sys-ops/IDENTITY.md# IDENTITY.md- Name: 系统运维工程师- Creature: 技术运维专家- Vibe: 严谨、可靠、高效- Emoji: 🛠️# data-researcher/IDENTITY.md# IDENTITY.md- Name: 资料搜集研究员- Creature: 信息分析专家- Vibe: 仔细、客观、全面- Emoji: 🔍# shrimp-t800/IDENTITY.md# IDENTITY.md- Name: 虾兵T800- Creature: 代码开发专家- Vibe: 专业、精准、高效- Emoji: 🦐`
3 为每个智能体创建 SOUL.md 文件
`SOUL.md`定义了智能体的核心能力和工作方式。通用模板：
MARKDOWN`# SOUL.md – [智能体名称]## 🎯 核心能力### 专业技能- [列出该智能体的专业技能]### 工作风格- [描述工作风格和特点]## 📋 工作流程### 接收任务时1. 确认任务目标和预期成果2. 评估复杂度和所需资源3. 给出时间估算4. 确认优先级### 执行任务时1. 按专业领域执行任务2. 保持高质量标准3. 遇到问题及时报告4. 记录关键决策### 任务完成后1. 总结交付物2. 记录经验教训3. 更新相关文档`
根据每个智能体的特点修改相应内容。
4 在 openclaw.json 中注册智能体
编辑主配置文件，将5个智能体添加到`agents.list`数组中：
JSON`{“agents”: {“list”: [ {“id”: “main”,”name”: “main”,”model”: “generic/qwen3.6-plus” }, {“id”: “art-designer”,”name”: “art-designer”,”workspace”: “/home/你的用户名/.openclaw/workspace-agents/（工作目录位置可自定义，不一定在 .openclaw 下）art-designer”,”model”: “generic/qwen3.6-plus”,”identity”: {“name”: “美术设计师”,”emoji”: “🎨” } }, {“id”: “marketing-writer”,”name”: “marketing-writer”,”workspace”: “/home/你的用户名/.openclaw/workspace-agents/（工作目录位置可自定义，不一定在 .openclaw 下）marketing-writer”,”model”: “generic/MiniMax-M2.5″,”identity”: {“name”: “营销文案专家”,”emoji”: “✍️” } }, {“id”: “sys-ops”,”name”: “sys-ops”,”workspace”: “/home/你的用户名/.openclaw/workspace-agents/（工作目录位置可自定义，不一定在 .openclaw 下）sys-ops”,”model”: “generic/glm-5″,”identity”: {“name”: “系统运维工程师”,”emoji”: “🛠️” } }, {“id”: “data-researcher”,”name”: “data-researcher”,”workspace”: “/home/你的用户名/.openclaw/workspace-agents/（工作目录位置可自定义，不一定在 .openclaw 下）data-researcher”,”model”: “generic/qwen3-max-2026-01-23″,”identity”: {“name”: “资料搜集研究员”,”emoji”: “🔍” } }, {“id”: “shrimp-t800″,”name”: “shrimp-t800″,”workspace”: “/home/你的用户名/.openclaw/workspace-agents/（工作目录位置可自定义，不一定在 .openclaw 下）shrimp-t800″,”model”: “generic/glm-5″,”identity”: {“name”: “虾兵T800″,”emoji”: “🦐” } } ] }}`
> 📝**注意事项**
>
>
> 1. **路径**：将`/home/你的用户名`替换为实际路径
> 2. **模型选择**：每个智能体可以使用不同的 AI 模型
> 3. **模型 ID 必须存在**：引用的模型 ID 必须在对应的 provider 下有定义
> 4. **可选字段**：`agentDir`通常可省略，系统会自动创建
5 重启并测试
BASH`# 重启 OpenClawopenclaw gateway restart# 测试：给每个智能体发送自我介绍请求# 在Web界面中选择不同智能体进行对话`
## 7. 性能优化与日常维护
### 防火墙配置
#### Ubuntu/Debian (UFW)
BASH`# 允许 OpenClaw 默认端口sudo ufw allow 18789/tcp# 启用防火墙sudo ufw enable`
#### RHEL/CentOS/Fedora (firewalld)
BASH`# 允许 OpenClaw 默认端口sudo firewall-cmd –permanent –add-port=18789/tcpsudo firewall-cmd –reload`
### 自动启动配置（systemd）
创建服务文件`/etc/systemd/system/openclaw.service`：
INI`[Unit]Description=OpenClaw AI AssistantAfter=network.target[Service]Type=simpleUser=adminWorkingDirectory=/home/adminExecStart=/路径/to/openclaw gateway start# 运行 which openclaw 查看实际路径并替换Restart=alwaysRestartSec=10[Install]WantedBy=multi-user.target`BASH`sudo systemctl daemon-reloadsudo systemctl enable openclawsudo systemctl start openclaw`
> ⚠️**注意**：`ExecStart`路径需要根据你的实际安装位置调整。使用`which openclaw`查看具体路径。
### 版本更新
BASH`# npm 全局安装更新npm install -g openclaw@latest# 重启使更新生效openclaw gateway restart`
### 备份配置
BASH`# 备份配置文件cp -r ~/.openclaw ~/.openclaw-backup-$(date +%Y%m%d)# 备份智能体工作目录tar -czf openclaw-agents-$(date +%Y%m%d).tar.gz ~/.openclaw/workspace-agents/`
### 查看状态
BASH`# 查看 OpenClaw 状态openclaw status# 检查网关状态openclaw gateway status`
## 8. 常见问题解答
Q1: 安装过程中出现 “node: command not found” 错误
A: 这说明 Node.js 没有正确安装或没有添加到系统 PATH 中。请重新安装 Node.js，并确保使用 Node.js v22 或更高版本。如果使用 nvm，确保执行了`source ~/.bashrc`。
Q2: npm 安装时出现 EACCES 权限错误
A: 有两种解决方案：
**方案A（推荐）**：配置 npm 全局目录
`mkdir ~/.npm-globalnpm config set prefix ‘~/.npm-global’echo’export PATH=~/.npm-global/bin:$PATH’>> ~/.bashrcsource ~/.bashrc`
**方案B**：使用 nvm 安装 Node.js
Q3: 启动 OpenClaw 时端口被占用
A: OpenClaw默认使用 18789 端口。如果该端口被占用，可以：
`# 检查端口占用netstat -tlnp | grep :18789# 在 openclaw.json 中修改端口{ “gateway”: { “port”: 18790 } }`
Q4: 智能体无法正常响应
A: 检查以下几点：
* AI模型API密钥是否正确配置
* 智能体的工作目录路径是否正确（使用绝对路径）
* 网络连接是否正常
* 查看日志中是否有错误信息
Q5: pnpm build 报 “bash 不是内部或外部命令”
A: 这是 Windows 环境下的问题。在 Linux 系统中使用 npm 全局安装不需要手动构建。如果是源码安装，确保在 Bash 环境中运行构建命令。
Q6: 安装 node-llama-cpp 时编译失败
A: 确保已安装编译工具：
`# Ubuntu/Debiansudo apt install -y build-essential python3-dev# Fedora/RHELsudo dnf install -y gcc-c++ python3-devel`
Q7: 如何添加新的智能体？
A: 按照第6节的方法，创建新的工作目录、IDENTITY.md 和 SOUL.md 文件，然后在`openclaw.json`的`agents.list`中注册即可。完成后重启 OpenClaw。
Q8: 如何安装插件？
A: OpenClaw 插件通过 npm 安装。例如：
`# 安装飞书插件（社区版本）npm install -g @m1heng-clawd/feishu# 安装语音通话插件npm install -g @openclaw/voice-call`
安装后需要在`openclaw.json`中配置相应的插件参数。
