OpenClaw 安装与部署手册¶

author: inRemark & qWen
version: v2026.1
date: 2026.2.28

欢迎加入“小龙虾”阵营！本手册将指导你从零开始，在本地计算机或服务器上部署 OpenClaw。OpenClaw 是一个强大的开源 AI 智能体框架，能让你的 AI 真正“动手”操作电脑。

目录¶

前置准备
方案 A：Docker 部署（推荐 ✅ 最简单/最安全）
方案 B：本地源码部署（适合开发者 🔧）
核心配置指南
首次运行与验证
常见问题排查 (FAQ)

前置准备¶

在开始之前，请确保你的环境满足以下最低要求：

硬件要求¶

CPU: 现代多核处理器 (Intel i5/Ryzen 5 或更高，Apple Silicon M1/M2/M3 完美支持)。
内存: 16GB 是推荐起步值（如果同时运行本地大模型，建议 32GB+）。
硬盘: 至少预留 20GB 空闲空间（用于存放模型缓存、向量数据库和日志）。

软件依赖¶

操作系统: macOS, Linux (Ubuntu/Debian/CentOS), Windows (WSL2 推荐)。
必装工具:
Docker & Docker Compose (方案 A 必需)
Node.js (v18+) & npm/pnpm (方案 B 必需)
Git

AI 模型准备 (二选一)¶

OpenClaw 本身不带模型，你需要准备一个“大脑”：

云端 API (推荐新手): 拥有 Anthropic (Claude 3.5/3.7), OpenAI (GPT-4o), 或 DeepSeek 的 API Key。
本地模型 (隐私优先): 安装 Ollama 或 [LM Studio]，并下载模型 (推荐: qwen2.5-coder, llama3.1, mistral)。

Docker 部署¶

优点：环境隔离，不污染本机，一键启动，安全性高（默认沙箱）。

步骤 1：获取项目代码¶

打开终端，克隆官方仓库：

git clone https://github.com/openclaw-project/openclaw.git
cd openclaw

步骤 2：配置环境变量¶

复制示例配置文件：

cp .env.example .env

使用编辑器打开 .env 文件，填入你的配置：

# .env 文件示例

# 1. 选择模型提供商 (选填一项)
LLM_PROVIDER=anthropic 
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx  # 填入你的 Key
# LLM_PROVIDER=openai
# OPENAI_API_KEY=sk-xxxxx

# 2. 模型名称
MODEL_NAME=claude-3-5-sonnet-20260101 # 或 gpt-4o, qwen2.5-coder

# 3. 本地模型设置 (如果用 Ollama)
# LLM_PROVIDER=ollama
# OLLAMA_BASE_URL=http://host.docker.internal:11434 # Mac/Win
# OLLAMA_BASE_URL=http://172.17.0.1:11434 # Linux

# 4. 安全沙箱设置 (重要！)
ALLOWED_DIRS=/workspace,/home/user/documents  # 限制 AI 只能访问这些目录
ENABLE_BROWSER_AUTOMATION=true

步骤 3：启动服务¶

在项目根目录运行：

docker compose up -d

如果是首次运行，Docker 会自动拉取镜像，可能需要几分钟。

步骤 4：访问界面¶

打开浏览器访问：

Web UI: http://localhost:3000
API 端点: http://localhost:8080

💡 提示：Docker 模式下，AI 对文件的操作仅限于挂载的 /workspace 目录，这是最安全的模式。

本地源码部署¶

优点：可直接调试代码，方便开发自定义工具 (Tools)，性能略优（无容器开销）。
警告：AI 将拥有你当前用户的权限，请务必配置好安全限制。

步骤 1：安装 `Node.js` 环境¶

确保 Node.js 版本 >= 18：

node -v  # 检查版本
npm install -g pnpm  # 推荐使用 pnpm 包管理器

步骤 2：安装依赖¶

git clone https://github.com/openclaw-project/openclaw.git
cd openclaw
pnpm install

步骤 3：配置环境与权限¶

同样复制并编辑 .env 文件（参考方案 A）。额外注意：在本地模式下，你需要手动创建允许访问的目录，并在配置中指定，否则 AI 可能无法写入文件。

