OpenClaw 是一个强大的 AI 助手平台，支持多代理架构、浏览器自动化、定时任务、跨平台消息推送等丰富功能。本文将基于官方文档，详细介绍 OpenClaw 的完整安装流程、配置方法以及日常使用中的各类命令。

系统要求

在安装 OpenClaw 之前，请确保你的系统满足以下要求：

• Node.js: 22 或更高版本（安装脚本会自动安装）
• 操作系统: macOS、Linux 或 Windows
• 包管理器: npm（必需）或 pnpm（源码安装时需要）

安装方法

方法一：安装脚本（推荐）

安装脚本是最简单的方式，它会自动处理 Node 检测、安装和初始化向导。

macOS / Linux / WSL2

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

Windows (PowerShell)

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

跳过初始化向导，仅安装二进制文件：

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

# Windows PowerShell
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

方法二：npm / pnpm 安装

如果你已经安装了 Node 22+，可以手动管理安装：

使用 npm

npm install -g openclaw@latest
openclaw onboard --install-daemon

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

使用 pnpm

pnpm add -g openclaw@latest
pnpm approve-builds -g        # 批准构建脚本
openclaw onboard --install-daemon

方法三：从源码安装

适合贡献者或想要本地运行的用户。

# 1. 克隆仓库并构建
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build

# 2. 链接 CLI 到全局
pnpm link --global

# 3. 运行初始化向导
openclaw onboard --install-daemon

方法四：Docker / Podman

适合容器化或 headless 部署：

# Docker
docker run -it --rm openclaw/openclaw:latest

# Podman（rootless）
# 先运行 setup-podman.sh，然后使用启动脚本

其他安装方式：

• Nix: 声明式安装
• Ansible: 自动化集群部署
• Bun: 仅 CLI 使用

安装后验证

安装完成后，运行以下命令验证一切正常：

# 检查配置问题
openclaw doctor

# 查看网关状态
openclaw status

# 打开浏览器控制面板
openclaw dashboard

初始化配置

运行初始化向导

openclaw onboard

向导会引导你完成：

1. 工作区设置
2. 模型提供商配置（API Key）
3. 消息通道配置（WhatsApp、Telegram、Discord 等）
4. 技能安装
5. 网关服务安装

常用配置选项

非交互式配置

# 快速模式
openclaw onboard --non-interactive --mode local

# 指定模型提供商
openclaw onboard --auth-choice openai-api-key --openai-api-key $OPENAI_API_KEY

# 远程网关模式
openclaw onboard --mode remote --remote-url https://gateway.example.com --remote-token $TOKEN

配置模型

# 查看模型状态
openclaw models status

# 设置主模型
openclaw models set moonshot/kimi-k2.5

# 设置图像模型
openclaw models set-image openai/gpt-4o

# 添加模型别名
openclaw models aliases add kimi moonshot/kimi-k2.5

# 配置模型认证
openclaw models auth add
openclaw models auth setup-token --provider anthropic

核心命令详解

基础命令

配置管理

# 交互式配置向导
openclaw configure

# 获取配置值
openclaw config get agents.defaults.model.primary

# 设置配置值
openclaw config set agents.defaults.model.primary moonshot/kimi-k2.5

# 验证配置
openclaw config validate

# 查看配置文件路径
openclaw config file

网关管理

# 查看网关状态
openclaw gateway status

# 安装网关服务
openclaw gateway install --port 18789

# 启动/停止/重启网关
openclaw gateway start
openclaw gateway stop
openclaw gateway restart

# 查看日志
openclaw logs --follow
openclaw logs --limit 200

会话管理

# 列出所有会话
openclaw sessions list

# 查看会话历史
openclaw sessions history agent:main:main

# 向会话发送消息
openclaw sessions send agent:main:main "你好"

技能管理

# 列出已安装技能
openclaw skills list

# 查看技能详情
openclaw skills info agent-browser

# 检查技能就绪状态
openclaw skills check

# 从 ClawdHub 搜索技能
npx clawhub search browser

# 安装技能
npx clawhub install agent-browser

消息通道管理

# 列出配置的通道
openclaw channels list

# 检查通道状态
openclaw channels status --probe

