Openclaw Ops

OpenClaw 操作指南

概述

OpenClaw（原 Clawdbot/Moltbot）是开源多通道 AI 智能体框架，支持 WhatsApp、Telegram、Discord、Slack、飞书等平台接入，兼容 Claude、GPT、DeepSeek、Ollama、通义千问等模型。

• 官方仓库: https://github.com/openclaw/openclaw
• 官方文档: https://docs.openclaw.ai
• 技能市场: https://clawhub.ai

环境要求

• Node.js >= 22（推荐 pnpm）
• 系统: macOS / Windows / Linux
• 硬件: 最低 2GB RAM
• 可选: Docker（沙箱功能需要）

安装方式

方式一: 一键脚本（推荐）

# macOS/Linux
curl -fsSL https://openclaw.ai/install.sh | bash

# Windows PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iex

方式二: npm/pnpm

npm i -g openclaw
# 或
pnpm add -g openclaw

openclaw onboard --install-daemon  # 初始化 + 开机自启

方式三: 源码（开发模式）

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm ui:build && pnpm build
pnpm openclaw onboard --install-daemon

初始化配置

运行 openclaw onboard 进入交互式向导：

1. 选择 AI 模型供应商，输入 API Key
2. 配置 Gateway 端口（默认 18789）
3. 可选安装预设技能
4. 完成后访问 http://127.0.0.1:18789/chat

配置文件位置：~/.openclaw/openclaw.json

最小配置示例：

{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}

核心 CLI 命令速查

基础操作

网关 Gateway

模型管理

通道管理

支持平台: whatsapp, telegram, discord, slack, googlechat, signal, imessage, msteams, mattermost, feishu

Agent 操作

诊断排错

openclaw doctor          # 全面健康检查
openclaw doctor --fix    # 自动修复
openclaw status --deep   # 深度状态检测
openclaw logs            # 查看运行日志

标准排查流程: doctor -> logs -> status --deep -> doctor --fix -> restart

技能管理

插件管理

聊天斜杠命令

在对话窗口中使用 / 命令：

关键文件路径

Windows 中 ~ 等于 %USERPROFILE%

常见问题与故障排查

问题一：大模型 API 返回空内容（No reply from agent）

症状: Agent 会话记录中 "content":[],"usage":{"input":0,"output":0}，大模型无回复。

根因: 使用 OpenAI 兼容模式（openai-completions）时，OpenClaw 配置系统会自动在 baseUrl 后追加 /chat/completions，而 OpenAI Node SDK 在发送请求时也会追加 /chat/completions，导致最终请求 URL 出现路径重复：

配置的 baseUrl:  https://api.example.com/v2/chat/completions
实际请求 URL:    https://api.example.com/v2/chat/completions/chat/completions  ← 重复

解决方案:

1. 在 ~/.openclaw/openclaw.json 中，baseUrl 只填到 API 根路径（不含 /chat/completions）：

   {
     "modelProviders": [{
       "baseUrl": "https://api.example.com/v2",
       "apiType": "openai-completions"
     }]
   }
   

2. 同步检查 ~/.openclaw/agents/main/agent/models.json，确保其中的 baseUrl 也不含重复路径。
3. 修改后执行 openclaw restart 重启服务。

问题二：Discord Bot 收到消息但不回复（fetch failed）

症状: Gateway 日志显示 Discord WebSocket 连接正常、消息已接收、Agent 生成了回复，但发送回复时报错：

final reply failed: TypeError: fetch failed
discord typing failed target=...
failed to fetch bot identity: TypeError: fetch failed

根因: 在中国大陆等需要代理才能访问 Discord API 的网络环境中，OpenClaw 的 Discord 通道配置了 proxy 字段，OpenClaw 也正确为自己的 REST 请求创建了 ProxyAgent。但底层依赖库 @buape/carbon 的 RequestClient 类直接使用 globalThis.fetch，完全绕过了代理配置。WebSocket 连接不受影响（OpenClaw 单独为其配置了 HttpsProxyAgent），但所有 REST API 调用（发消息、设置打字状态、获取 Bot 身份等）都失败。

解决方案（Preload 模块 — 不修改源码，版本更新安全）:

1. 创建代理预加载模块 ~/.openclaw/discord-proxy-preload.mjs：

/**
 * Discord Proxy Preload Module
 * 通过 NODE_OPTIONS="--import <path>" 预加载
 * 在 OpenClaw 启动前将 globalThis.fetch 替换为代理感知版本
 * 仅对 Discord 域名走代理，其他请求（如国内大模型 API）不受影响
 */
import { createRequire } from 'node:module';

// 使用 OpenClaw 自带的 undici 依赖（无需额外安装）
const require = createRequire('<openclaw安装路径>/package.json');
const { ProxyAgent, fetch: undiciFetch } = require('undici');

const PROXY_URL = 'http://127.0.0.1:7890';  // 改为你的代理地址
const PROXY_DOMAINS = [
  'discord.com', 'discordapp.com',
  'discord.gg', 'cdn.discordapp.com'
];
const proxyAgent = new ProxyAgent(PROXY_URL);
const originalFetch = globalThis.fetch;

function shouldProxy(urlStr) {
  try {
    const url = typeof urlStr === 'string' ? new URL(urlStr)
      : urlStr instanceof URL ? urlStr
      : urlStr?.url ? new URL(urlStr.url) : null;
    if (!url) return false;
    return PROXY_DOMAINS.some(d =>
      url.hostname === d || url.hostname.endsWith('.' + d)
    );
  } catch { return false; }
}

globalThis.fetch = function patchedFetch(input, init) {
  if (shouldProxy(input)) {
    return undiciFetch(input, { ...init, dispatcher: proxyAgent });
  }
  return originalFetch.call(globalThis, input, init);
};

console.log('[discord-proxy-preload] globalThis.fetch patched for Discord domains via', PROXY_URL);

2. 创建启动脚本 ~/.openclaw/start-gateway.bat（Windows）：

@echo off
set HTTP_PROXY=http://127.0.0.1:7890
set HTTPS_PROXY=http://127.0.0.1:7890
set NO_PROXY=你的大模型API域名,localhost,127.0.0.1
set NODE_OPTIONS=--import file:///C:/Users/<用户名>/.openclaw/discord-proxy-preload.mjs
openclaw gateway --port 18789 --verbose %*

3. 以后通过 start-gateway.bat 启动 Gateway 即可，无需手动设置环境变量。

验证成功标志:

• 启动日志出现 [discord-proxy-preload] globalThis.fetch patched for Discord domains via ...
• 不再出现 fetch failed 错误
• Discord Bot 正常回复消息

为什么不直接修改源码: 修改 @buape/carbon 或 OpenClaw 的 bundle 文件虽然也能解决，但每次 openclaw update 后修改会被覆盖。Preload 模块方案利用标准 Node.js 机制，完全独立于 OpenClaw 源码，版本更新不受影响。

问题三：代理环境下大模型 API 被代理拦截

症状: 配置了 HTTP_PROXY 后，国内大模型 API（如讯飞星火、通义千问）请求也走了代理，导致延迟高或连接失败。

解决方案: 在启动脚本中设置 NO_PROXY 排除国内 API 域名：

set NO_PROXY=maas-api.cn-huabei-1.xf-yun.com,.xf-yun.com,.aliyuncs.com,localhost,127.0.0.1

上述 Preload 模块方案天然解决此问题：只有 Discord 域名走代理，其他所有请求使用原始 fetch。

更多参考

• 完整命令参考: reference.md
• 实战使用示例: examples.md