OpenClaw 完全指南

OpenClaw 是一款开源的 AI 编码助手，专注于在终端中以 CLI 方式提供智能编码辅助。它属于与 Claude Code、OpenAI Codex、Hermes Agent 同类的自主编码代理，通过工具调用与代码仓库、终端、文件系统交互。

OpenClaw 以简洁高效著称，安装包小、启动快，在资源受限的环境（如低配 VPS、ARM 设备）上表现出色。

一、架构概述

OpenClaw 采用单进程架构，核心组件包括：

• 工具调用层 — 管理文件读写、终端执行、代码搜索等工具的调用
• 会话管理 — 管理历史对话上下文窗口
• LLM 适配层 — 对接多种模型提供商（OpenAI、Anthropic、本地模型等）

数据存储：

• 会话缓存：~/.openclaw/sessions/
• 配置文件：~/.openclaw/config.yaml + ~/.openclaw/.env
• Keyring：支持系统密钥环或环境变量

二、安装方式

方式一：一键安装（推荐）

curl -fsSL https://raw.githubusercontent.com/OpenClaw/openclaw/main/scripts/install.sh | bash

安装后验证：

openclaw --version
openclaw doctor

方式二：pip 安装

pip install openclaw

推荐在虚拟环境中安装：

python -m venv .venv
source .venv/bin/activate
pip install openclaw

方式三：npm 安装

npm install -g openclaw

方式四：Homebrew（macOS）

brew tap openclaw/tap
brew install openclaw

三、Docker 部署

OpenClaw 提供官方 Docker 镜像：

docker pull openclaw/openclaw:latest

基本用法

docker run -it --rm \
  -v $(pwd):/workspace \
  -v ~/.openclaw:/home/openclaw/.openclaw \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  openclaw/openclaw:latest \
  openclaw

Docker Compose 持久化运行

# docker-compose.yml
version: '3.8'
services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    working_dir: /workspace
    volumes:
      - $(pwd):/workspace
      - ~/.openclaw:/home/openclaw/.openclaw
    env_file:
      - .env
    stdin_open: true
    tty: true
    command: tail -f /dev/null  # 保持容器运行，然后 docker exec 进入

使用：

docker compose up -d
docker exec -it openclaw openclaw

Docker 部署注意事项

• 务必挂载工作目录（$(pwd):/workspace），否则 OpenClaw 无法访问项目文件
• 配置目录 ~/.openclaw 需要持久化，否则每次重新配置
• API Key 通过环境变量或 .env 文件传入
• ARM64 镜像完全可用，在树莓派、Oracle ARM 上运行流畅
• 交互模式需要 stdin_open: true 和 tty: true

四、初始化配置

配置 API Key

openclaw config set OPENAI_API_KEY sk-xxxxxxxx
# 或使用环境变量
export OPENAI_API_KEY=sk-xxxxxxxx

选择模型

openclaw config set model gpt-4o
openclaw config set model claude-sonnet-4-20250514

查看配置

openclaw config list
openclaw doctor          # 检查环境

五、核心功能

代码库感知

OpenClaw 会自动扫描项目结构，建立文件索引：

cd /path/to/your/project
openclaw                 # 在当前目录启动，自动加载项目上下文

工具调用

OpenClaw 支持以下核心工具：

• 文件操作： 读、写、搜索、替换文件内容
• 终端执行： 运行命令并捕获输出
• 代码搜索： grep/sed 语义感知搜索
• Git 集成： 查看 diff、创建 commit、推送
• Web 获取： 读取 URL 内容（文档、API 参考）

Session 管理

openclaw --continue      # 恢复上次会话
openclaw --new           # 开启新会话
openclaw session list    # 查看所有会话

单次查询模式

openclaw -q "这段代码有什么问题？"
# 适合脚本集成或快速查询

六、WebUI 常见问题 (FAQ)

Q: WebUI 页面无法打开或显示空白

原因：

• WebUI 服务未启动
• 端口被防火墙屏蔽
• 反向代理配置错误

解决：

# 确认 WebUI 进程运行
ps aux | grep openclaw

# 检查端口
ss -tlnp | grep 8080

# 重启 WebUI
openclaw webui restart

Q: "Error: Connection refused" 无法连接 LLM

原因： API Key 配置错误或网络不通。

解决：

• 执行 openclaw doctor 检查连接
• 确认 API Key 有效：curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models
• 检查是否需要配置代理（HTTPS_PROXY 环境变量）
• 如果使用本地模型（Ollama/LM Studio），确认本地服务正在运行

Q: WebUI 操作缓慢或卡顿

原因：

• 大文件导致上下文过长
• 模型推理速度慢
• 服务器资源不足

解决：

• 使用 .openclawignore 排除无关文件（类似 .gitignore）
• 切换到更快的模型（如 gpt-4o-mini 或 claude-haiku）
• 减少当前会话的文件上下文量

Q: "Permission denied" 无法写文件

原因： OpenClaw 运行用户对目标目录无写权限。

解决：

• 检查目录权限：ls -la
• Docker 部署时注意 volume 挂载的用户 UID 匹配
• 使用 sudo 或调整目录权限

Q: 会话历史丢失

原因：

• Docker 容器重启未挂载持久化卷
• 手动清除了 ~/.openclaw/sessions/
• 磁盘空间不足导致写入失败

解决：

• Docker 部署务必挂载 ~/.openclaw 数据卷
• 检查磁盘空间：df -h

Q: "Rate limit exceeded" 速率限制

原因： API 调用频率超过提供商限制。

解决：

• 降低请求频率
• 升级 API 套餐（更高 tier）
• 配置多个 API Key 轮换（openclaw config set api_keys）
• 切换到不限制速率的提供商（如本地模型）

Q: 代码搜索返回结果不准确或为空

原因： 项目文件过多，搜索索引未正确建立。

解决：

• 确保 .openclawignore 正确配置，排除 node_modules、.git 等目录
• 使用更精确的搜索关键词
• 检查是否在正确的项目根目录启动

七、进阶技巧

.openclawignore 配置

类似 .gitignore，排除不需要加载的文件：

node_modules/
dist/
build/
*.min.js
*.map
vendor/
__pycache__/
*.pyc
.env
.git/

自定义提示词 (System Prompt)

openclaw config set system_prompt "你是一个精通 Python 和 Web 开发的专家助手。回答问题要简洁，优先提供代码示例。"

多项目工作流

为每个项目创建独立的配置文件：

# 在项目根目录创建 .openclaw/config.yaml
model: claude-sonnet-4
system_prompt: "专注于 React 和 TypeScript 开发"

八、相关资源

• GitHub：github.com/openclaw/openclaw
• 官方文档：openclaw.dev/docs