旅行青蛙 Travel Frog 🐸

English | 中文

中文

项目介绍

旅行青蛙是一个基于 OpenClaw 的放置类 Agent 游戏。你的青蛙会自主旅行、寄明信片、拍照片、写日记，就像经典的《旅行青蛙》游戏一样。

✨ 特性

• 🐸 自主旅行 — 青蛙会根据心情和时间自己决定出门旅行
• 📮 明信片系统 — 旅途中会寄明信片回来，带图片和文字
• 📸 拍照功能 — 可以让青蛙拍照分享当前状态
• 📔 日记系统 — 青蛙会写日记记录每天的经历
• 🎁 纪念品收集 — 旅行回来会带回当地纪念品
• 🗺️ 世界探索 — 青蛙会逐步解锁新地区，学习当地文化
• 🎨 AI 图片生成 — 明信片和照片由 AI 自动生成（推荐 OpenAI gpt-image-1.5）

📋 前置准备

开始之前，请准备好以下信息：

| 类型 | 说明 | 获取方式 | |------|------|----------| | Discord Bot Token 或 Telegram Bot Token | 消息收发（必需） | Discord Developer Portal / BotFather | | UserId | 消息发送目标（必需） | Telegram: 通过 @userinfobot 获取 | | OpenAI API Key | AI 图片生成（可选，推荐） | OpenAI Platform | | Gemini API Key | AI 图片生成（可选，替代方案） | Google AI Studio |

🚀 快速开始

自动安装（推荐）

npx travel-frog@latest

安装器会引导你完成：

1. 环境检查
2. Skill 安装
3. Workspace 创建
4. 给青蛙起名
5. 配置消息频道
6. 设置图片生成
7. 自动配置 OpenClaw

手动安装

如果你更喜欢手动配置：

1. 安装 skill

clawhub install travel-frog -workdir ~/.openclaw/workspace-frog

2. 复制模板文件

SOURCE_DIR=~/.openclaw/workspace-frog/skills/travel-frog/templates
DEST_DIR=~/.openclaw/workspace-frog

# 一次性复制所有文件和目录
cp "$SOURCE_DIR"/{AGENTS.md,SOUL.md,HEARTBEAT.md,TOOLS.md,IDENTITY.md} "$DEST_DIR/"
cp -r "$SOURCE_DIR/memory" "$DEST_DIR/"

3. 编辑 IDENTITY.md 给青蛙起名

nano ~/.openclaw/workspace-frog/IDENTITY.md

4. 配置 OpenClaw

编辑 ~/.openclaw/openclaw.json：

{
  "agents": {
    "list": [
      {
        "id": "frog",
        "workspace": "~/.openclaw/workspace-frog",
        "skills": ["travel-frog"]
      }
    ]
  },
  "bindings": [
    { "agentId": "frog", "match": {"channel": "discord", "accountId": "frog"}}
  ],
  "tools": {
    "profile": "full",
    "sessions": {"visibility": "all"}
  },
  "channels": {
    "discord": {
      "accounts": {
        "frog": {
          "token": "TOKEN"
        }
      }
    }
  }
}

5. 配置消息频道

编辑 ~/.openclaw/workspace-frog/TOOLS.md，填写你的频道信息：

## 消息发送

- `accountId`: `frog`
- `channel`: `discord`（或 `telegram`）
- `target`: `TARGET`（discord:UserId/telegram:UserId）

6. 配置图片生成（可选）

将全局安装的图片生成 skill 软链接到 workspace 中：

# 找到全局 skill 目录（二选一）
# macOS: /opt/homebrew/lib/node_modules/openclaw/skills/
# Linux: ~/.npm-global/lib/node_modules/openclaw/skills/

GLOBAL_SKILLS=/opt/homebrew/lib/node_modules/openclaw/skills
ln -s "$GLOBAL_SKILLS/openai-image-gen" ~/.openclaw/workspace-frog/skills/
ln -s "$GLOBAL_SKILLS/nano-banana-pro" ~/.openclaw/workspace-frog/skills/

