OpenClaw本地使用完整教程

---

目录

1. OpenClaw本地安装
2. OpenClaw基本操作
   • 启动网关
   • 停止网关
   • 重启网关
   • 查看状态
   • 查看日志
   • 杀进程
3. 接入DeepSeek模型
4. Ollama本地模型
   • 安装Ollama
   • 启动Ollama服务
   • 配置OpenClaw使用Ollama
5. 接入飞书
   • 创建飞书应用
   • 配置OpenClaw飞书插件
   • 测试连接
6. 故障排除
7. 常用命令速查

---

1. OpenClaw本地安装

安装方法

# 使用npm安装（推荐）
npm install -g openclaw

# 或使用pnpm
pnpm add -g openclaw

# 验证安装
openclaw --version

初始化配置

# 运行初始化向导
openclaw onboard

# 或手动创建配置文件
openclaw config set agents.defaults.workspace "~/.openclaw/workspace"

目录结构

~/.openclaw/
├── openclaw.json          # 主配置文件
├── workspace/             # 工作空间
├── agents/               # 代理配置
├── logs/                 # 日志文件
└── plugins/              # 插件目录

---

2. OpenClaw基本操作

启动网关

# 启动网关（前台运行）
openclaw gateway

# 启动网关并安装为系统服务
openclaw gateway install

# 启动网关服务
openclaw gateway start

# 后台运行（使用nohup）
nohup openclaw gateway > ~/.openclaw/gateway.log 2>&1 &

停止网关

# 停止网关服务
openclaw gateway stop

# 如果网关在前台运行，按 Ctrl+C

# 强制停止（如果服务未响应）
openclaw gateway kill

重启网关

# 重启网关服务
openclaw gateway restart

# 重新加载配置（不重启）
openclaw gateway reload

查看状态

# 查看网关状态
openclaw gateway status

# 查看完整状态
openclaw status

# 查看通道状态
openclaw channels status

# 查看插件状态
openclaw plugins list

查看日志

# 实时查看日志
openclaw logs --follow

# 查看最近100行日志
openclaw logs --tail 100

# 查看特定日期的日志
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

# 查看网关日志文件
cat ~/.openclaw/logs/gateway.log

杀进程

# 查找OpenClaw进程
ps aux | grep openclaw

# 查找网关进程
ps aux | grep "openclaw gateway"

# 通过端口查找进程（默认18789）
lsof -i :18789

# 杀死进程
kill <PID>

# 强制杀死进程
kill -9 <PID>

# 杀死所有OpenClaw相关进程
pkill -f openclaw

# 杀死网关服务
launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist  # macOS

---

3. 接入DeepSeek模型

获取API密钥

1. 访问 DeepSeek官网
2. 注册账号并登录
3. 进入API Keys页面
4. 创建新的API密钥

配置DeepSeek

# 方法1：通过命令行配置
openclaw config set models.providers.deepseek.apiKey "sk-your-api-key-here"
openclaw config set models.providers.deepseek.baseUrl "https://api.deepseek.com/v1"
openclaw config set agents.defaults.model.primary "deepseek/deepseek-chat"

# 方法2：编辑配置文件 ~/.openclaw/openclaw.json

配置文件示例

{
  "models": {
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com/v1",
        "apiKey": "sk-your-api-key-here",
        "api": "openai-completions",
        "models": [
          {
            "id": "deepseek-chat",
            "name": "DeepSeek Chat (V3)"
          },
          {
            "id": "deepseek-reasoner",
            "name": "DeepSeek Reasoner (R1)"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat"
      }
    }
  }
}

测试DeepSeek连接

# 重启网关应用配置
openclaw gateway restart

# 查看模型状态
openclaw status

# 测试对话
# 通过Web界面或API测试

---

4. Ollama本地模型

安装Ollama

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows
# 从官网下载安装包：https://ollama.com/download

启动Ollama服务

# 启动Ollama服务
ollama serve

# 后台运行
ollama serve > ~/.ollama/logs/ollama.log 2>&1 &

# 下载模型
ollama pull llama3.2
ollama pull qwen2.5:7b
ollama pull deepseek-coder:6.7b

# 查看已下载模型
ollama list

# 运行模型
ollama run llama3.2

配置OpenClaw使用Ollama

# 启用Ollama插件
openclaw config set plugins.entries.ollama.enabled true

# 配置Ollama端点
openclaw config set models.providers.ollama.baseUrl "http://localhost:11434"
openclaw config set models.providers.ollama.api "ollama"

# 添加Ollama模型
openclaw config set 'models.providers.ollama.models[0].id' "llama3.2"
openclaw config set 'models.providers.ollama.models[0].name' "Llama 3.2"

# 设置默认模型
openclaw config set agents.defaults.model.primary "ollama/llama3.2"

配置文件示例

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://localhost:11434",
        "api": "ollama",
        "models": [
          {
            "id": "llama3.2",
            "name": "Llama 3.2"
          },
          {
            "id": "qwen2.5:7b",
            "name": "Qwen2.5 7B"
          }
        ]
      }
    }
  },
  "plugins": {
    "entries": {
      "ollama": {
        "enabled": true
      }
    }
  }
}

---