# 查看通道日志
openclaw channels logs --lines 100

# 添加 Telegram 机器人
openclaw channels add --channel telegram --account alerts --name "Alerts Bot" --token $TELEGRAM_BOT_TOKEN

# 添加 Discord 机器人
openclaw channels add --channel discord --account work --name "Work Bot" --token $DISCORD_BOT_TOKEN

# 移除通道
openclaw channels remove --channel discord --account work --delete

代理管理

# 列出代理
openclaw agents list

# 添加新代理
openclaw agents add my-agent --workspace /path/to/workspace

# 绑定通道到代理
openclaw agents bind --agent my-agent --bind telegram:alerts

# 解绑通道
openclaw agents unbind --agent my-agent --bind telegram:alerts

# 删除代理
openclaw agents delete my-agent

浏览器自动化

# 启动浏览器
openclaw browser start

# 打开网页
openclaw browser open https://example.com

# 获取页面快照
openclaw browser snapshot --interactive

# 点击元素
openclaw browser click @e1

# 输入文本
openclaw browser type @e2 "搜索内容" --submit

# 截图
openclaw browser screenshot --full-page

# 停止浏览器
openclaw browser stop

定时任务 (Cron)

# 查看定时任务
openclaw cron list

# 添加定时任务（每 30 分钟）
openclaw cron add --name "heartbeat" --every 30m --system-event "检查邮件"

# 添加定时任务（特定时间）
openclaw cron add --name "reminder" --at "2026-03-10T09:00:00Z" --message "开会提醒"

# 添加 Cron 表达式任务
openclaw cron add --name "daily" --cron "0 9 * * *" --system-event "每日简报"

# 启用/禁用任务
openclaw cron enable <id>
openclaw cron disable <id>

# 删除任务
openclaw cron rm <id>

# 立即运行任务
openclaw cron run <id>

节点管理（移动设备）

# 列出已配对节点
openclaw nodes list

# 查看节点详情
openclaw nodes describe --node <id>

# 批准配对请求
openclaw nodes approve <requestId>

# 拍照（iOS/Android）
openclaw nodes camera snap --node <id> --facing back

# 录屏（iOS/Android）
openclaw nodes screen record --node <id> --duration 30s

# 获取位置
openclaw nodes location get --node <id>

# 发送通知（macOS）
openclaw nodes notify --node <id> --title "提醒" --body "内容"

# 在节点上运行命令
openclaw nodes run --node <id> ls -la

内存搜索

# 查看内存索引状态
openclaw memory status

# 重新索引内存
openclaw memory index

# 搜索记忆
openclaw memory search "OpenClaw 安装"

工作区文件结构

OpenClaw 在工作区使用以下文件组织配置和记忆：

~/.openclaw/
├── workspace/                    # 主工作区
│   ├── AGENTS.md                # 多代理工作流配置
│   ├── SOUL.md                  # AI 行为准则和个性
│   ├── TOOLS.md                 # 工具能力和使用模式
│   ├── MEMORY.md                # 长期记忆（仅主会话）
│   ├── TOOLS.md                 # 工具配置
│   ├── BOOTSTRAP.md             # 首次运行引导（可删除）
│   ├── HEARTBEAT.md             # 定时任务检查清单
│   ├── IDENTITY.md              # AI 身份信息
│   ├── USER.md                  # 用户信息
│   ├── .learnings/              # 学习记录
│   │   ├── LEARNINGS.md
│   │   ├── ERRORS.md
│   │   └── FEATURE_REQUESTS.md
│   └── memory/                  # 每日记忆文件
│       └── YYYY-MM-DD.md
├── config.json                  # 主配置文件
├── agents/                      # 代理配置
└── skills/                      # 已安装技能

推荐技能清单

故障排除

openclaw 命令未找到

诊断：

node -v
npm -v
npm prefix -g
echo "$PATH"

修复（macOS/Linux）：

将以下行添加到 ~/.zshrc 或 ~/.bashrc：

export PATH="$(npm prefix -g)/bin:$PATH"

Windows： 将 npm prefix -g 的输出添加到系统 PATH 环境变量。

模型认证失败

# 检查认证状态
openclaw models status --probe

