OpenClaw 完整配置与使用指南

基于实际配置经验整理，涵盖安装、中转 API、Telegram Bot、命令执行权限等核心配置。

一、安装 OpenClaw

OpenClaw 的安装极为友好，即使是非开发者也能快速上手。

系统要求

硬件：极低，2GB RAM 即可运行
系统：支持 macOS、Windows、Linux
环境：需要 Node.js (pnpm) 或使用 Docker

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

直接通过终端执行以下命令，会自动安装 Node.js（≥22）并完成基本配置。

macOS / Linux：

bash

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

Windows（PowerShell）：

powershell

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

Windows（CMD）：

cmd

curl -fsSL https://openclaw.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

方式二：手动安装

需要先安装 Node.js ≥22。

使用 npm：

bash

npm i -g openclaw

或使用 pnpm：

bash

pnpm add -g openclaw

安装完成后，初始化并安装后台服务（launchd / systemd 用户服务）：

bash

openclaw onboard

方式三：从源码安装（开发模式）

bash

git clone https://github.com/openclaw/openclaw.git
cd openclaw

pnpm install

pnpm ui:build   # 首次运行会自动安装 UI 相关依赖并构建前端界面
pnpm build      # 构建整个项目（包含后端与相关模块）

# 初始化 OpenClaw 并安装为系统后台服务（开机自动运行）
pnpm openclaw onboard --install-daemon

# 开发模式：监听 TypeScript 代码变更并自动重载网关服务
pnpm gateway:watch

配置说明

我们推荐使用一键脚本安装，它会完成环境检测、安装必要的依赖，并启动 onboarding 流程。

macOS / Linux：

bash

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

Windows（PowerShell）：

powershell

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

Windows（CMD）：

cmd

curl -fsSL https://openclaw.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

二、安装后的基础配置

配置文件位置

文件	路径	用途
主配置	`~/.openclaw/openclaw.json`	全局配置（模型、频道、网关等）
API 认证	`~/.openclaw/agents/main/agent/auth-profiles.json`	API Key 存储
执行权限	`~/.openclaw/exec-approvals.json`	命令执行白名单
日志	`~/.openclaw/logs/gateway.log`	运行日志
错误日志	`~/.openclaw/logs/gateway.err.log`	错误日志

Gateway 基本操作

bash

# 启动/安装 Gateway 服务
openclaw gateway install

# 停止 Gateway
openclaw gateway stop

# 强制重装（修改配置后）
openclaw gateway install --force

# 查看状态
openclaw status

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

# 健康检查
openclaw health

三、配置中转 API（国内必做）

问题背景

OpenClaw 默认连接 Anthropic 官方 API（api.anthropic.com），国内无法直接访问。使用中转 API 需要配置自定义 Provider。

配置步骤

编辑 ~/.openclaw/openclaw.json，添加 models 配置块，并修改默认模型：

json

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "你的provider名/模型id"
      },
      "workspace": "~/.openclaw/workspace"
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "你的provider名": {
        "baseUrl": "你的中转API地址",
        "apiKey": "你的API Key",
        "api": "anthropic-messages",
        "models": [
          { "id": "模型id", "name": "显示名称" }
        ]
      }
    }
  }
}

实际示例（ccfly 中转）

json

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "ccfly/claude-sonnet-4-6"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "ccfly": {
        "baseUrl": "https://api.ccfly.codes/api",
        "apiKey": "cc-xxxxxxxxxxxxxxxx",
        "api": "anthropic-messages",
        "models": [
          { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6" },
          { "id": "claude-sonnet-4-5-20250514", "name": "Claude Sonnet 4.5" },
          { "id": "claude-opus-4-20250918", "name": "Claude Opus 4" }
        ]
      }
    }
  }
}

字段说明

