0016 - OpenClaw + Kimi 配置全记录：从安装到天气组件迭代

会话概述

本次会话记录了与 AI 助手（Kimi）一起完成 OpenClaw 安装配置、Kimi API 接入，以及博客天气组件从零到迭代的完整过程。

一、OpenClaw 安装与配置

1.1 环境检查

网络环境: 用户连接 VPN（新加坡出口）
检测结果: 网络正常，Moonshot API 可访问
系统: macOS, Homebrew 已安装

1.2 安装步骤

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

# 配置 Gateway 模式
openclaw config set gateway.mode local

# 启动 Gateway
openclaw gateway start

1.3 配置 Kimi API

通过 openclaw onboard 交互配置：

Model/auth provider: Moonshot AI (Kimi K2.5)
API Key: sk-CkA2P20lwLqchuerr6QSleqbmUVV002P2jY7xIaGrqVbgqm0
Default model: moonshot/kimi-k2.5
分页设置: pagerSize = 99999（显示所有文章）

1.4 遇到的坑与解决

问题	原因	解决
Gateway 启动失败	`gateway.mode` 未设置	`openclaw config set gateway.mode local`
Config 无效	缺少环境变量	直接硬编码 API Key 到配置文件
CLI 连接错误	Gateway 与 CLI 通信问题	使用 Web UI 替代 CLI

二、天气组件开发迭代记录

2.1 初始版本问题

用户反馈:

底部有"🌤️ 天气加载中…“不想要
天气组件位置不对，要靠上
城市名显示英文/拼音，需要中文
天气描述是英文（sunny），需要中文
样式不美观，要透明毛玻璃风格

2.2 迭代过程

迭代 1: 删除底部天气组件

# 删除 public/index.html 中底部残留
sed -i '' 's|<div style="max-width:800px;margin:0 auto;padding:0 16px"><div id=weather-widget class=weather-widget><span>🌤️ 天气加载中...</span></div></div>||' index.html

迭代 2: 中文天气描述映射

在 weather-widget-v3.js 中添加：

const WEATHER_DESC_CN = {
  'sunny': '晴朗',
  'clear': '晴朗', 
  'partly cloudy': '局部多云',
  'light rain': '小雨',
  // ... 50+ 种天气状况
};

迭代 3: 中文城市名映射

添加 80+ 城市的中英文对照：

const CITY_NAME_CN = {
  'beijing': '北京', 'shanghai': '上海', 'nanjing': '南京',
  'guangzhou': '广州', 'shenzhen': '深圳', 'hangzhou': '杭州',
  // ... 更多城市
};

迭代 4: IP 定位优先

通过 ipapi.co 获取中文城市：

async function getCityByIP() {
  const response = await fetch('https://ipapi.co/json/');
  const data = await response.json();
  return CITY_NAME_CN[data.city] || data.city;
}

迭代 5: 文章卡片风格 CSS

修改 weather-widget-v3.css：

.weather-entry {
  margin-bottom: var(--gap, 24px);
}

