入门指南安装和配置

OpenClaw 安装与配置指南

本指南介绍如何安装 OpenClaw 并配置 OPCX 平台的 API 代理。

关于本文档 本文档重点帮助你在 OpenClaw 中配置 OPCX 的 baseUrl 和 apiKey，以便在国内无障碍访问 Claude。对于 OpenClaw 的其他功能和详细说明，请参考官方文档。

系统要求

项目	最低要求	推荐
Node.js	≥ 22.12.0	最新 LTS
内存	1GB	4GB+
操作系统	macOS 12+ / Ubuntu 20.04+ / Windows 10+	macOS 14+

1. 安装 OpenClaw

安装脚本（推荐）Homebrew (macOS)npm / pnpmUbuntu 服务器Docker

macOS / Linux / WSL2：

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

Windows（PowerShell）：

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

安装脚本会自动检测环境、安装 CLI 并运行引导向导。跳过向导只安装 CLI：

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

brew install openclaw/tap/openclaw
openclaw onboard --install-daemon

# npm
npm install -g openclaw@latest
 
# 或 pnpm
pnpm add -g openclaw@latest
 
openclaw onboard --install-daemon

⚠️

如果 sharp 安装报错（macOS + Homebrew libvips 冲突），使用：

npm install -g openclaw@latest --ignore-scripts
npm rebuild sharp --platform=linux --arch=x64

Ubuntu 服务器需先安装 Node.js，推荐使用 nvm：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
 
# 加载 nvm（免重启 shell）
\. "$HOME/.nvm/nvm.sh"
 
# 安装 Node.js 24
nvm install 24
 
# 验证
node -v
npm -v

然后安装 OpenClaw：

npm install -g openclaw@latest

nvm 安装的 Node.js 路径会写入 systemd 服务文件，升级 Node 版本后需运行 openclaw doctor --repair 更新服务配置。

git clone https://github.com/openclaw/openclaw.git
cd openclaw
 
# 一键启动（交互式）
./docker-setup.sh

或手动 Docker Compose：

cp .env.example .env
# 编辑 .env 填入 API 密钥和 Token
docker compose up -d

2. 运行引导向导

安装后执行引导，完成首次配置：

openclaw onboard --install-daemon

向导会依次引导你：

选择模型提供商（选 Anthropic）
输入 API 密钥
设置 Gateway 网关（端口、认证方式）
配置消息渠道（Telegram / WhatsApp / Discord 等）
安装后台服务（launchd / systemd / Windows 计划任务）

3. 配置 OPCX API 代理

⚠️

重要：使用 OPCX 需要手动配置两个地方：API 密钥和自定义 baseUrl。

配置文件位置

OpenClaw 的配置目录：

macOS / LinuxWindows

~/.openclaw/
├── openclaw.json               # 主配置文件
├── .env                        # 环境变量（API 密钥等敏感信息）
└── agents/main/agent/
    └── auth-profiles.json      # API Key 凭据

C:\Users\<用户名>\.openclaw\
├── openclaw.json               # 主配置文件
└── agents\main\agent\
    └── auth-profiles.json      # API Key 凭据

第一步：写入 API Key

编辑 ~/.openclaw/agents/main/agent/auth-profiles.json（Windows：C:\Users\<用户名>\.openclaw\agents\main\agent\auth-profiles.json）：

{
  "version": 1,
  "profiles": {
    "anthropic:default": {
      "type": "api_key",
      "provider": "anthropic",
      "key": "你的OPCX-API-Key"
    }
  },
  "lastGood": {
    "anthropic": "anthropic:default"
  }
}

也可以通过命令行方式配置：

openclaw onboard --auth-choice apiKey --anthropic-api-key 你的OPCX-API-Key

第二步：配置自定义 baseUrl

编辑 ~/.openclaw/openclaw.json，添加 models 节：

{
  "models": {
    "mode": "merge",
    "providers": {
      "anthropic": {
        "baseUrl": "https://opcx.ai/api",
        "models": []
      }
    }
  }
}

"models": [] 为必填项，留空表示使用 provider 默认模型列表；省略该字段会导致配置校验报错：

Invalid config: models.providers.anthropic.models: expected array, received undefined

OPCX API 节点

根据你的网络情况选择最佳节点：

地址	说明
`https://opcx.ai/api`	默认地址（直连延迟 < 100ms 时最快）
`https://jp.opcx.ai/api`	日本节点（阿里云，回国优化）
`https://hk.opcx.ai/api`	香港节点（阿里云，回国优化）
`https://sz.ai-code.club/api`	深圳节点（国内，由服务器代为出境）

