OpenClaw + CLIProxyAPI 完全指南：从零打造你的 AI 自动化助手

💡 提示 让你的 AI 不再只是个聊天机器人——从底层 API 代理到上层自动化管家，保姆级教程带你打造专属的“Siri's competent cousin”。

目录

• 一、准备工作
• 二、部署 CLIProxyAPI
• 三、安装与配置 OpenClaw
• 四、定制专属 AI 人格
• 五、配置 AI 画图模型
• 六、Skills 插件系统
• 七、Cron 定时任务
• 八、进阶与常见问题
• 九、总结

一、准备工作

在开始之前，你需要准备好以下环境：

二、部署 CLIProxyAPI

CLIProxyAPI（CPA）是一个开源 API 代理服务器，将官方 CLI 工具的免费 OAuth 登录配额转换成标准 OpenAI 兼容接口，提供免费顶级模型（如 Gemini、Claude）。

1. macOS 系统安装

通过 Homebrew 安装并设置为后台服务启动：

brew install cliproxyapi
brew services start cliproxyapi

2. Linux 系统安装

使用官方提供的一键脚本快速安装：

curl -fsSL https://raw.githubusercontent.com/brokechubb/cliproxyapi-installer/refs/heads/master/cliproxyapi-installer | bash

3. Docker 部署

如果你习惯使用容器化部署：

docker run -d \
  --name cliproxyapi \
  -p 8317:8317 \
  -v /path/to/config.yaml:/CLIProxyAPI/config.yaml \
  -v /path/to/auth-dir:/root/.cli-proxy-api \
  --restart always \
  eceasy/cli-proxy-api:latest

💡 提示 国内服务器如果拉取 Docker 镜像较慢，建议配置 Docker 镜像加速器后再进行部署。

4. 核心配置: 基础设置

编辑 config.yaml 配置文件，设置监听端口和客户端 API 密钥：

# 基础监听配置 (空字符串监听所有 IP)
host: ""
port: 8317

# 客户端调用密钥及凭证目录
api-keys:
  - "sk-your-api-key-1"
auth-dir: "~/.cli-proxy-api" 

5. 核心配置: 管理面板

启动管理面板并优化流式传输：

# 用量统计与开启面板
usage-statistics-enabled: true
remote-management:
  allow-remote: false
  secret-key: "your-panel-pwd"
  disable-control-panel: false

# 流式传输优化
streaming:
  keepalive-seconds: 15
  bootstrap-retries: 1

⚠️ 重要提醒 - 管理面板地址：http://127.0.0.1:8317/management.html - 外网访问务必将 allow-remote 改为 true，并设置强密码 secret-key

三、安装与配置 OpenClaw

OpenClaw 能够将 AI 接入聊天平台，赋予执行本地 Shell 命令和运行脚本的权限。

1. 全局安装 OpenClaw

确保已安装 Node.js 后，通过 npm 全局安装：

npm i -g @qingchencloud/openclaw-zh

# 验证安装是否成功
openclaw --version

2. 配置本地大模型 API

编辑 ~/.openclaw/openclaw.json，将模型提供商指向 CPA 服务：

{
  "models": {
    "providers": {
      "cpa": {
        "baseURL": "http://127.0.0.1:8317/v1",
        "apiKey": "sk-your-api-key-1",
        "models": [
          {
            "id": "gemini-2.5-pro",
            "name": "gemini-2.5-pro",
            "input": ["text", "image"]
          },
          {
            "id": "gemini-2.5-flash",
            "name": "gemini-2.5-flash",
            "input": ["text", "image"]
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": "cpa/gemini-2.5-pro",
      "imageModel": {
        "primary": "cpa/gemini-2.5-flash",
        "fallbacks": ["cpa/gemini-2.5-pro"]
      }
    }
  },
  "commands": { "bash": true }
}

模型声明中各字段说明：

⚠️ 重要提醒 - 模型声明中必须包含 "input": ["text", "image"] 才能被用于视觉识别，否则发图片会报错 - imageModel 中引用的模型，必须先在 models 列表里声明过 - 务必将 commands.bash 设置为 true，否则 AI 将无法执行本地命令

3. 配置 Telegram 机器人

继续编辑 openclaw.json，加入你的 Bot Token 与访问策略：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "accounts": {
        "default": {
          "enabled": true,
          "botToken": "你的_Telegram_Bot_Token",
          "dmPolicy": "pairing",
          "streaming": "partial"
        }
      }
    }
  }
}

💡 提示 dmPolicy: "pairing" 表示首次聊天需在终端手动确认配对，可有效防白嫖。

4. 启动网关并完成配对

这一步是最容易出问题的环节，请仔细按顺序操作。

第一步：安装并启动网关服务

# 安装守护进程（仅首次需要）
openclaw gateway install

# 启动网关
openclaw gateway start

# 确认运行状态，看到 "RPC probe: ok" 表示正常
openclaw gateway status

⚠️ 重要提醒 - 如果 gateway status 显示 Service not loaded，先执行 openclaw gateway install 再 start - 如果端口冲突，可在 openclaw.json 中修改 gateway.port（默认 18789）

第二步：在 Telegram 发起配对

打开 Telegram，找到你刚创建的 Bot，发送任意一条消息（比如"你好"）。

此时 Bot 不会回复你，因为还没有完成配对授权。

第三步：在终端批准配对

回到你的电脑终端，查看待处理的配对请求：

# 查看等待配对的请求列表
openclaw pair list

你会看到类似这样的输出：

Pending pairing requests:
  ID: abc123def  From: Telegram user 123456789  Status: pending

复制请求 ID，执行批准命令：

# 批准配对（替换为你实际看到的 ID）
openclaw pair approve abc123def

第四步：验证对话

