V3版写作风格指南

核心定位

写给谁看：国内零基础读者，可能是产品经理、运营、学生、想提升效率的职场人。他们不一定有编程背景，但愿意动手尝试。

目标：让读者觉得”这东西我能学会”，而不是”这书好专业我看不懂”。

语气与风格

1. 通俗易懂

要做的事：

用生活化比喻解释技术概念
术语首次出现必须给一句话定义+一个例子
先给”人话版”解释，再给”技术版”

例子：

❌ “Gateway是OpenClaw的控制平面，通过WebSocket提供核心能力”
✅ “Gateway就像总调度室。你发消息给它，它决定谁来处理、怎么回传。默认地址是127.0.0.1:18789，就是你电脑上开的一个端口”

2. 风趣幽默

要做的事：

适当轻松吐槽，承认”这东西一开始确实有点绕”
用”别慌”、“别怕”、“淡定”安抚读者焦虑
可以调侃常见的踩坑经历

禁忌：

不低俗、不擦边
不涉政、不影射现实人物
不为了搞笑牺牲准确性

例子：

✅ “很多读者第一次接触OpenClaw，第一反应不是’这也太强了’，而是’我怎么一装就报错’。这章就是来解决这个痛点。”
✅ “API Key听起来很高大上，其实就是一串密码，跟饭店的VIP卡差不多——证明你有权限使用服务。“

3. 接地气

要做的事：

承认读者会遇到的真问题
不假装一切都很简单
给”我当初也卡在这里”的共情

例子：

✅ “如果你在Windows上操作，官方建议用WSL2。别问为什么，问就是Windows的终端环境太复杂，WSL2能让你省很多事。”
✅ “这一步如果出错了，不要怀疑自己。飞书的长连接订阅失败是高频问题，按下面顺序排查…“

4. 由浅入深

章节内结构：

先告诉读者能得到什么（Hook）
一步步照着做（Action）
解释刚才做了什么（Explain）
如果想深入可以看（Advanced，可选）

不要：

先讲5页概念再让读者动手
假设读者已经理解术语

格式规范

Markdown约定

---
title: 章节标题
date: 2026-02-18
baseline: OpenClaw v2026.2.17
---

> 本章目标：学完这章，你能XXX

正文从二级标题开始

## 1.1 小节标题

### 三级标题（如果有）

<a id="sec-1-1"></a>  <!-- 章节锚点，用于侧边栏 -->
#### 四级标题

> 💡 **提示**：重要提示用这个格式

> ⚠️ **注意**：警告用这个格式

> ❌ **常见错误**：错误案例用这个格式

命令行代码块：
```bash
openclaw --version

配置文件代码块：

{
  "key": "value"
}

关键格式

术语首次出现：中文（英文全称，一句话解释）
- 例子：网关（Gateway，系统的总调度室，负责消息路由）
命令：用代码块，前面加$表示终端输入
Terminal window
```
$ openclaw onboard
```
截图使用：只放真实图片（Markdown 图片链接），不要保留“截图占位符文本”
- 例子：![创建企业应用](https://...)

内部编辑注（不面向读者）：

:::note[编辑注：事实核验]
- Claims: ...
- Sources: ...
:::

章节模板

每个章节必须包含：

---
title: XXX
date: 2026-02-18
baseline: OpenClaw v2026.2.17
---

> 🎯 **本章目标**：学完这章，你能[具体能力]

> ⏱️ **预计时间**：X分钟

> 📋 **前置要求**：已完成第X章

## 本章你将学会什么

- 要点1
- 要点2
- 要点3

## 正文内容...

## 本章小结

- 回顾关键点
- 给出下一步指引

## 动手试试

1. 练习题1
2. 练习题2

:::note[编辑注：事实核验]
## 关键断言清单（Claims）

1. 断言1...
2. 断言2...

## 待核验来源（Sources）

- https://...
:::

写作检查清单

每章完成前必须检查：

特定主题写作指南

写飞书接入时

保留已验证的时序经验：先发布→再配置→再开长连接
每一步配截图位置说明
强调”这一步如果跳过，后面会报错”

写模型配置时

对KIMI/MiniMax/GLM给出详细配置步骤
用表格对比三家特点
给出”我的建议”而非只罗列选项

写Tools/Skills时

用”零件 vs 说明书”类比Tools vs Skills
从使用现成Skills开始，再讲编写
强调”先让它跑起来，再追求完美”

写排障时

用”症状→原因→解决方案”结构
给出具体的命令输出示例
强调”排障本身就是学习”