mkdir -p ./claw-workspace
chmod 755 ./claw-workspace

修改 .env 中的 ALLOWED_DIRS 为绝对路径，例如：/Users/yourname/projects/openclaw/claw-workspace。

步骤 4：启动开发服务器

pnpm dev

系统编译完成后，会自动打开浏览器或在终端显示访问地址（通常是 http://localhost:3000）。

核心配置指南¶

为了让 OpenClaw 更聪明、更安全，请仔细检查以下配置项：

LLM_PROVIDER: 模型服务商, 推荐 anthropic (逻辑强), ollama (隐私强)；
MODEL_NAME: 具体模型 ID，推荐claude-3-5-sonnet, qwen2.5-coder:32b；
ALLOWED_DIRS: 关键安全项：允许 AI 读写的目录列表, 推荐仅限工作目录，严禁填 / 或 C:\；
BLOCKED_COMMANDS: 禁止执行的 shell 命令推荐 rm -rf, format, dd, sudo；
REQUIRE_APPROVAL: 高风险操作是否需要人工确认，推荐 true (强烈建议开启)；
MEMORY_DB_PATH: 长期记忆存储路径，推荐默认即可，定期备份此文件；

首次运行与验证¶

部署完成后，请进行以下“Hello World”测试：

测试 1：基础对话¶

在聊天框输入： "你好，你是谁？你能做什么？"

预期：AI 应自我介绍，并列出它可用的工具（如文件读写、搜索等）。

测试 2：文件操作（沙箱测试）

在聊天框输入： "请在允许的工作目录下创建一个名为 'test_openclaw.txt'的文件，里面写上 'Hello OpenClaw'，然后读取它的内容发给我。"

预期：
AI 规划步骤。
(若开启审批) 弹出确认框，显示即将执行的命令。
点击确认后，文件被创建。
AI 读取文件并回复内容。

测试 3：联网搜索 (需配置)

"帮我搜索一下今天最新的科技新闻，并总结三条。"

预期：AI 调用搜索工具，返回摘要。

常见问题排查 (FAQ)¶

❌ Q1: 启动报错 "Port 3000 already in use"

A: 端口被占用。

解决: 修改 .env 中的 PORT=3001，或者关闭占用 3000 端口的程序。
Docker 用户可修改 docker-compose.yml 中的端口映射 "3001:3000"。

❌ Q2: AI 说 "我没有权限访问该目录"

A: 触发了安全沙箱限制。

解决: 检查 .env 中的 ALLOWED_DIRS，确保你要操作的文件夹路径包含在内。
Docker 用户需确保该目录已正确挂载到容器内 (volumes 部分)。

❌ Q3: 连接本地 Ollama 失败

A: Docker 容器无法访问宿主机的 localhost。

Mac/Win 解决: 使用 host.docker.internal 代替 localhost。
配置: OLLAMA_BASE_URL=http://host.docker.internal:11434
Linux 解决: 可能需要添加 --network host 启动参数，或配置 Docker 桥接网络。

❌ Q4: AI 反应很慢或一直转圈

A: 可能是模型推理慢或网络问题。

解决:
如果是本地模型：尝试换一个小一点的模型 (如 7B/14B 参数量)。
如果是云端 API：检查 API Key 是否有效，网络是否能连通外网。
查看后台日志 (docker logs openclaw-core) 寻找具体错误。

❌ Q5: 如何更新 OpenClaw？

Docker:

docker compose pull
docker compose up -d --force-recreate

源码:

git pull
pnpm install
pnpm dev

接下来做什么？¶

恭喜你成功部署 OpenClaw！现在你可以：

定制工具：编写简单的 JavaScript/Python 脚本，让 AI 能操作你的特定业务软件。
建立知识库：上传你的 PDF 文档到记忆库，让 AI 成为你的私人专家。
自动化工作流：尝试让它帮你自动整理周报、监控服务器日志或批量处理图片。

⚠️ 安全警示：

随着你对 AI 信任度的增加，切勿轻易扩大 ALLOWED_DIRS 的范围或关闭 REQUIRE_APPROVAL。始终记住：AI 是副驾驶，你才是机长。