将上述地址填入 openclaw.json 的 models.providers.anthropic.baseUrl。

第三步：重启 Gateway

macOSLinux / UbuntuWindows

launchctl stop ai.openclaw.gateway
launchctl start ai.openclaw.gateway

或：

kill $(lsof -ti :18789) && openclaw gateway

systemctl --user restart openclaw-gateway.service

openclaw gateway stop
openclaw gateway start

4. 完整配置示例

以下是一个使用 OPCX 的完整 openclaw.json 示例：

{
  "meta": {
    "lastTouchedVersion": "2026.2.19"
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-6"
      },
      "workspace": "~/.openclaw/workspace",
      "compaction": {
        "mode": "safeguard"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "anthropic": {
        "baseUrl": "https://opcx.ai/api",
        "models": []
      }
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto"
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "你的gateway-token"
    },
    "port": 18789
  }
}

关键配置说明：

配置项	说明	示例值
`agents.defaults.model.primary`	默认使用的模型，需加 provider 前缀	`anthropic/claude-sonnet-4-6`
`models.providers.anthropic.baseUrl`	OPCX API 地址	`https://opcx.ai/api`
`models.providers.anthropic.models`	模型列表，留空使用默认	`[]`
`gateway.auth.token`	Dashboard 访问令牌	用 `openssl rand -hex 32` 生成
`gateway.port`	Gateway 监听端口	`18789`

5. 启动 Gateway

# 前台启动（适合调试）
openclaw gateway --port 18789 --verbose
 
# 后台服务（推荐）
openclaw onboard --install-daemon

Gateway 启动成功后会显示：

[gateway] listening on ws://127.0.0.1:18789 (PID xxxxx)

服务管理

macOSLinux / UbuntuWindows

# 查看状态
launchctl list | grep openclaw
 
# 停止 / 启动
launchctl stop ai.openclaw.gateway
launchctl start ai.openclaw.gateway

# 查看状态
systemctl --user status openclaw-gateway
 
# 重启
systemctl --user restart openclaw-gateway
 
# 查看日志
journalctl --user -u openclaw-gateway -f

# 以管理员权限安装为计划任务
openclaw gateway install --force
openclaw gateway start
openclaw gateway status
 
# 卸载
openclaw gateway uninstall

6. 访问 Dashboard

# 自动打开（推荐）
openclaw dashboard
 
# 或手动访问
# http://127.0.0.1:18789/#token=你的gateway-token

Dashboard 功能：

功能	说明
Chat	直接与 AI 对话
Agents	管理 Agent 会话和历史
Channels	查看渠道状态
Models	查看可用模型
Settings	配置 Token、主题等

7. 配置消息渠道

创建 Bot

打开 Telegram，找 @BotFather，发送 /newbot，按提示设置名称和用户名，获得 Bot Token（格式：123456789:ABCDEF...）。

配置渠道

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

{
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "open",
      "allowFrom": ["*"],
      "groupPolicy": "allowlist",
      "streamMode": "partial"
    }
  },
  "plugins": {
    "entries": {
      "telegram": { "enabled": true }
    }
  }
}

设置 Bot Token

# ~/.openclaw/.env
TELEGRAM_BOT_TOKEN=123456789:ABCDEF...

Telegram 配对

在 Telegram 给你的 Bot 发消息，Bot 会返回配对码，然后在服务器上批准：

openclaw pairing approve telegram XXXXXXXX

Discord / Slack / WhatsApp

WhatsApp 需要扫码登录：

openclaw channels login --channel whatsapp

Discord 和 Slack 在 .env 中配置 Bot Token，详见官方文档。

8. Ubuntu 服务器完整流程

在远程 Ubuntu 服务器上部署 OpenClaw 的完整步骤：

安装 Node.js（通过 nvm）

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
\. "$HOME/.nvm/nvm.sh"
nvm install 24

安装 OpenClaw

npm install -g openclaw@latest

配置 OPCX API Key

编辑 ~/.openclaw/agents/main/agent/auth-profiles.json：