# 重新添加认证
openclaw models auth add

网关无法启动

# 检查端口占用
openclaw gateway status --deep

# 强制重启
openclaw gateway restart --force

# 查看详细日志
openclaw logs --follow

进阶使用技巧

1. 多代理架构

创建隔离的代理用于不同任务：

# 创建工作代理
openclaw agents add work-agent --workspace ~/work-agent
openclaw agents bind --agent work-agent --bind slack:work

# 创建个人代理
openclaw agents add personal-agent --workspace ~/personal-agent
openclaw agents bind --agent personal-agent --bind telegram:personal

2. 环境变量配置

自定义运行时路径：

export OPENCLAW_HOME="$HOME/.openclaw-custom"      # 主目录
export OPENCLAW_STATE_DIR="/var/openclaw"          # 可变状态
export OPENCLAW_CONFIG_PATH="/etc/openclaw.json"   # 配置文件

3. 开发模式

# 使用隔离的开发环境
openclaw --dev dashboard

# 使用自定义配置文件
openclaw --profile work dashboard

4. ACP 桥接（IDE 集成）

# 启动 ACP 桥接，连接 IDE 到网关
openclaw acp

更新与卸载

更新 OpenClaw

# 通过 npm
npm update -g openclaw

# 或通过安装脚本重新安装
curl -fsSL https://openclaw.ai/install.sh | bash

重置配置

# 重置配置（保留 CLI）
openclaw reset --scope config

# 完全重置（包括凭证和会话）
openclaw reset --scope full --yes

完全卸载

# 卸载服务和数据（保留 CLI）
openclaw uninstall --all --yes

# 然后手动删除全局安装
npm uninstall -g openclaw

总结

OpenClaw 是一个功能丰富的 AI 助手平台，主要特点包括：

• 多种安装方式：安装脚本、npm、源码、Docker
• 多代理支持：隔离的工作区和路由
• 丰富的技能生态：浏览器自动化、搜索、语音等
• 跨平台消息：WhatsApp、Telegram、Discord、Slack 等
• 移动设备集成：iOS/Android 节点配对
• 定时任务：Cron 表达式支持
• 浏览器自动化：完整的网页操作能力

快速开始命令：

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

# 初始化
openclaw onboard --install-daemon

# 验证
openclaw doctor
openclaw status

# 打开控制面板
openclaw dashboard

参考链接：

• OpenClaw 官方文档
• ClawdHub 技能市场
• GitHub 仓库
• Discord 社区

本文基于 OpenClaw 官方文档编写，最后更新于 2026-03-06

server.properties

服务器滞后指标

TPS

TPS：TickPerSecond。它也是服务器所有者可以直接控制唯一项目，下述指南专门用于提高 TPS。 服务器以 20 TPS 的速率处理所有任务。诸如怪物移动、作物生长和玩家与块的交互等任务需要由服务器Ticks才能正常运行。TPS 低于 20 意味着服务器运行滞后，必须跳过任务才能按时执行重要任务。

20.0 = 无卡顿

19.95 - 19.99 = 几乎无卡顿

18.5 - 19.94 = 一般。可能有一些卡顿，但对游戏无明显影响。

16.0 - 18.4 = 差。

优化推荐

simulation-distance：模拟距离是服务器将在玩家周围互动的距离。

• 推荐值: 4-8
• 性能影响: 中

view-distance：渲染距离。

• 默认值: 10
• 推荐值: 4-8
• 性能影响: 重

network-compression-threshold：服务器尝试压缩之前限制数据包的大小。

• 默认值：256
• 推荐值：64-128（过小容易造成过大的服务器 CPU 负担）

网上常见的联机方案是买一台 VPS 服务器，用它的公网 IP 来做联机映射。这种方法操作起来最简单，但 VPS 的配置往往和预算挂钩，预算有限的话，性能很难跟上 Minecraft 的运行需求。

既然如此，我们能否借助本地电脑的算力，用内网映射的方式来提升游戏性能，让联机体验更丝滑？

接下来，我将使用 VMware Workstation 搭建一台本地的 Minecraft 服务器。

注：以下配置需要基础的交换网络技术功底！