配置 API key 到 ~/.openclaw/.env：

OPENAI_API_KEY=sk-**
GEMINI_API_KEY=sk-**

7. 启动 OpenClaw

openclaw gateway start

8. 配置定时任务

openclaw cron add \
  --every 15m \
  --name "Travel Frog Engine" \
  --timeout-seconds 300 \
  --agent "frog" \
  --no-deliver \
  --message "用 exec 运行 \`python3 skills/travel-frog/scripts/frog_engine.py tick\`, 如果输出包含\`\"events\": []\`, 直接返回 NO_REPLY。否则读取 HEARTBEAT.md 处理返回的事件。"

📖 使用方法

查看青蛙状态

在配置的频道中发送：

• 看看蛙
• 在干嘛
• frog status

查看明信片收藏

• 明信片
• 看明信片
• postcards

让青蛙拍照

• 拍照
• 拍张照
• 来张照片

召回青蛙

• 回来
• 召回
• 叫醒

推荐地方

• 你应该去北海道看薰衣草
• 推荐你去京都

青蛙会记住你的推荐，之后可能会去。

🎮 游戏机制

时间系统

• 默认配置：1 游戏小时 = 1 现实小时
• 睡觉时间：23:00 - 08:00
• 心跳频率：15 分钟检查一次

旅行系统

青蛙会根据以下因素决定是否出门：

• 当前时间（早上起床后、白天）
• 最近旅行历史（避免重复去同一个地方）
• 朋友推荐
• 节日和季节

旅程包含多个阶段：

• Transit — 交通阶段（新干线、渡轮等）
• Explore — 游玩阶段（景点、美食、活动）

明信片系统

• 每次旅行至少寄一张明信片
• 明信片包含文字描述和 AI 生成的图片
• 明信片会归档到收藏中

照片系统

• 可以随时让青蛙拍照
• 根据当前状态生成场景（在家/旅行中/睡觉）
• 照片也会归档到收藏中

记忆系统

青蛙会维护多个记忆文件：

• memory/YYYY-MM-DD.md — 每日日记
• memory/world_knowledge.md — 世界认知（已解锁区域）
• memory/friend_tips.md — 朋友推荐
• MEMORY.md — 长期记忆（旅行统计、成长记录）

🛠️ 配置说明

skills/travel-frog/config.json

{
  "sleepTime": {
    "start": 23,    // 睡觉时间（小时）
    "end": 8        // 起床时间（小时）
  },
  "travel": {
    "timeMultiplier": 3600  // 时间倍率（3600 = 正式体验）
  },
  "rewards": {
    "cloversOnReturn": 3,   // 回家获得三叶草数量
    "initialClovers": 10    // 初始三叶草数量
  }
}

🐛 故障排查

青蛙不发消息

1. 检查 TOOLS.md 中的频道配置是否正确
2. 检查 OpenClaw gateway 是否运行：openclaw gateway status
3. 查看日志：tail -f ~/.openclaw/workspace-frog/travel-frog-data/engine.log

图片生成失败

1. 检查图片生成 skill 是否安装
2. 检查 API key 是否配置
3. 查看 TOOLS.md 中的图片生成配置

心跳不工作

1. 执行 openclaw cron list | grep "Travel Frog Engine"
2. 重启 gateway：openclaw gateway restart

📝 开发指南

项目结构

travel-frog/
├── skill/                  # ClawHub skill
│   ├── SKILL.md           # 引擎文档
│   ├── config.json        # 默认配置
│   ├── scripts/           # 核心引擎
│   └── templates/         # Workspace 模板
├── bin/                   # npm 安装器
└── examples/              # 示例配置

本地测试

# 测试引擎
cd ~/.openclaw/workspace-frog/skills/travel-frog
python3 scripts/frog_engine.py status

# 测试心跳
python3 scripts/frog_engine.py tick

# 测试旅行
python3 scripts/frog_engine.py depart --journey '{"title":"测试","totalHours":1,"phases":[...]}'

贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add amazing feature'
4. 推送分支：git push origin feature/amazing-feature
5. 提交 Pull Request

📄 许可证

MIT License - 详见 LICENSE

🙏 致谢

• OpenClaw - AI Agent 框架
• 经典游戏《旅行青蛙》的灵感

English

Introduction

Travel Frog is an idle agent game built on OpenClaw. Your frog will autonomously travel, send postcards, take photos, and keep a diary, just like the classic "Travel Frog" game.

✨ Features

• 🐸 Autonomous Travel — Frog decides when to travel based on mood and time
• 📮 Postcard System — Sends postcards with AI-generated images during trips
• 📸 Photo Feature — Take photos of current activities
• 📔 Diary System — Keeps daily diary entries
• 🎁 Souvenir Collection — Brings back local souvenirs
• 🗺️ World Exploration — Gradually unlocks new regions and learns local culture
• 🎨 AI Image Generation — Postcards and photos generated by AI (recommended: OpenAI gpt-image-1.5)

📋 Prerequisites

Before you begin, have the following ready:

| Item | Description | Where to get | |------|-------------|--------------| | Discord Bot Token or Telegram Bot Token | Message channel (required) | Discord Developer Portal / BotFather | | UserId | Message target (required) | Telegram: via @userinfobot | | OpenAI API Key | AI image generation (optional, recommended) | OpenAI Platform | | Gemini API Key | AI image generation (optional, alternative) | Google AI Studio |

🚀 Quick Start

Automatic Installation (Recommended)

npx travel-frog@latest

The installer will guide you through:

1. Environment check
2. Skill installation
3. Workspace creation
4. Naming your frog
5. Configuring message channels
6. Setting up image generation
7. Auto-configuring OpenClaw

Manual Installation

If you prefer manual setup:

1. Install skill

clawhub install travel-frog -workdir ~/.openclaw/workspace-frog

2. Copy template files

SOURCE_DIR=~/.openclaw/workspace-frog/skills/travel-frog/templates
DEST_DIR=~/.openclaw/workspace-frog

# Copy all files and directories at once
cp "$SOURCE_DIR"/{AGENTS.md,SOUL.md,HEARTBEAT.md,TOOLS.md,IDENTITY.md} "$DEST_DIR/"
cp -r "$SOURCE_DIR/memory" "$DEST_DIR/"

3. Edit IDENTITY.md to name your frog

nano ~/.openclaw/workspace-frog/IDENTITY.md

4. Configure OpenClaw

Edit ~/.openclaw/openclaw.json:

{
  "agents": {
    "list": [
      {
        "id": "frog",
        "workspace": "~/.openclaw/workspace-frog",
        "skills": ["travel-frog"]
      }
    ]
  },
  "bindings": [
    { "agentId": "frog", "match": {"channel": "discord", "accountId": "frog"}}
  ],
  "tools": {
    "profile": "full",
    "sessions": {"visibility": "all"}
  },
  "channels": {
    "discord": {
      "accounts": {
        "frog": {
          "token": "TOKEN"
        }
      }
    }
  }
}

5. Configure message channel

Edit ~/.openclaw/workspace-frog/TOOLS.md with your channel info:

## Message Sending

- `accountId`: `frog`
- `channel`: `discord` (or `telegram`)
- `target`: `TARGET` (discord:UserId / telegram:UserId)

6. Configure image generation (optional)

Symlink image generation skills from the global installation into your workspace:

# Find your global skill directory (pick one)
# macOS: /opt/homebrew/lib/node_modules/openclaw/skills/
# Linux: ~/.npm-global/lib/node_modules/openclaw/skills/

GLOBAL_SKILLS=/opt/homebrew/lib/node_modules/openclaw/skills
ln -s "$GLOBAL_SKILLS/openai-image-gen" ~/.openclaw/workspace-frog/skills/
ln -s "$GLOBAL_SKILLS/nano-banana-pro" ~/.openclaw/workspace-frog/skills/

Configure API key in ~/.openclaw/.env:

OPENAI_API_KEY=sk-**
GEMINI_API_KEY=sk-**

7. Start OpenClaw

openclaw gateway start

8. Configure cron job

openclaw cron add \
  --every 15m \
  --name "Travel Frog Engine" \
  --timeout-seconds 300 \
  --agent "frog" \
  --no-deliver \
  --message "Run \`python3 skills/travel-frog/scripts/frog_engine.py tick\` via exec. If output contains \`\"events\": []\`, return NO_REPLY. Otherwise read HEARTBEAT.md and handle the returned events."

📖 Usage

Check frog status

Send in your configured channel:

• 看看蛙 (Chinese)
• 在干嘛 (Chinese)
• frog status

View postcard collection

• 明信片 (Chinese)
• postcards

Take a photo

• 拍照 (Chinese)
• take a photo

Call frog home

• 回来 (Chinese)
• come home

Recommend places

• You should visit Hokkaido for lavender fields
• I recommend Kyoto

The frog will remember your recommendations and may visit later.

🎮 Game Mechanics

Time System

• Default: 1 game hour = 1 real hour
• Sleep time: 23:00 - 08:00
• Heartbeat frequency: Check every 15 minutes

Travel System

Frog decides to travel based on:

• Current time (after waking up, daytime)
• Recent travel history (avoids repeating same places)
• Friend recommendations
• Holidays and seasons

Journeys include multiple phases:

• Transit — Transportation (bullet train, ferry, etc.)
• Explore — Sightseeing (attractions, food, activities)

Postcard System

• At least one postcard per trip
• Postcards include text and AI-generated images
• Postcards are archived in collection

Photo System

• Take photos anytime
• Generates scenes based on current state (home/traveling/sleeping)
• Photos are also archived

Memory System

Frog maintains multiple memory files:

• memory/YYYY-MM-DD.md — Daily diary
• memory/world_knowledge.md — World knowledge (unlocked regions)
• memory/friend_tips.md — Friend recommendations
• MEMORY.md — Long-term memory (travel stats, growth records)

🛠️ Configuration

skills/travel-frog/config.json

{
  "sleepTime": {
    "start": 23,    // Sleep time (hour)
    "end": 8        // Wake time (hour)
  },
  "travel": {
    "timeMultiplier": 3600  // Time multiplier (3600 = real-time)
  },
  "rewards": {
    "cloversOnReturn": 3,   // Clovers earned on return
    "initialClovers": 10    // Initial clovers
  }
}

🐛 Troubleshooting

Frog not sending messages

1. Check channel config in TOOLS.md
2. Check OpenClaw gateway: openclaw gateway status
3. View logs: tail -f ~/.openclaw/workspace-frog/travel-frog-data/engine.log

Image generation fails

1. Check if image generation skill is installed
2. Check if API key is configured
3. Review image generation config in TOOLS.md

Heartbeat not working

1. Run openclaw cron list | grep "Travel Frog Engine"
2. Restart gateway: openclaw gateway restart

📝 Development

Project Structure

travel-frog/
├── skill/                  # ClawHub skill
│   ├── SKILL.md           # Engine documentation
│   ├── config.json        # Default config
│   ├── scripts/           # Core engine
│   └── templates/         # Workspace templates
├── bin/                   # npm installer
└── examples/              # Example configs

Local Testing

# Test engine
cd ~/.openclaw/workspace-frog/skills/travel-frog
python3 scripts/frog_engine.py status

# Test heartbeat
python3 scripts/frog_engine.py tick

# Test travel
python3 scripts/frog_engine.py depart --journey '{"title":"Test","totalHours":1,"phases":[...]}'

Contributing

Issues and Pull Requests are welcome!

1. Fork this repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push branch: git push origin feature/amazing-feature
5. Submit Pull Request

📄 License

MIT License - see LICENSE

🙏 Acknowledgments

• OpenClaw - AI Agent Framework
• Classic "Travel Frog" game for inspiration

Star ⭐ this repo if you like it!