{
  "version": 1,
  "profiles": {
    "anthropic:default": {
      "type": "api_key",
      "provider": "anthropic",
      "key": "cr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  },
  "lastGood": {
    "anthropic": "anthropic:default"
  }
}

配置��定义 baseUrl

编辑 ~/.openclaw/openclaw.json：

{
  "models": {
    "mode": "merge",
    "providers": {
      "anthropic": {
        "baseUrl": "https://opcx.ai/api",
        "models": []
      }
    }
  }
}

运行引导向导

openclaw onboard --install-daemon

向导中选择 Anthropic 模型，并配置 Telegram Bot Token。

配对 Telegram

openclaw pairing approve telegram XXXXXXXX

9. 常见问题

API Key 报错：`No API key found for provider "anthropic"`

检查步骤：

确认文件存在：~/.openclaw/agents/main/agent/auth-profiles.json
确认格式正确（参考第 3 节）
重启 Gateway

配置文件校验失败

Invalid config: models.providers.anthropic.models: expected array, received undefined

解决：在 openclaw.json 的 models.providers.anthropic 下添加 "models": []。

Gateway 端口被占用

Port 18789 is already in use. pid xxxxx

解决（Linux/macOS）：

kill $(lsof -ti :18789)

解决（Windows）：

Stop-Process -Id <pid> -Force

TUI 报 `pairing required` 或 `device token mismatch`

# 清除旧的设备配对文件
rm -f ~/.openclaw/devices/paired.json \
      ~/.openclaw/identity/device-auth.json \
      ~/.openclaw/identity/device.json
 
# 重启 Gateway
systemctl --user restart openclaw-gateway.service
 
# 验证状态
sleep 5 && openclaw gateway status

Dashboard 显示 “unauthorized”

用带 Token 的 URL 访问：

http://localhost:18789/#token=你的gateway-token

或查看当前 Token：

openclaw config get gateway.auth.token

验证代理可达性

curl -X POST "https://opcx.ai/api/v1/messages" \
  -H "x-api-key: 你的API-Key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":64,"messages":[{"role":"user","content":"hi"}]}'

更新 OpenClaw

# 稳定版（推荐）
openclaw update --channel stable
 
# 或直接 npm 更新
npm update -g openclaw

常用命令速查

openclaw --version              # 查看版本
openclaw doctor                 # 诊断配置问题
openclaw doctor --repair        # 自动修复配置
openclaw gateway --verbose      # 启动 Gateway（详细日志）
openclaw dashboard              # 打开 Dashboard
openclaw status                 # 查看运行状态
openclaw onboard                # 重新运行引导向导
openclaw tui                    # 打开终端交互界面
openclaw logs --follow          # 实时查看日志
openclaw update --channel stable # 更新到稳定版

与 Claude Code 的区别

对比项	Claude Code	OpenClaw
用途	命令行编程助手	自托管多渠道 AI 网关
配置工具	CC Switch / 环境变量	手动编辑 JSON
配置文件	`~/.claude/settings.json`	`~/.openclaw/openclaw.json`
API Key 存储	环境变量	`auth-profiles.json`
界面	命令行	Web Dashboard
消息平台	终端	Telegram、WhatsApp 等 20+

参考资料

官方文档：https://docs.openclaw.ai/
GitHub 仓库：https://github.com/openclaw/openclaw
获取 OPCX API Key
OPCX 节点配置说明

注意：相比 Claude Code，OpenClaw 的额度消耗可能更多，因为它需要处理更多渠道和上下文请求。

OpenClaw 介绍

OpenClaw 安装与配置指南 ​

系统要求 ​

1. 安装 OpenClaw ​

2. 运行引导向导 ​

3. 配置 OPCX API 代理 ​

配置文件位置 ​

第一步：写入 API Key ​

第二步：配置自定义 baseUrl ​

OPCX API 节点 ​

第三步：重启 Gateway ​

4. 完整配置示例 ​

5. 启动 Gateway ​

服务管理 ​

6. 访问 Dashboard ​

7. 配置消息渠道 ​

Telegram ​

创建 Bot ​

配置渠道 ​

设置 Bot Token ​

Telegram 配对 ​

Discord / Slack / WhatsApp ​

8. Ubuntu 服务器完整流程 ​

安装 Node.js（通过 nvm） ​

安装 OpenClaw ​

配置 OPCX API Key ​

配置���定义 baseUrl ​

运行引导向导 ​

配对 Telegram ​

9. 常见问题 ​

API Key 报错：No API key found for provider "anthropic" ​

配置文件校验失败 ​

Gateway 端口被占用 ​

TUI 报 pairing required 或 device token mismatch ​

Dashboard 显示 “unauthorized” ​

验证代理可达性 ​

更新 OpenClaw ​

常用命令速查 ​

与 Claude Code 的区别 ​

参考资料 ​