安装 Ubuntu 系统

在 VMware Workstation 上部署 Ubuntu 系统

为了方便后续的内网传统，VM 选择桥接模式（该模式可以让虚拟机直接直连网卡，网卡通过有线网络连接路由器），最终实现的效果就是 Ubuntu 直连路由器。之后在 Ubuntu 图形化中修改 IP 地址与路由器同网段。

桥接原理：

之后在 Terminal 中安装控制面板套件：

sudo su -c "wget -qO- https://script.mcsmanager.com/setup_cn.sh | bash"

# 先启动面板守护进程。
# 这是用于进程控制，终端管理的服务进程。
systemctl start mcsm-daemon.service
# 再启动面板 Web 服务。
# 这是用来实现支持网页访问和用户管理的服务。
systemctl start mcsm-web.service

# 重启面板命令
systemctl restart mcsm-daemon.service
systemctl restart mcsm-web.service

# 停止面板命令
systemctl stop mcsm-web.service
systemctl stop mcsm-daemon.service

之后通过 {IP}:23333 访问控制面板，做初步配置。

安装 Minecraft 所需的 JAVA JDK 21 环境

sudo apt install openjdk-21-jdk
java -version

NPS 服务端配置

VPS 防火墙请开启 80/443/8080/8024 端口，用于内网穿透映射

sudo ./nps install
The default configuration file of nps use 80，443，8080，8024 ports
80 and 443 ports for host mode default ports
8080 for web management access port
8024 for net bridge port, to communicate between server and client

配置conf/nps.conf
#web
web_username=xxx           //用户名
web_password=xxx           //密码
web_port = 8080         //默认8080端口登录
web_ip=0.0.0.0

NPS 开机自启

systemctl enable Nps

防火墙端口开启，这里以阿里云为例：

通过 {IP/域名}:8080 访问服务端控制面板，如下：

创建客户端列表

创建客户端隧道至 25565 端口（游戏默认25565端口，可按需修改）

注：记得放行 25565 端口防火墙规则

配置 Server Port

Server port: 25565
Target:{127.0.0.1/内网IP地址}:25565  // 25565 公网端口映射到私网 25565 端口

VM Ubuntu NPS 客户端服务

安装 NPS Client ，按照 NPS Server 提示运行内网穿透配置

wget https://github.com/ehang-io/nps/releases/download/v0.26.10/linux_386_client.tar.gz
./npc -server={服务端IP/域名}:8024 -vkey={秘钥信息} -type=tcp

Ubuntu Terminal 中运行，保持虚拟机后台运行！

Minecraft 服务端安装

访问内网 IP:23333，进入 Mincraft 服务器控制面板。创建新实例

启动命令
java -jar xxx.jar   //具体请根据服务端文件名称填写

上传服务端文件：

这里以 paper server 1.20.4 为例：

下载地址：

https://fill-data.papermc.io/v1/objects/cabed3ae77cf55deba7c7d8722bc9cfd5e991201c211665f9265616d9fe5c77b/paper-1.20.4-499.jar

上传至服务器文件根目录内启动服务：

按照要求同意通用协议：

这里只需要在配置服务端配置文件中打开即可！

总结

最终通过 Minecraft 多人服务器即可联机！

虽然总体上比较复杂，但可以最大化解决服务器配置不足的问题，只需要按需调整公网带宽即可。常规 1M 公网带宽可以支持 2-3 人原生服务器游玩。

参考链接

以下链接为所需要用到的原始下载链接：

https://github.com/ehang-io/nps
https://docs.mcsmanager.com/zh_cn/
https://papermc.io/downloads/paper

前提条件

1. Vmware Workstation 或者同类产品的虚拟化软件
2. 已经安装好的Ubuntu 64bit 系统

警告：不要使用 root 用户去编译！

sudo apt-get update
sudo apt-get -y install build-essential asciidoc binutils bzip2 gawk gettext git libncurses5-dev libz-dev patch python3 unzip zlib1g-dev lib32gcc1 libc6-dev-i386 subversion flex uglifyjs git-core gcc-multilib p7zip p7zip-full msmtp libssl-dev texinfo libglib2.0-dev xmlto qemu-utils upx libelf-dev autoconf automake libtool autopoint device-tree-compiler g++-multilib antlr3 gperf wget curl swig rsync  //编译预配环境