字段	说明
`baseUrl`	中转 API 的完整地址
`apiKey`	中转服务提供的 API Key
`api`	兼容模式：Anthropic 用 `anthropic-messages`，OpenAI 用 `openai-completions`
`models`	可用模型列表
`primary`	默认模型，格式 `provider名/模型id`

验证配置

bash

openclaw models status

正确输出应显示你的 provider 名称和 Key 信息。

四、Telegram Bot 配置

第 1 步：创建 Bot

在 Telegram 找到 @BotFather
发送 /newbot，按提示创建
保存返回的 Bot Token

第 2 步：配置 openclaw.json

在 ~/.openclaw/openclaw.json 中添加：

json

{
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "pairing",
      "botToken": "你的Bot Token",
      "groupPolicy": "allowlist",
      "streaming": "off"
    }
  },
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true
      }
    }
  }
}

第 3 步：网络代理配置（国内必做）

Telegram API 在国内被墙，需要通过代理访问。

方案一：ClashX Pro 增强模式（推荐）

无需在 OpenClaw 中配置代理，但需要：

开启增强模式（⌘E）— 接管所有系统流量
全局模式 或规则模式中确保 api.telegram.org 走代理节点

重要：仅开「系统代理」不够！终端和 Node.js 程序不走系统代理，必须开「增强模式」。

方案二：在 OpenClaw 中配置代理

如果你的代理支持 HTTP 代理端口：

json

{
  "channels": {
    "telegram": {
      "proxy": "http://127.0.0.1:7890"
    }
  }
}

注意：OpenClaw 的 Telegram 代理也支持 SOCKS5 格式 socks5://host:port，但实际取决于你的代理软件是否在该端口提供 SOCKS5 服务。

第 4 步：重启 Gateway 并配对

bash

# 重启
openclaw gateway stop && openclaw gateway install --force

# 验证 Telegram 状态
openclaw status
# 应显示：Telegram │ ON │ OK

在 Telegram 上给 Bot 发一条消息，然后：

bash

# 查看配对请求
openclaw pairing list telegram

# 批准配对（CODE 从上面的输出获取）
openclaw pairing approve telegram <CODE>

配对成功后即可在 Telegram 上与 Bot 对话。

五、命令执行权限配置

问题背景

默认情况下，OpenClaw 禁止 Bot 执行系统命令（安全考虑），会报错：

SYSTEM_RUN_DISABLED: security=deny

配置方法

需要修改 两个文件：

1. 修改 `~/.openclaw/openclaw.json`

添加 tools 配置块：

json

{
  "tools": {
    "exec": {
      "host": "gateway",
      "security": "allowlist",
      "ask": "on-miss"
    }
  }
}

字段	可选值	说明
`host`	`sandbox` / `gateway` / `node`	命令执行位置
`security`	`deny` / `allowlist` / `full`	`deny`=全部拒绝，`allowlist`=白名单，`full`=全部允许
`ask`	`off` / `on-miss` / `always`	不在白名单的命令是否询问

2. 修改 `~/.openclaw/exec-approvals.json`

这是关键文件，控制实际的执行权限：

json

{
  "version": 1,
  "defaults": {
    "security": "allowlist",
    "ask": "on-miss"
  },
  "agents": {
    "*": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [
        { "pattern": "/usr/bin/open" },
        { "pattern": "/bin/ls" },
        { "pattern": "/bin/cat" },
        { "pattern": "/bin/mkdir" },
        { "pattern": "/usr/bin/defaults" },
        { "pattern": "/usr/sbin/system_profiler" }
      ]
    }
  }
}

重要：defaults.security 必须设置为 allowlist，否则即使白名单有内容也无效（默认为 deny）。

通过命令行添加白名单

bash

# 添加白名单
openclaw approvals allowlist add "/usr/bin/open"
openclaw approvals allowlist add "/opt/homebrew/bin/code"

# 查看当前白名单
openclaw approvals get

# 删除白名单
openclaw approvals allowlist remove "/bin/cat"

安全等级说明

