openclaw使用配置 windows

# OpenClaw 完整配置与使用指南

> 版本：OpenClaw 2026.3.8  
> 整理日期：2026-03-25

---

## 目录

1. [基础安装](#一基础安装)
2. [核心命令速查](#二核心命令速查)
3. [插件管理](#三插件管理)
4. [技能管理](#四技能管理)
5. [浏览器控制](#五浏览器控制)
6. [设备与配对](#六设备与配对)
7. [飞书机器人配置](#七飞书机器人配置)
8. [模型配置](#八模型配置)
9. [完整配置模板](#九完整配置模板)
10. [常见问题](#十常见问题)
11. [联网搜索](#十一联网搜索)
12. [其他命令](#十二其他命令)

---

## 一、基础安装

### 1. 环境准备

```bash
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source /root/.bashrc

# 安装 Node.js 22
nvm install 22
nvm use 22

# 安装系统依赖（CentOS/RHEL）
yum update -y
yum install -y glibc libstdc++ git

# 如果没有 GPU，安装编译工具
sudo yum groupinstall "Development Tools" -y
sudo yum install cmake -y

2. 安装 OpenClaw

# 方式一：源码安装
git clone https://github.com/openclaw/openclaw
cd openclaw
npm install

# 方式二：全局安装
npm install -g openclaw

3. 清理重装（故障恢复）

# 1. 清理 npm 缓存
npm cache clean --force

# 2. 卸载旧版本
npm uninstall -g openclaw

# 3. 设置 CPU 模式（无 GPU）
export LLAMA_CPP_NO_CUDA=1

# 4. 重新安装
npm install -g openclaw

4. 安装后检查

# 方案一：使用 openclaw 自带的状态检查
openclaw status

# 方案二：检查网关端口（默认 18789）
netstat -tuln | grep 18789

# 方案三：查看进程列表
ps aux | grep openclaw

---

二、核心命令速查

状态检查

命令	说明
openclaw status	查看整体状态
openclaw doctor	诊断检查
openclaw doctor --fix	自动修复问题

网关管理

命令	说明
openclaw gateway start	启动网关
openclaw gateway stop	停止网关
openclaw gateway restart	重启网关
openclaw gateway --verbose	前台启动（调试模式）

日志查看

# 查看日志
openclaw logs

# 实时跟踪日志
openclaw logs --follow

# 过滤关键信息（工具调用、MCP、错误等）
openclaw logs --follow | grep -E "(tool|function|ddg|mcp|error)"

# 保存日志到文件并分析
openclaw gateway --verbose 2>&1 | tee /tmp/gateway.log &
grep -E "(tool|function|ddg|mcp|agent|llm)" /tmp/gateway.log

---

三、插件管理

插件操作命令

# 查看插件
openclaw plugins list
openclaw plugins status

# 安装插件
openclaw plugins install <plugin-name>

# 启用/禁用/更新
openclaw plugins enable <plugin>
openclaw plugins disable <plugin>
openclaw plugins update <plugin>

常用插件安装

# MCP 适配器（核心）
openclaw plugins install openclaw-mcp-adapter

# 飞书插件
openclaw plugins install @larksuiteoapi/feishu-openclaw-plugin@2026.3.7

# Algorand 插件
openclaw plugins install @goplausible/openclaw-algorand-plugin

# Basic Memory 插件
openclaw plugins install @basicmemory/openclaw-basic-memory

MCP 配置流程

# 1. 安装 MCP 适配器
openclaw plugins install openclaw-mcp-adapter

# 2. 验证配置（不重启）
openclaw config validate

# 3. 重启网关加载新配置
openclaw gateway restart

# 4. 查看已加载的工具
openclaw tools list

# 5. 检查 MCP 服务器状态
openclaw doctor

---

四、技能管理

技能操作命令

openclaw skills list                    # 列出已安装技能
openclaw skills info <skill-name>      # 查看技能详情
openclaw skills enable <skill-name>    # 启用技能
openclaw skills disable <skill-name>   # 禁用技能
openclaw skills uninstall <skill-name> # 卸载技能

安装技能

# 从 npm 安装
openclaw skills install @openclaw/skill-name

# 从本地安装
openclaw skills install /path/to/skill

# 从 GitHub 安装
openclaw skills install github:用户名/仓库名

推荐技能清单

基础技能

• mcp-adapter
  
  – MCP 适配器
• summarize
  
  – 文本总结
• multi-search-engine
  
  – 多搜索引擎
• self-improving
  
  – 自我改进

工具类

• skill-vetter
  
  – 技能审查
• find-skills
  
  – 查找技能
• stock-watcher
  
  – 股票监控
• tavily-search
  
  – Tavily 搜索

内容创作

• copywriting
  
  – 文案写作
• content-strategy
  
  – 内容策略
• marketing-ideas
  
  – 营销创意
• social-content
  
  – 社交媒体内容

设计类

• web-design-guidelines
  
  – Web 设计规范
• ui-ux-pro-max
  
  – UI/UX 专业版
• canvas-design
  
  – Canvas 设计
• tailwind-design-system
  
  – Tailwind 设计系统
• algorithmic-art
  
  – 算法艺术

安全与测试

• skills-sec-audit
  
  – 技能安全审计
• api-testing-observability
  
  – API 测试与可观测性
• test-driver-development
  
  – 测试驱动开发
• seo-audit
  
  – SEO 审计
• page-cro
  
  – 页面转化率优化

浏览器与自动化

• agent-browser
  
  – Agent 浏览器
• playwright-cli
  
  – Playwright 命令行
• skyvern
  
  – Skyvern 自动化
• openfang
  
  – OpenFang 工具

Agent 管理

• agent-orchestration
  
  – Agent 编排
• agent-team-agile-workflow
  
  – Agent 团队敏捷工作流
• agents-language-specialists
  
  – 语言专家 Agents
• agents-specialized-domains
  
  – 专业领域 Agents

---

五、浏览器控制

openclaw browser status              # 检查浏览器状态
openclaw browser start               # 启动浏览器
openclaw browser open <url>          # 打开网页，如 https://www.baidu.com
openclaw browser screenshot          # 截图

---

六、设备与配对

# 列出设备
openclaw devices list

# 批准设备连接
openclaw devices approve <device-id>

# 列出频道
openclaw channels list

# 频道状态
openclaw channels status

---

七、飞书机器人配置

7.1 单机器人配置

编辑配置文件（openclaw config edit）：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "domain": "feishu",
      "connectionMode": "websocket",
      "groupPolicy": "open",
      "appId": "cli_a92ff21ac7xxxxxxxxx",
      "appSecret": "6gxuD0r6jx0IGbxxxxxxxxxxx"
    }
  }
}

7.2 多机器人配置

支持配置多个飞书机器人，通过不同 ID 区分：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "domain": "feishu",
      "connectionMode": "websocket",
      "groupPolicy": "open",
      "accounts": [
        {
          "id": "default",
          "appId": "cli_a92ff21xxxxxxxx",
          "appSecret": "6gxuD0r6jx0IGxxxxxxxxx"
        },
        {
          "id": "seniortest",
          "appId": "cli_a93be57xxxxxxxx",
          "appSecret": "hkOTVCwPVIEHBxxxxxxxxxx"
        }
      ]
    }
  },
  "session": {
    "dmScope": "per-account-channel-peer"
  }
}

说明：

• id
  
  : 账号唯一标识，用于绑定规则匹配
• dmScope
  
  : 会话隔离级别，per-account-channel-peer确保不同机器人会话互不干扰

7.3 绑定 Agent

通过 bindings配置不同机器人使用不同 Agent 处理消息：

{
  "bindings": [
    {
      "agentId": "main",
      "match": {
        "channel": "feishu",
        "accountId": "default"
      }
    },
    {
      "agentId": "seniortest-agent",
      "match": {
        "channel": "feishu",
        "accountId": "seniortest"
      }
    }
  ]
}

特定群绑定（可选）：

{
  "agentId": "seniortest-agent",
  "match": {
    "channel": "feishu",
    "accountId": "seniortest",
    "peer": {
      "kind": "group",
      "id": "oc_xxxxxxxxx"
    }
  }
}

7.4 配置生效

# 修改配置后必须重启网关
openclaw gateway restart

7.5 参考文档

• 飞书配置教程：https://juejin.cn/post/7613330850830843954

---

八、模型配置

8.1 vLLM 配置示例

编辑 ~/.openclaw/config.json：

{
  "models": {
    "mode": "merge",
    "providers": {
      "vllm": {
        "baseUrl": "http://10.35.208.xxxx:3001/v1",
        "apiKey": "",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen",
            "name": "qwen",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "vllm/qwen"
      },
      "models": {
        "vllm/qwen": {}
      },
      "workspace": "/root/.openclaw/workspace",
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  }
}

8.2 Agent 专属配置

如需为特定 Agent 单独配置模型，检查并编辑：

/root/.openclaw/agents/main/agent/models.json

十、常见问题

10.1 Control UI 访问被拒绝

错误信息：

open the Control UI from the gateway host or allow it in gateway.controlUi.allowedOrigins

解决方案：

在配置中添加允许的源：

{
  "gateway": {
    "controlUi": {
      "allowedOrigins": [
        "https://192.168.125.186:18789",
        "https://localhost:18789"
      ]
    }
  }
}

10.2 Agent 连接错误

错误信息：

[agent/embedded] embedded run agent end: runId=xxx isError=true error=Connection error.

解决方案：

检查 Agent 专属模型配置是否正确传递：

# 检查 Agent 模型配置
cat /root/.openclaw/agents/main/agent/models.json

# 确保与主配置一致，必要时手动同步

10.3 调试模式

# 设置 debug 日志级别
openclaw config set logging.level debug
openclaw gateway restart

# 前台启动并记录详细日志
openclaw gateway --verbose 2>&1 | tee /tmp/gateway.log &

# 分析日志
grep -E "(tool|function|ddg|mcp|agent|llm|error)" /tmp/gateway.log

10.4 CentOS 8 源失效

CentOS 8 停止维护后，使用临时腾讯云源：

sudo yum groupinstall "Development Tools" -y \
  --disablerepo=* \
  --enablerepo=temp-tencent-base \
  --enablerepo=temp-tencent-appstream \
  --repofrompath=temp-tencent-base,https://mirrors.cloud.tencent.com/centos-vault/8.5.2111/BaseOS/x86_64/os/ \
  --repofrompath=temp-tencent-appstream,https://mirrors.cloud.tencent.com/centos-vault/8.5.2111/AppStream/x86_64/os/

10.5 快速诊断流程

# 1. 停止当前网关
openclaw gateway stop

# 2. 前台启动查看详细日志
openclaw gateway --verbose 2>&1 | tee /tmp/gateway.log &

# 3. 发送测试消息，然后查看日志
grep -E "(tool|function|ddg|mcp|error)" /tmp/gateway.log

---

十一、联网搜索

11.1 工作原理

联网搜索通过内置工具链完成：

1. web_search
   
   – 查找链接
2. web_fetch
   
   – 读取内容

11.2 配置搜索 API

参考文档：https://blog.csdn.net/xieyan0811/article/details/157944593

11.3 推荐搜索服务

Brave Search

• 免费套餐：每月 2000 次查询
• 注册地址：https://brave.com/search/api
• 注意：需要信用卡验证（部分国内信用卡可能不支持）

---

十二、其他命令

12.1 ACP 调试

# 启动 ACP 调试客户端
openclaw acp client

# 连接远程 Gateway
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

12.2 配置管理

# 编辑配置
openclaw config edit

# 验证配置
openclaw config validate

# 设置配置项
openclaw config set <key> <value>

12.3 进程管理

# 强制停止
pkill -9 openclaw

---

附录：Clawhub 技能安装清单

# 基础技能
clawhub install mcp-adapter
clawhub install summarize
clawhub install multi-search-engine
clawhub install self-improving

# 工具技能
clawhub install skill-vetter
clawhub install find-skills
clawhub install stock-watcher
clawhub install tavily-search

# 内容技能
clawhub install copywriting
clawhub install systematic-debugging
clawhub install content-strategy
clawhub install marketing-ideas
clawhub install social-content

# 设计技能
clawhub install web-design-guidelines
clawhub install ui-ux-pro-max
clawhub install canvas-design
clawhub install tailwind-design-system
clawhub install algorithmic-art

# 安全技能
clawhub install skills-sec-audit

# 浏览器技能
clawhub install agent-browser
clawhub install playwright-cli

# Agent 技能
clawhub install agent-orchestration
clawhub install agent-team-agile-workflow
clawhub install agents-language-specialists
clawhub install agents-specialized-domains

# 测试技能
clawhub install api-testing-observability
clawhub install test-driver-development
clawhub install seo-audit
clawhub install page-cro
clawhub install product-marketing-context
clawhub install audit

# 其他工具
clawhub install skyvern
clawhub install openfang

---

快速启动检查清单

• Node.js 22+ 已安装
• OpenClaw 已全局安装 (npm install -g openclaw)
• 配置文件已编辑 (openclaw config edit)
• 模型提供商已配置（vLLM/OpenAI 等）
• 所需插件已安装（mcp-adapter 等）
• 所需技能已安装
• 网关已启动 (openclaw gateway start)
• 状态检查通过 (openclaw status)
• 飞书/其他渠道已配置（如需要）

---

提示：修改任何配置后，记得执行 openclaw gateway restart使配置生效。

如需进一步调整格式或补充内容，请告诉我！