克隆 Lede 仓库

git clone https://github.com/coolsnowwolf/lede 
cd lede   //进入克隆好的仓库

编辑 feeds.conf.default

按照这个库去填，包含科学上网插件等等
src-git kenzo https://github.com/kenzok8/openwrt-packages
src-git small https://github.com/kenzok8/small
src-git packages https://github.com/coolsnowwolf/packages
src-git luci https://github.com/coolsnowwolf/luci
src-git routing https://github.com/coolsnowwolf/routing
src-git telephony https://github.com/openwrt/telephony.git;openwrt-23.05

编译

更新插件库，开始编译

./scripts/feeds update -a
./scripts/feeds install -a
make menuconfig

Target System : 选择系统架构，这里默认 x86 平台

Target Images ：

ext4：小型 Linux，适合装软件，需要大空间，软路由/NAS 场景推荐。
Squashfs：系统不可直接写入，只能通过 overlay 存储配置和数据，适合跑在嵌入式、小闪存设备（刷机+恢复出厂设置玩法。
combined：boot 分区和 rootfs 合成在一起。刷在硬盘或者 U 盘可以直接启动。 x86架构装机默认推荐此版本，适合 SSD 启动。
generic：通用固件（非特定硬件化优化），适合搭配不同文件系统。

推荐选择方案：

重要科学上网插件库路径：

LUCI/Applications/luci-app-xxx   //按需选择
第一次编译不推荐选择过多，建议删除非必要插件，提高编译成功率

编译清单
LuCI ---> Applications ---> luci-app-accesscontrol  #访问时间控制
LuCI ---> Applications ---> luci-app-acme  #ACME自动化证书管理环境（丢弃）
LuCI ---> Applications ---> luci-app-adblock   #ADB广告过滤
...（略）

来自：https://www.right.com.cn/forum/thread-344825-1-1.html

下载编译所需要的文件

make -j8 download V=s   // 8 代表八线程
make -j1 V=s   //编译，第一次推荐使用一线程，方便检查报错信息，如果报错请删除报错的插件

编译结束后在此文件夹中可见导出文件：

/lede/bin/target/x86/64/

二次编译：

./scripts/feeds update -a && ./scripts/feeds install -a             # 更新Feeds
rm -rf ./tmp && rm -rf .config                                      # 清除编译配置和缓存
make menuconfig                                                      # 进入编译配置菜单
make -j8 download
make -j$(($(nproc) + 1)) V=s

更改配置编译

cd lede
rm -rf ./tmp && rm -rf .config
make menuconfig
make -j$(($(nproc) + 1)) V=s

更改 LAN 口默认 IP 地址

cd lede
vim package/base-files/files/bin/config_generate

默认密码：password

Waline 是一个基于 LeanCloud 等后端的无后端评论系统，在 Hugo 等静态站点中非常流行。

优势：

• 前端资源小，加载快；
• 云端存储，无需部署数据库；
• 支持托管后台，配合 LeanCloud 效果很好；
• 支持多种样式；
• 支持游客或者QQ/微博等登录方式；

我选择此方案原因是支持社交媒体登录，评论区样式美观~

部署流程

创建 LeanCloud 账号

获取三个 API
AppID
AppKey
MasterKey

国内版需要完成备案接入：

如果你正在使用 Leancloud 国内版 (leancloud.cn)，推荐你切换到国际版 (leancloud.app)。否则，你需要为应用额外绑定已备案的域名，同时购买独立 IP 并完成备案接入:

• 登录国内版并进入需要使用的应用
• 选择 设置 > 域名绑定 > API 访问域名 > 绑定新域名 > 输入域名 > 确定。
• 按照页面上的提示按要求在 DNS 上完成 CNAME 解析。
• 购买独立 IP 并提交工单完成备案接入。(独立 IP 目前价格为 ￥ 50/个/月)

Vercel部署（服务端）

输入个人喜好的 Vercel 项目名称，并且创建