等级	说明	适用场景
`deny`	拒绝所有命令执行	最安全，不需要执行命令时
`allowlist`	只允许白名单中的命令	推荐，安全与实用的平衡
`full`	允许所有命令	完全信任，风险较高

六、常用命令速查

Gateway 管理

bash

openclaw gateway install          # 安装并启动
openclaw gateway install --force  # 强制重装
openclaw gateway stop             # 停止
openclaw status                   # 查看状态
openclaw health                   # 健康检查
openclaw logs --follow            # 实时日志

模型管理

bash

openclaw models status            # 查看模型状态
openclaw models list              # 列出可用模型
openclaw models set <model>       # 设置默认模型

配置管理

bash

openclaw config get agents        # 查看 agents 配置
openclaw config get tools         # 查看 tools 配置
openclaw config set <key> <value> # 设置配置项
openclaw configure                # 交互式配置向导

Telegram 管理

bash

openclaw pairing list telegram         # 查看配对请求
openclaw pairing approve telegram <CODE>  # 批准配对
openclaw status                        # 查看频道状态

执行权限管理

bash

openclaw approvals get                          # 查看当前权限
openclaw approvals allowlist add "/path/to/bin"  # 添加白名单
openclaw approvals allowlist remove "/path"      # 删除白名单

会话管理

bash

openclaw sessions list            # 列出会话
openclaw doctor                   # 诊断问题
openclaw doctor --fix             # 自动修复

七、常见问题排查

1. Bot 不回复消息

检查日志：

bash

tail -20 ~/.openclaw/logs/gateway.err.log

常见原因：

错误信息	原因	解决方案
`No API key found for provider "anthropic"`	未配置 API Key 或使用了中转但没配置 provider	配置自定义 provider（见第二章）
`Network request failed`	网络不通（Telegram API 被墙）	开启 ClashX Pro 增强模式
`Connection error`	无法连接到 AI API	检查中转地址和 Key 是否正确
`Invalid URL protocol`	代理协议格式错误	使用 `http://` 或正确的 `socks5://` 格式

2. 命令执行被拒绝

错误信息：SYSTEM_RUN_DISABLED: security=deny

解决方案：

检查 exec-approvals.json 中 defaults.security 是否为 allowlist
检查 openclaw.json 中 tools.exec.security 是否为 allowlist
确保要执行的命令在白名单中

3. Gateway 端口冲突

错误信息：Port 18789 is already in use

解决方案：

bash

openclaw gateway stop
# 或
launchctl bootout gui/$UID/ai.openclaw.gateway
# 然后重新启动
openclaw gateway install --force

4. ClashX Pro 代理不生效

关键配置：

必须同时开启「增强模式」和「系统代理」
全局模式下 GLOBAL 必须指向代理节点（不能是 DIRECT）
规则模式下确保 Telegram 域名走代理而非直连

验证代理是否生效：

bash

curl --connect-timeout 10 https://api.telegram.org/botYOUR_TOKEN/getMe

返回 JSON 数据即表示网络通畅。

八、完整配置文件参考

`~/.openclaw/openclaw.json`

json