.weather-card {
  background: var(--entry, #fff);
  border-radius: var(--radius, 8px);
  border: 1px solid var(--border, #eee);
  /* 继承文章卡片所有样式 */
}

迭代 6: 位置调整

修改 layouts/_default/list.html：

{{- if and .IsHome (eq $paginator.PageNumber 1) }}
<!-- 天气组件 - 作为独立文章条目 -->
<article class="post-entry weather-entry">
  <div id="weather-widget"></div>
</article>
{{- end }}

2.3 最终文件结构

blog/
├── layouts/
│   ├── _default/
│   │   └── list.html          # 修改：添加天气组件位置
│   └── partials/
│       └── home_info.html     # 修改：移除天气组件
├── static/
│   └── assets/
│       ├── css/
│       │   └── weather-widget-v3.css  # 透明毛玻璃风格
│       └── js/
│           └── weather-widget-v3.js   # 中文版
└── hugo.toml                  # 修改：pagerSize = 99999

三、底部”🌤️ 天气加载中…“删除详解

3.1 问题分析

现象: 每次 Hugo 构建后，页面底部总有一个”🌤️ 天气加载中…"

原因:

OpenClaw 最初在 layouts/partials/home_info.html 中添加了天气组件
后来又在 layouts/_default/list.html 中添加了独立文章条目的天气组件
但构建后的 public/index.html 底部还残留着旧的天气组件 HTML

文件关系:

layouts/partials/home_info.html 
    └── 被 themes/PaperMod/layouts/_default/list.html 引用
        └── 生成 public/index.html

layouts/_default/list.html (覆盖主题)
    └── 直接生成 public/index.html 中的 weather-entry

3.2 删除方法

方法 1: 直接修改生成的 HTML（临时）

cd public
sed -i '' 's|<div style="max-width:800px;margin:0 auto;padding:0 16px"><div id=weather-widget class=weather-widget><span>🌤️ 天气加载中...</span></div></div>||' index.html

方法 2: 修改源文件（永久）

文件 1: layouts/partials/home_info.html

{{- with site.Params.homeInfoParams }}
<article class="first-entry home-info">
    <header class="entry-header">
        <h1>{{ .Title | markdownify }}</h1>
    </header>
    
    <div class="entry-content">
        {{ .Content | markdownify }}
    </div>
    <footer class="entry-footer">
        {{ partial "social_icons.html" (dict "align" site.Params.homeInfoParams.AlignSocialIconsTo) }}
    </footer>
    
    <!-- 删除这里的天气组件 -->
    <!-- <div id="weather-widget"></div> -->
</article>
{{- end -}}

文件 2: layouts/_default/list.html（覆盖主题文件）

<!-- 在 home_info 之后添加 -->
{{- if and .IsHome (eq $paginator.PageNumber 1) }}
<article class="post-entry weather-entry">
  <div id="weather-widget"></div>
</article>
{{- end }}

方法 3: 自动化脚本（推荐）

创建 fix-weather.sh:

#!/bin/bash
cd public
# 删除底部残留
sed -i '' 's|<div style="max-width:8000px;margin:0 auto;padding:0 16px"><div id=weather-widget class=weather-widget><span>🌤️ 天气加载中...</span></div></div>||g' index.html
sed -i '' 's|<div style="max-width:800px;margin:0 auto;padding:0 16px"><div id=weather-widget class=weather-widget><span>🌤️ 天气加载中...</span></div></div>||g' index.html
echo "已清理底部天气组件"

四、默认显示南京天气修改详解

4.1 问题分析

用户反馈: 天气服务加载太慢，页面一直显示 loading

解决方案:

立即显示默认南京天气（不等待 API）
后台异步获取真实天气数据
获取成功后平滑更新显示

4.2 修改文件

文件: static/assets/js/weather-widget-v3.js

修改 1: 添加默认天气数据方法

在 WeatherApp 对象中添加：

const WeatherApp = {
  // 默认南京天气数据（用于立即显示）
  getDefaultWeatherData() {
    return {
      temp: '15',
      feelsLike: '14',
      desc: '晴朗',
      humidity: '55',
      wind: '12',
      city: '南京'
    };
  },
  // ...
}

修改 2: 修改 init 方法

async init() {
  if (state.isInitialized) return;
  
  state.widget = document.getElementById('weather-widget');
  if (!state.widget) return;
  
  state.isInitialized = true;
  
  // 获取访问者信息
  state.visitorInfo = await getVisitorInfo();
  
  // 尝试从缓存加载
  const cached = Cache.get();
  if (cached && cached.weather) {
    // 有缓存，显示缓存数据
    UI.render(cached.weather, cached.city);
  } else {
    // 无缓存，立即显示默认南京天气（不显示 loading）
    const defaultWeather = this.getDefaultWeatherData();
    UI.render(defaultWeather, defaultWeather.city);
  }
  
  // 后台异步更新真实天气（不阻塞页面）
  this.updateWeatherInBackground();
},

修改 3: 添加后台更新方法

// 后台异步更新天气
async updateWeatherInBackground() {
  try {
    // 优先使用 IP 定位获取城市
    const ipLocation = await getCityByIP();
    if (ipLocation) {
      await this.loadWeatherByCity(ipLocation.city, ipLocation);
    } else {
      // 加载默认天气
      await this.loadDefaultWeather();
    }
    
    // 异步尝试浏览器定位（更精确）
    this.tryGeolocation();
  } catch (error) {
    console.log('后台天气更新失败:', error);
    // 失败时保持默认显示，不报错
  }
},

修改 4: 修改 loadDefaultWeather（静默失败）

async loadDefaultWeather() {
  try {
    const cached = Cache.get();
    if (cached && cached.city === CONFIG.DEFAULT_CITY_NAME) return;
    
    const weather = await API.getWeather(CONFIG.DEFAULT_CITY);
    UI.render(weather, weather.city || CONFIG.DEFAULT_CITY_NAME);
    Cache.set(weather, weather.city || CONFIG.DEFAULT_CITY_NAME);
  } catch (error) {
    console.warn('默认天气加载失败:', error);
    // 静默失败，保持当前显示（默认南京天气）
  }
},

4.3 代码执行流程

页面加载
  ↓
init() 调用
  ↓
检查缓存？
  ├── 有缓存 → 显示缓存天气
  └── 无缓存 → 显示默认南京天气（立即）
  ↓
updateWeatherInBackground() 后台执行
  ↓
尝试 IP 定位 → 获取真实天气 → 更新显示

用户体验:

页面打开立即看到南京天气（无 loading）
1-3 秒后自动更新为真实天气（如果有缓存或定位成功）
API 失败时保持南京天气显示，不报错

五、Git 提交记录

# 添加所有修改
git add .

# 提交
git commit -m "feat: OpenClaw + Kimi 集成，天气组件 v3.3

- 安装配置 OpenClaw 2026.3.7
- 接入 Moonshot/Kimi K2.5 API
- 天气组件从 v1 迭代到 v3.3
  - 中文城市名（IP定位优先）
  - 中文天气描述（50+种映射）
  - 文章卡片风格（与主题一致）
  - 透明毛玻璃效果
- Hugo 分页设置 99999（不分页）
- 删除底部残留天气组件
- 默认显示南京天气（后台异步更新）"

# 推送
git push origin main

六、核心代码片段

6.1 城市名中文化

function extractCityName(apiData) {
  const areaName = safeGet(apiData, 'nearest_area.0.areaName.0.value');
  if (areaName) {
    // 尝试精确匹配
    if (CITY_NAME_CN[areaName]) return CITY_NAME_CN[areaName];
    // 尝试小写匹配
    if (CITY_NAME_CN[areaName.toLowerCase()]) return CITY_NAME_CN[areaName.toLowerCase()];
    // 尝试首字母大写匹配
    const capitalized = areaName.charAt(0).toUpperCase() + areaName.slice(1).toLowerCase();
    if (CITY_NAME_CN[capitalized]) return CITY_NAME_CN[capitalized];
    return areaName;
  }
  return null;
}

6.2 天气描述中文化

const WEATHER_DESC_CN = {
  'sunny': '晴朗',
  'partly cloudy': '局部多云',
  'light rain': '小雨',
  'moderate rain': '中雨',
  'heavy rain': '大雨',
  'thunderstorm': '雷阵雨',
  // ...
};

function extractWeatherData(apiData) {
  const englishDesc = current.weatherDesc?.[0]?.value || 'Unknown';
  const chineseDesc = WEATHER_DESC_CN[englishDesc.toLowerCase()] || englishDesc;
  return { desc: chineseDesc, /* ... */ };
}

6.3 立即显示默认天气

// 默认南京天气数据
getDefaultWeatherData() {
  return {
    temp: '15',
    feelsLike: '14',
    desc: '晴朗',
    humidity: '55',
    wind: '12',
    city: '南京'
  };
},

// init 中立即显示
if (!cached) {
  const defaultWeather = this.getDefaultWeatherData();
  UI.render(defaultWeather, defaultWeather.city);
}

七、调试技巧总结

7.1 检查底部天气组件

grep -n "天气加载中" public/index.html

grep -o "id=weather-widget" public/index.html | wc -l
# 应该只有 1 个

7.3 查看 JS 是否加载

浏览器 Console 执行：

console.log(WeatherApp.getDefaultWeatherData());
// 应该输出南京天气数据

7.4 强制刷新

open http://localhost:8080
# 然后按 Cmd+Shift+R 强制刷新

会话时间

开始: 2026-03-09 11:00 CST
结束: 2026-03-09 13:00 CST
总时长: 约 2 小时

关键决策

使用 IP 定位优先：比浏览器定位更稳定，且能获取中文城市名
文章卡片风格：放弃毛玻璃效果，改为与 Hugo PaperMod 主题完全一致
独立文章条目：天气组件作为 post-entry，与其他文章保持相同间距
立即显示默认天气：解决 API 慢的问题，提升用户体验
后台异步更新：不阻塞页面渲染，获取真实天气后平滑更新

会话概述#

一、OpenClaw 安装与配置#

1.1 环境检查#

1.2 安装步骤#

1.3 配置 Kimi API#

1.4 遇到的坑与解决#

二、天气组件开发迭代记录#

2.1 初始版本问题#

2.2 迭代过程#

迭代 1: 删除底部天气组件#

迭代 2: 中文天气描述映射#

迭代 3: 中文城市名映射#

迭代 4: IP 定位优先#

迭代 5: 文章卡片风格 CSS#

迭代 6: 位置调整#

2.3 最终文件结构#

三、底部”🌤️ 天气加载中…“删除详解#

3.1 问题分析#

3.2 删除方法#

方法 1: 直接修改生成的 HTML（临时）#

方法 2: 修改源文件（永久）#

方法 3: 自动化脚本（推荐）#

四、默认显示南京天气修改详解#

4.1 问题分析#

4.2 修改文件#

修改 1: 添加默认天气数据方法#

修改 2: 修改 init 方法#

修改 3: 添加后台更新方法#

修改 4: 修改 loadDefaultWeather（静默失败）#

4.3 代码执行流程#

五、Git 提交记录#

六、核心代码片段#

6.1 城市名中文化#

6.2 天气描述中文化#

6.3 立即显示默认天气#

七、调试技巧总结#

7.1 检查底部天气组件#

7.2 检查 weather-widget 数量#

7.3 查看 JS 是否加载#

7.4 强制刷新#

会话时间#

关键决策#