点击顶部的 Settings - Environment Variables 进入环境变量配置页，并配置三个环境变量 LEAN_ID, LEAN_KEY 和 LEAN_MASTER_KEY 。它们的值分别对应上一步在 LeanCloud 中获得的 APP ID, APP KEY, Master Key。

环境变量配置完成之后点击顶部的 Deployments 点击顶部最新的一次部署右侧的 Redeploy 按钮进行重新部署。该步骤是为了让刚才设置的环境变量生效。

此时会跳转到 Overview 界面开始部署，等待片刻后 STATUS 会变成 Ready。此时请点击 Visit ，即可跳转到部署好的网站地址，此地址即为你的服务端地址。

绑定域名（可选）

1. 点击顶部的 Settings - Domains 进入域名配置页
2. 输入需要绑定的域名并点击 Add

最终可以通过域名访问评论系统和管理系统：

• 评论系统：example.yourdomain.com
• 评论管理：example.yourdomain.com/ui

注：第一个注册的用户默认为管理员！！！

嵌入HTML

嵌入Html文件路径
创建 waline.html
/layouts/partials/comments.html  //取决于theme网页结构

Waline.html

<!-- Waline Comment System -->
<link
  rel="stylesheet"
  href="https://unpkg.com/@waline/client@v3/dist/waline.css"
/>

<div id="waline"></div>

<script type="module">
  import { init } from 'https://unpkg.com/@waline/client@v3/dist/waline.js';

  init({
    el: '#waline',
    serverURL: '{{ .serverURL }}',   //从 config.toml 获取
    locale: '{{ .locale | default "en" }}',
    dark: '{{ .dark | default "auto" }}',
  });
</script>

Comments.html

  {{- if $pageCommentSystems.waline }}
    {{- with .waline }}
      {{- partial "waline.html" . }}

本教程参考网站：https://waline.js.org/en/guide/get-started

由于我是长期 VPS 服务器的持有用户，最开始我尝试使用阿里云的 VPS 服务器作为平台作为Hugo Blog站点，随着部署的过程和最终的效果呈现，我觉得存在以下几方面的问题：

• 性能受限于 VPS 的性能配置；
• 使用 HTTPS，需要在 WEB 服务上配置 https 证书；
• 发布内容繁琐复杂，后台数据更新不够及时，依赖于脚本；
• 网页可靠性较低；
• 与 VPS 其他部署的服务部分处在冲突。

最后我选择 GitHub Pages 配合 Cloudflare 托管的方案实现 BLOG 的搭建。可以解决以上所以问题，重要的是免费！

GitHub + Cloudflare

注册配置 GitHub 仓库

Respsitory name： example.com （自定义填写Blog网站的仓库名）

安装 Git

安装 Git

后续为了方便本地化管理 GitHub仓库。

官网地址：https://git-scm.com/

本地 SSH 秘钥

在 Windows 本地使用 cmd 生成本地 SSH 秘钥

设置 SSH keys

在 GitHub 设置的 SSH and GPG keys 中填写生成的秘钥 SSH Keys

之后就可以通过 Git 命令，https 上传文件到仓库了~

Hugo 主题

在 Hugo themes 中挑选自己合适的主题，作为BLOG的模版。

https://themes.gohugo.io/

本网站主题如下：

https://github.com/reorx/hugo-PaperModX

Git 拉取仓库

git clone https://github.com/reorx/hugo-PaperModX.git

文件格式

• content：存储posts等
• data：社交媒体的配置
• layouts：整个静态网页的布局（重要！）
• assets：存储 css，js 文件，默认 toml 拉取头像
• i18n：多语言
• 我这里选择覆盖 ExampleSite 和仓库根目录，具体不同 theme 会有不同的配置方案。该教程不适配任何主题。

拉取文件到 GitHub