{
  "auth": {
    "profiles": {
      "anthropic:default": {
        "provider": "anthropic",
        "mode": "api_key"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "ccfly": {
        "baseUrl": "https://api.ccfly.codes/api",
        "apiKey": "你的API Key",
        "api": "anthropic-messages",
        "models": [
          { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6" },
          { "id": "claude-sonnet-4-5-20250514", "name": "Claude Sonnet 4.5" },
          { "id": "claude-opus-4-20250918", "name": "Claude Opus 4" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "ccfly/claude-sonnet-4-6"
      },
      "workspace": "~/.openclaw/workspace"
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true
  },
  "session": {
    "dmScope": "per-channel-peer"
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "pairing",
      "botToken": "你的Bot Token",
      "groupPolicy": "allowlist",
      "streaming": "off"
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback"
  },
  "tools": {
    "exec": {
      "host": "gateway",
      "security": "allowlist",
      "ask": "on-miss"
    }
  },
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true
      }
    }
  }
}

`~/.openclaw/exec-approvals.json`

json

{
  "version": 1,
  "defaults": {
    "security": "allowlist",
    "ask": "on-miss"
  },
  "agents": {
    "*": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [
        { "pattern": "/usr/bin/open" },
        { "pattern": "/bin/ls" },
        { "pattern": "/bin/cat" },
        { "pattern": "/bin/mkdir" },
        { "pattern": "/usr/bin/defaults" },
        { "pattern": "/usr/sbin/system_profiler" }
      ]
    }
  }
}

附录：配置修改流程

每次修改配置文件后，都需要重启 Gateway 使其生效：

bash

openclaw gateway stop
openclaw gateway install --force

然后验证状态：

bash

openclaw status

确认所有 Channel 状态为 OK 即可。

我们可以帮助您吗?

加入交流群

OpenClaw 完整配置与使用指南 ​

一、安装 OpenClaw ​

系统要求 ​

方式一：一键脚本安装（推荐） ​

方式二：手动安装 ​

方式三：从源码安装（开发模式） ​

配置说明 ​

二、安装后的基础配置 ​

配置文件位置 ​

Gateway 基本操作 ​

三、配置中转 API（国内必做） ​

问题背景 ​

配置步骤 ​

实际示例（ccfly 中转） ​

字段说明 ​

验证配置 ​

四、Telegram Bot 配置 ​

第 1 步：创建 Bot ​

第 2 步：配置 openclaw.json ​

第 3 步：网络代理配置（国内必做） ​

方案一：ClashX Pro 增强模式（推荐） ​

方案二：在 OpenClaw 中配置代理 ​

第 4 步：重启 Gateway 并配对 ​

五、命令执行权限配置 ​

问题背景 ​

配置方法 ​

1. 修改 ~/.openclaw/openclaw.json ​

2. 修改 ~/.openclaw/exec-approvals.json ​

通过命令行添加白名单 ​

安全等级说明 ​

六、常用命令速查 ​

Gateway 管理 ​

模型管理 ​

配置管理 ​

Telegram 管理 ​

执行权限管理 ​

会话管理 ​

七、常见问题排查 ​

1. Bot 不回复消息 ​

2. 命令执行被拒绝 ​

3. Gateway 端口冲突 ​

4. ClashX Pro 代理不生效 ​

八、完整配置文件参考 ​

~/.openclaw/openclaw.json ​

~/.openclaw/exec-approvals.json ​

附录：配置修改流程 ​

OpenClaw 完整配置与使用指南

一、安装 OpenClaw

系统要求

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

方式二：手动安装

方式三：从源码安装（开发模式）

配置说明

二、安装后的基础配置

配置文件位置

Gateway 基本操作

三、配置中转 API（国内必做）

问题背景

配置步骤

实际示例（ccfly 中转）

字段说明

验证配置

四、Telegram Bot 配置

第 1 步：创建 Bot

第 2 步：配置 openclaw.json

第 3 步：网络代理配置（国内必做）

方案一：ClashX Pro 增强模式（推荐）

方案二：在 OpenClaw 中配置代理

第 4 步：重启 Gateway 并配对

五、命令执行权限配置

问题背景

配置方法

1. 修改 `~/.openclaw/openclaw.json`

2. 修改 `~/.openclaw/exec-approvals.json`

通过命令行添加白名单

安全等级说明

六、常用命令速查

Gateway 管理

模型管理

配置管理

Telegram 管理

执行权限管理

会话管理

七、常见问题排查

1. Bot 不回复消息

2. 命令执行被拒绝

3. Gateway 端口冲突

4. ClashX Pro 代理不生效

八、完整配置文件参考

`~/.openclaw/openclaw.json`

`~/.openclaw/exec-approvals.json`

附录：配置修改流程