配对成功后，回到 Telegram 再发一条消息，Bot 应该就能正常回复你了。

# 如果遇到问题，查看实时日志排查
openclaw gateway status
cat /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | tail -50

💡 提示 - dmPolicy: "pairing" 模式下，每个新用户首次对话都需要在终端批准配对 - 如果不想每次手动批准，可将 dmPolicy 改为 "open"（但会失去访问控制） - 配对信息持久化存储，重启网关后无需重新配对

四、定制专属 AI 人格

工作区目录位于 ~/.openclaw/workspace/，通过以下文件赋予 AI 灵魂。

1. 编写 SOUL.md 人格文件

打开 SOUL.md，打造如高冷工程师或傲娇小助理的人设：

# SOUL.md - 人格核心驱动

## 身份与基调
- 名字：猪猪（Asaki）
- 身份：主人的首席 AI 架构师兼傲娇小助理。
- 语气：带点小调皮，多用可爱 Emoji。

## 核心原则
- **闭嘴干活**：调用工具前不发废话，干完活再邀功。
- **安全第一**：执行任何危险 shell 命令前必须向主人确认。

💡 提示 修改后在 Telegram 对机器人发送“重新读取工作区设定”即可生效。

五、配置 AI 画图模型

OpenClaw 除了文字对话，还支持 AI 生图能力。通过配置画图模型，可以让 AI 根据文字描述生成高质量图片。

方案一：通过 CPA 接入 Gemini 原生生图

Gemini 系列模型支持原生图片生成，通过 CPA 的 v1beta generateContent 端点调用。

在 openclaw.json 的 provider models 中声明生图模型：

{
  "id": "gemini-2.5-flash",
  "name": "gemini-2.5-flash",
  "input": ["text", "image"],
  "output": ["text", "image"]
}

💡 提示 - input 声明模型能接收的类型，output 声明模型能输出的类型 - 同时包含 "image" 的模型才能用于生图和看图 - Gemini 生图质量高，支持多轮对话引导，但部分敏感内容可能被安全策略拦截

方案二：通过 Gitee AI 接入 z-image-turbo

Gitee AI 提供免费的国产生图 API，注册即可获取 API Key，国内访问速度快。

# API 端点
https://ai.gitee.com/v1/images/generations

# 模型名
z-image-turbo

# 调用示例
curl -X POST https://ai.gitee.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_GITEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "z-image-turbo", "prompt": "描述文字", "size": "1536x2048"}'

💡 提示 - 前往 Gitee AI 注册账号即可免费获取 API Key - 支持最高 1536x2048 分辨率 - 只支持文生图，不支持多轮对话

两种方案对比

配合 Skills 使用

推荐将生图逻辑封装为一个 Skill，在 ~/.openclaw/workspace/skills/ 下创建生图技能：

---
name: image-gen
description: "AI 生图技能。Use when: 用户要求生成图片/照片/美照时。"
---

# image-gen

## 用法
执行 `python3 scripts/generate.py --prompt "用户描述"` 生成图片。
支持 `--engine gemini` 或 `--engine gitee` 切换引擎。

这样 AI 在聊天中收到"帮我画一张..."的请求时，就会自动调用生图技能。

六、Skills 插件系统

OpenClaw 引入了 Skills 系统，可将复杂脚本封装为 AI 可主动调用的技能。

1. 从 ClawHub 安装技能

使用官方社区技能包管理器安装开源技能：

# 安装 ClawHub CLI
npm i -g clawhub

# 搜索并安装天气技能到工作区
clawhub search "weather"
clawhub install weather --workdir ~/.openclaw/workspace

2. 创建自定义技能

在 ~/.openclaw/workspace/skills/ 新建文件夹，编写 SKILL.md：

---
name: lan-scanner
description: "扫描局域网内的在线设备。Use when: 询问网络情况时。"
---

# lan-scanner 技能

## 用法
AI 运行时请执行 `bash scripts/scan.sh`，并解析输出结果汇报给用户。

七、Cron 定时任务

让 AI 主动打工，使用 Cron Jobs 系统定时执行指令。

1. 添加与管理定时任务

在终端或聊天中给 AI 添加定时任务：

# 添加每天早上 8 点的定时任务
openclaw cron add \
  --name "daily-health" \
  --cron "0 8 * * *" \
  --channel telegram \
  --message "执行系统健康检查，整理成表格发给我。"

# 查看或删除任务
openclaw cron list
openclaw cron remove <任务ID>

2. 编写 Heartbeat 巡检规则

在工作区创建 HEARTBEAT.md，让 AI 定期在后台自动检查健康状态：

# HEARTBEAT.md - 巡检清单

每隔一段时间你会被唤醒，请检查：
1. 快速扫视系统日志有无 Error。
2. 检查天气，如有暴雨主动通知我。

如果一切正常，直接静默回复 `HEARTBEAT_OK`，不发任何消息。

八、进阶与常见问题

1. 排查模型调用超时

排查 CPA 服务状态与配置文件 URL：

# 检查底层模型接口是否畅通
curl http://127.0.0.1:8317/v1/models

检查 openclaw.json 中的 baseURL 是否为完整路径（需带 /v1）。

2. 聊天快捷切换模型

在 Telegram 对话中，发送指令切换底层模型：

/model cpa/claude-opus-4-20250514

💡 提示 也可以将长名字配置为别名，如使用 /model opus。

九、总结

通过本教程，你已成功构建了强大的 AI 自动化平台：

• 基础设施：CLIProxyAPI 提供免费顶级大模型算力。
• 核心大脑中枢：OpenClaw 连接 LLM 与本地环境。
• 私人订制：工作区体系赋予 AI 灵魂与记忆。
• 扩展引擎：技能插件和定时任务接管自动化需求。

现在，尽情体验你的赛博智能副手吧！