5. 接入飞书

创建飞书应用

1. 访问 飞书开放平台
2. 登录飞书账号
3. 点击"创建企业自建应用"
4. 填写应用信息：
   • 应用名称例如：OpenClaw助手
   • 应用描述例如：AI助手机器人
5. 获取关键信息：
   • App ID（格式：cli_xxx）
   • App Secret
   • Encryption Key（可选）

配置应用权限

在飞书后台"权限管理"页面，开启以下权限：

• im:message - 接收和发送消息
• im:message:send_as_bot - 以机器人身份发送消息
• im:chat - 访问聊天
• contact:user.employee_id:readonly - 读取用户信息

配置事件订阅

1. 进入"事件订阅"页面
2. 选择"使用长连接接收事件"（WebSocket模式）
3. 添加事件：im.message.receive_v1
4. 保存配置

配置OpenClaw飞书插件

# 启用飞书通道
openclaw config set channels.feishu.enabled true

# 设置连接模式（WebSocket，无需公网IP）
openclaw config set channels.feishu.connectionMode websocket

# 配置账号信息
openclaw config set channels.feishu.accounts.main.appId "cli_your_app_id"
openclaw config set channels.feishu.accounts.main.appSecret "your_app_secret"
openclaw config set channels.feishu.accounts.main.botName "OpenClaw助手"

# 配置访问策略
openclaw config set channels.feishu.dmPolicy pairing
openclaw config set channels.feishu.groupPolicy allowlist
openclaw config set 'channels.feishu.groupAllowFrom[0]' "oc_your_group_id"

# 配置群组设置
openclaw config set channels.feishu.groups.oc_your_group_id.requireMention true
openclaw config set channels.feishu.groups.oc_your_group_id.enabled true

测试连接

1. 重启网关：

   openclaw gateway restart
   

2. 查看状态：

   openclaw channels status
   openclaw status
   

3. 在飞书中测试：

   • 搜索"OpenClaw助手"或应用ID
   • 发送测试消息
   • 如需配对，使用配对码

4. 批准配对：

   # 查看配对请求
   openclaw pairing list feishu
   
   # 批准配对
   openclaw pairing approve feishu <配对码>
   

---

6. 故障排除

网关无法启动

# 检查端口占用
lsof -i :18789

# 检查日志
openclaw logs --tail 50

# 检查配置文件
openclaw config validate

# 修复配置
openclaw doctor --fix

飞书连接失败

# 检查飞书插件状态
openclaw plugins list | grep feishu

# 查看飞书连接日志
grep -i "feishu" /tmp/openclaw/openclaw-*.log

# 检查飞书后台配置
# 1. 确认应用已发布
# 2. 确认使用"长连接"模式
# 3. 确认权限已开启

模型无法连接

# 测试DeepSeek API
curl https://api.deepseek.com/v1/models \
  -H "Authorization: Bearer sk-your-api-key"

# 测试Ollama
curl http://localhost:11434/api/tags

# 检查模型配置
openclaw config get models.providers

常见错误解决

# 错误：端口已被占用
openclaw gateway stop
kill -9 $(lsof -ti:18789)

# 错误：配置文件损坏
cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json

# 错误：权限问题
chmod 600 ~/.openclaw/agents/main/agent/auth-profiles.json

# 错误：服务未安装
openclaw gateway install
openclaw gateway start

---

7. 常用命令速查

网关管理

openclaw gateway start      # 启动
openclaw gateway stop       # 停止
openclaw gateway restart    # 重启
openclaw gateway status     # 状态
openclaw gateway install    # 安装服务
openclaw gateway uninstall  # 卸载服务

配置管理

openclaw config get <path>           # 获取配置
openclaw config set <path> <value>   # 设置配置
openclaw config unset <path>         # 删除配置
openclaw config validate             # 验证配置
openclaw doctor --fix                # 修复配置

日志管理

openclaw logs --follow      # 实时日志
openclaw logs --tail 100    # 最近100行
openclaw logs --since 1h    # 最近1小时

插件管理

openclaw plugins list       # 列出插件
openclaw plugins install    # 安装插件
openclaw plugins uninstall  # 卸载插件

通道管理

openclaw channels status    # 通道状态
openclaw channels add       # 添加通道

配对管理

openclaw pairing list feishu        # 列出配对请求
openclaw pairing approve feishu <code>  # 批准配对

系统管理

openclaw status             # 系统状态
openclaw version            # 版本信息
openclaw update             # 更新OpenClaw
openclaw help               # 帮助信息

---

总结

最佳实践

1. 定期备份配置：

   cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup
   

2. 监控日志：

   # 使用tmux或screen保持日志监控
   tmux new -s openclaw-logs
   openclaw logs --follow
   

3. 自动化启动：

   # 创建启动脚本
   echo '#!/bin/bash
   openclaw gateway start
   ollama serve' > ~/start_openclaw.sh
   chmod +x ~/start_openclaw.sh
   

4. 安全建议：

   • 保护API密钥和App Secret
   • 定期更新访问令牌
   • 限制网络访问（使用防火墙）

联系方式

如有问题，请参考：

• OpenClaw官方文档
• GitHub仓库
• Discord社区

---