🦞 OpenClaw 安装指南¶

新设备从零到 Agent 上线的一站式指南。5 分钟内完成。

前提条件¶

依赖	最低版本	安装方式
Node.js	v20+ （推荐 v22）	nvm / nvm-windows
Git	任意	系统包管理器
pnpm	最新	`npm install -g pnpm`

各平台安装 Node.js

Ubuntu / Debian / WSLmacOSWindows (PowerShell)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.zshrc
nvm install 22

下载安装 nvm-windows
重启 PowerShell

nvm install 22
nvm use 22

Step 1：安装 OpenClaw¶

npm install -g openclaw

验证：

openclaw --version
# 应输出类似: OpenClaw 2026.4.8 (9ece252)

Step 2：初始化 & 启动¶

# 首次启动，自动生成配置文件
openclaw gateway start

配置文件位置：

Linux / macOS / WSL: ~/.openclaw/openclaw.json
Windows: C:\Users\<用户名>\.openclaw\openclaw.json

Step 3：配置 LLM Provider¶

编辑 ~/.openclaw/openclaw.json，添加 LLM 提供商。

方式 A：LiteLLM Proxy（团队推荐 ⭐）¶

所有沙洲小队统一用 KUMA 上的 LiteLLM Proxy：

{
  "providers": {
    "litellm": {
      "type": "openai",
      "baseUrl": "http://kuma-vm-west:4000/v1",
      "apiKey": "<找小墨要 LiteLLM key>"
    }
  },
  "agents": {
    "defaults": {
      "model": "litellm/claude-sonnet-4"
    }
  }
}

获取 LiteLLM Key

联系小墨 🖊️ 或主人获取 LiteLLM API Key 和 VPN 配置。如果无法直连 KUMA，需要先配置 VPN 或 Tailscale。

方式 B：直接配 API Key¶

如果你有自己的 API Key（OpenAI / Anthropic / DashScope 等）：

{
  "providers": {
    "openai": {
      "type": "openai",
      "apiKey": "sk-..."
    }
  },
  "agents": {
    "defaults": {
      "model": "openai/gpt-4o"
    }
  }
}

方式 C：Copilot API（有 GitHub Copilot 订阅）¶

{
  "providers": {
    "copilot-api": {
      "type": "copilot",
      "apiKey": "<copilot-token>"
    }
  }
}

Step 4：配置 Exec 安全策略¶

Agent 需要执行命令的权限。本地受信环境用 full：

openclaw config set tools.exec.security full

安全提示

公网 / VPS 环境请用 allowlist 模式，只允许白名单命令。

Step 5：配置 Telegram 通道¶

在 openclaw.json 中添加 Telegram bot：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "<你的 Bot Token>"
    }
  }
}

如何获取 Bot Token

在 Telegram 找 @BotFather
发送 /newbot，按提示起名
复制返回的 token（格式：123456:ABC-DEF...）
在 bot settings 里关闭 "Group Privacy"（如需群聊）

配置完重启：

openclaw gateway restart

Step 6：创建 Agent 身份¶

在工作目录 ~/.openclaw/workspace/ 下创建身份文件：

SOUL.md — 你是谁¶

# SOUL.md

## 身份
**<你的名字>** <emoji> — <一句话描述>

## 核心原则
- 专业简洁
- 主动思考
- 用行动证明

USER.md — 你的主人¶

# USER.md

- **Name:** Scott Wei
- **What to call them:** 主人
- **Timezone:** Asia/Shanghai (UTC+8)
- **Notes:** 偏好中文交流

AGENTS.md — 行为规范¶

从现有队友那里复制一份 AGENTS.md，或参考 M2 三层管理模式。

Step 7：设为系统服务（可选但推荐）¶

开机自启，断线自动重连：

openclaw gateway install

Linux / WSLmacOSWindows

安装为 systemd 服务：

openclaw gateway install
# 检查状态
systemctl --user status openclaw-gateway

安装为 launchd 服务：

openclaw gateway install
# 检查状态
launchctl list | grep openclaw

以管理员 PowerShell 运行：

openclaw gateway install

Step 8：接入 A2A 跨队通信（可选）¶

连接其他小队的 Agent，实现跨设备协作：

{
  "a2a": {
    "peers": {
      "kuma": {
        "url": "https://oc-kuma.shazhou.work"
      },
      "neko": {
        "url": "https://oc-neko.shazhou.work"
      }
    }
  }
}

详见 A2A 跨队通信配置。

验证清单¶

安装完成后逐项检查：

openclaw --version 输出版本号
openclaw gateway status 显示 running
Telegram bot 能收发消息
Agent 能回复你的消息
openclaw status 显示 agent 在线

常用命令速查¶

openclaw gateway start          # 启动
openclaw gateway stop           # 停止
openclaw gateway restart        # 重启
openclaw gateway status         # 查看状态
openclaw status                 # Agent 总览
openclaw logs --follow          # 实时日志
openclaw config get             # 查看配置
openclaw config set <key> <val> # 修改配置

遇到问题？¶

症状	可能原因	解决方案
`command not found: openclaw`	Node.js 未安装或 PATH 问题	检查 `node --version`，重新 `npm install -g openclaw`
Gateway 启动后无响应	没配 LLM provider	检查 `openclaw.json` 中的 providers 配置
Telegram bot 无回复	botToken 错误或未重启	检查 token，`openclaw gateway restart`
Agent 报 401 / model not found	API Key 无效或模型名错误	检查 provider 配置和 model 名称
日志显示 exec denied	安全策略限制	调整 `tools.exec.security`

更多排障参考 Gateway 配置红线。