1. git init ：在此文件夹生成一个.git隐藏文件；
2. git add . : 将文件添加到缓存区( 注意这个"."，是有空格的，".“代表这个test这个文件夹下的目录全部都提交，也可以通过git add 文件名 提交指定的文件)；
3. git status：查看现在的状态，也可以不看，随你啦，可以看到picture文件夹里面的内容都提交上去了；
4. git commit -m “这里是注释”：提交添加到缓存区的文件；
5. git remote add origin remote_url ： 添加新的git方式的origin, github上创建好的仓库和本地仓库进行关联；
6. git push origin main：推送文件到仓库。

注：

• 第4步可能会让你配置个人信息，否则无法推送文件，具体请看 CLI 提示。
• 确保推送的仓库主分支和 CLI 一致。

配置 toml 文件

title = "ZORAN"  //BLOG标题
baseURL = "https://zoranzhou.com/"  //主网站信息
languageCode = "en-us"
defaultContentLanguage = "en"
enableEmoji = true
ignoreErrors = ["additional-script-loading-error"]
disqusShortname = ""

[pagination]  //主页显示文章数量
pagerSize = 10

##############################
# Params
##############################
[params]
TocSide = "left"   //左对齐
EnableInstantClick = false  //这里因为加了waline方案，所以需要false，确保html正确的刷新出来

# --- Logo ---
[params.logo] 
icon = "favicon.png" //存储在assets/favicon.png
iconWidth = 128        
iconHeight = 128
text = ""             

##############################
# Menu 确保导航分页都正常显示
##############################
[menu]

  [[menu.main]]
  name = "Home"
  url = "/"
  weight = 1

  [[menu.main]]
  name = "Blog"
  url = "/posts/"
  weight = 2
  
  [[menu.main]]
  name = "Archives"
  url = "/archives/"
  weight = 3
    [menu.main.params]
    external = false

# --- Social Icons --- 社交媒体配置
[[params.social]]
name = "github"
url = "xxx"

[[params.social]]
name = "twitter"
url = "xxx"

##############################
# Comments 评论区方案（可选）
##############################
[params.commentSystems.waline]
serverURL = "xxx" 评论区后台URL
locale = "en"

[params.defaultCommentSystems]
waline = true

其他常用属性

Theme Switch Toggle (白天夜晚主题相关)

Shows icon besides title of page to change theme

To disable it :

disableThemeToggle: true

You can refer following table for better understanding…

Archives Layout（存档页面布局）

Create a page with archive.md in content directory with following content

.
├── config.toml
├── content/
│   ├── archives.md   <--- Create archive.md here
│   └── posts/
 ── static/

and add the following to it

---
title: "Archive"
layout: "archives"
url: "/archives/"
summary: archives
---

注：Archives 布局不支持多语言月份翻译。

Search Page （搜索）

PaperModX uses Fuse.js Basic for seach functionality

Add the following to site config, config.yml

[outputs]
  home = ["HTML", "JSON","RSS"]

Create a page with search.md in content directory with following content.

---
title: "Search" # in any language you want
layout: "search" # is necessary
# url: "/archive"
# description: "Description for Search"
summary: "search"
---

To hide a particular page from being searched, add it in post’s fron’t matter

searchHidden: true

Share Buttons on post （分享按钮）

Displays Share Buttons at Bottom of each post

to show share buttons add

params:
    ShowShareButtons: true

Show post reading time （显示阅读时间）

Displays Reading Time (the estimated time, in minutes, it takes to read the content.)

To show reading time add

Params:
    ShowReadingTime: true

Show Table of Contents (Toc) on blog post （目录）

Displays ToC on blog-pages

To show ToC add following to page-variables

ShowToc: true

To keep Toc Open by default on a post add following to page-variables:

TocOpen: true

BreadCrumb Navigation （返回主页）

Adds BreadCrumb Navigation above Post’s Title to show subsections and Navigation to Home

params:
    ShowBreadCrumbs: true

Can be diabled for particular page’s front-matter

---
ShowBreadCrumbs: false
---

Cloudflare配置

Workers & Pages

配置workers & Pages

链接 GitHub 仓库

选择刚才创建好的仓库

Project name：随意
Production branch：选择正确的分支
Framework preset：选择Hugo

之后默认部署即可

添加自定义域名

填写自己拥有的域名即可，Cloudflare会自动化处理。

最后就可以通过域名访问到 BLOG了！

Cloudflare R2 对象存储 + WebP Cloud 代理加速

随着博客内容的增加，图片资源的存储和加载速度成为影响用户体验的关键因素。这里介绍一套免费的图片存储与加速方案：Cloudflare R2 配合 WebP Cloud 代理。

为什么需要这套方案？

• GitHub 仓库限制：大量图片会增加仓库体积，影响克隆和部署速度
• 加载速度：直接从 GitHub 或 Cloudflare Pages 加载图片，跨国访问速度不稳定
• 格式优化：现代浏览器支持 WebP 格式，体积更小，加载更快
• 成本考量：R2 提供 10GB 免费存储，WebP Cloud 提供免费代理转换服务

Cloudflare R2 配置

R2 是 Cloudflare 提供的兼容 S3 API 的对象存储服务。

创建 R2 存储桶

1. 登录 Cloudflare Dashboard，进入 R2 页面
2. 点击 Create bucket，输入存储桶名称（如 blog-storage）
3. 选择存储桶位置，建议选 Automatic 让 Cloudflare 自动优化

配置公开访问

R2 默认是私有的，需要配置公开访问才能通过 URL 直接访问图片：

1. 进入存储桶设置，找到 Public Access 选项
2. 开启 Allow Public Access
3. 绑定自定义域名（推荐）：
   • 在 Custom Domains 中添加你的子域名，如 images.yourdomain.com
   • 或者使用 WebP Cloud 提供的代理域名

获取 API 凭证

用于通过 API 上传图片：

1. 进入 R2 → Manage R2 API Tokens
2. 点击 Create API Token
3. 选择 Object Read & Write 权限
4. 复制 Access Key ID 和 Secret Access Key

API 连接信息示例：

Account ID: your-account-id
Access Key ID: your-access-key
Secret Access Key: your-secret-key
Bucket: blog-storage
S3 API Endpoint: https://your-account-id.r2.cloudflarestorage.com

上传图片到 R2

可以使用多种方式上传：

方式一：Cloudflare Dashboard 网页上传

• 适合偶尔上传少量图片

方式二：AWS CLI / boto3 脚本

• 适合批量上传和自动化工作流

import boto3

s3 = boto3.client(
    's3',
    endpoint_url='https://your-account-id.r2.cloudflarestorage.com',
    aws_access_key_id='your-access-key',
    aws_secret_access_key='your-secret-key',
    region_name='auto'
)

# 上传文件
s3.upload_file('local-image.jpg', 'blog-storage', 'image-20250101.jpg')

方式三：第三方工具（如 rclone、Cyberduck）

• 图形化界面，操作直观

WebP Cloud 代理加速

WebP Cloud（webp.fi）是一个免费的图片代理服务，可以自动将图片转换为 WebP 格式，并提供全球 CDN 加速。

配置 WebP Cloud

1. 访问 WebP Cloud 官网
2. 注册账号并添加你的 R2 存储桶作为源站
3. 配置自定义域名（可选）

使用方式

假设你的 R2 图片原始链接是：

https://your-bucket.your-account-id.r2.cloudflarestorage.com/image.jpg

通过 WebP Cloud 代理后：

https://your-proxy.webp.fi/image.jpg

WebP Cloud 会自动：

• 将图片转换为 WebP 格式（浏览器支持时）
• 压缩图片体积
• 通过 Cloudflare CDN 全球加速

在博客中使用

在 Hugo 的 Markdown 文章中引用：

![图片描述](https://your-proxy.webp.fi/image-20250101.jpg)

完整工作流示例

1. 撰写文章时，将图片保存到本地
2. 上传图片到 R2 存储桶
3. 获取 WebP Cloud 代理链接
4. 在 Markdown 中引用代理链接
5. 部署博客，图片会自动通过 WebP Cloud 加速加载

成本与限额

对于个人博客来说，免费额度完全够用。

总结

这套方案的优势：

• ✅ 完全免费：R2 + WebP Cloud 对个人用户免费
• ✅ 全球加速：Cloudflare CDN 覆盖全球
• ✅ 自动优化：WebP 格式自动压缩，提升加载速度
• ✅ 兼容性好：S3 API 标准，工具生态丰富
• ✅ 与现有工作流集成：不影响 Hugo + GitHub + Cloudflare Pages 的部署流程

通过这套方案，你的博客图片可以实现快速、稳定、低成本的全球分发。