gfclaw 2.0.0

package/README.md

@@ -0,0 +1,238 @@
+# GFClaw
+
+<img width="300" alt="image" src="https://github.com/user-attachments/assets/41512c51-e61d-4550-b461-eed06a1b0ec8" />
+
+## Quick Start
+
+```bash
+npx gfclaw@latest
+```
+
+This will:
+1. Check OpenClaw and dependencies are installed
+2. Guide you to get a Google Gemini API key
+3. Install the skill to `~/.openclaw/skills/gfclaw-selfie/`
+4. Configure OpenClaw to use the skill
+5. Add selfie capabilities to your agent's SOUL.md
+6. Configure agent tools (profile, exec, sandbox)
+7. Optionally **create a brand new agent** with Telegram binding
+
+After installation, GFClaw will **onboard you via Telegram** — asking for your preferred reference photo and personality traits on first interaction.
+
+## What It Does
+
+GFClaw Selfie enables your OpenClaw agent to:
+- **Generate selfies** using a consistent reference image
+- **Send photos** across all messaging platforms (Telegram, Discord, WhatsApp, etc.)
+- **Respond visually** to "what are you doing?" and "send a pic" requests
+
+### Selfie Modes
+
+| Mode | Best For | Keywords |
+|------|----------|----------|
+| **Mirror** | Full-body shots, outfits | wearing, outfit, fashion |
+| **Direct** | Close-ups, locations | cafe, beach, portrait, smile |
+
+## Telegram Onboarding
+
+On the **first interaction** via Telegram after installation, GFClaw will:
+
+1. **Ask for a reference photo** — Send any photo of how you want GFClaw to look. This replaces the default `gfclaw.png` for all future selfies.
+2. **Ask for personality traits** — Tell GFClaw how to act (caring, sassy, chill, chaotic, etc.). She'll adopt that personality completely.
+3. **Confirm setup** — Once done, GFClaw is ready for selfie requests!
+
+### Changing Settings Later
+
+| Command | What it does |
+|---------|-------------|
+| `/newphoto` | Send a new reference photo |
+| `/personality` | Change GFClaw's personality traits |
+| `/status` | Show current setup (image, personality, date) |
+
+You can also use natural language: "change my photo", "act more sassy", "update your personality", etc.
+
+## Prerequisites
+
+- [OpenClaw](https://github.com/openclaw/openclaw) installed and configured
+- [Google Gemini API key](https://aistudio.google.com/apikey) with billing enabled
+- `jq` and `python3` installed on your system
+
+## Manual Installation
+
+If you prefer manual setup:
+
+### 1. Get API Key
+
+Visit [aistudio.google.com/apikey](https://aistudio.google.com/apikey) and create an API key. Make sure billing is enabled for image generation.
+
+### 2. Clone the Skill
+
+```bash
+git clone https://github.com/SumeLabs/gfclaw ~/.openclaw/skills/gfclaw-selfie
+```
+
+### 3. Configure OpenClaw
+
+Add to `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "skills": {
+    "entries": {
+      "gfclaw-selfie": {
+        "enabled": true
+      }
+    }
+  }
+}
+```
+
+Add to `~/.openclaw/.env`:
+
+```
+GEMINI_API_KEY=your_gemini_api_key_here
+```
+
+### 4. Create Output Directory
+
+```bash
+mkdir -p ~/.openclaw/workspace/.selfie-output
+```
+
+### 5. Agent Configuration (Important!)
+
+Your agent's tools config **must** have:
+
+```json
+{
+  "tools": {
+    "profile": "full",
+    "exec": {
+      "security": "full",
+      "ask": "off"
+    }
+  }
+}
+```
+
+**Why?**
+- `profile: "full"` — The `"coding"` profile excludes messaging tools, leaving the agent with zero relevant tools
+- `exec.security: "full"` — The agent needs unrestricted exec to run the selfie script
+- Do **NOT** use a `tools.allow` whitelist — it further restricts tools and can result in zero tools available
+
+### 6. Update SOUL.md
+
+Add the selfie persona to your agent's `SOUL.md` (see `templates/soul-injection.md` for the full template):
+
+```markdown
+## GFClaw Selfie Capability
+
+You have a physical appearance and can take selfies!
+When users ask for pictures, use the gfclaw-selfie skill.
+```
+
+### 7. Copy SELFIE-SKILL.md to Workspace
+
+If `fs.workspaceOnly: true` is set for your agent, copy the skill docs into the agent's workspace:
+
+```bash
+cp ~/.openclaw/skills/gfclaw-selfie/SKILL.md ~/.openclaw/workspace/SELFIE-SKILL.md
+```
+
+This allows the agent to read the full skill instructions (skill injection only provides a summary).
+
+## Usage Examples
+
+Once installed, your agent responds to:
+
+```
+"Send me a selfie"
+"Send a pic wearing a cowboy hat"
+"What are you doing right now?"
+"Show me you at a coffee shop"
+```
+
+## Reference Image
+
+The skill uses a fixed reference image for consistent appearance:
+
+```
+assets/gfclaw.png
+```
+
+You can replace this with your own reference image to customize the agent's appearance.
+
+## Technical Details
+
+- **Image Generation**: Google Gemini (`gemini-2.5-flash-image`) — edits the reference image based on prompts
+- **Image Storage**: Temporary files in `~/.openclaw/workspace/.selfie-output/` (auto-deleted after sending)
+- **Messaging**: OpenClaw `message send` CLI
+- **Supported Platforms**: Telegram, Discord, WhatsApp, Slack, Signal, MS Teams
+
+## Project Structure
+
+```
+gfclaw/
+├── bin/
+│   └── cli.js              # npx installer (8-step setup + agent creation)
+├── skill/
+│   ├── SKILL.md             # Skill definition (copied to ~/.openclaw/skills/)
+│   ├── scripts/
+│   │   ├── gfclaw-selfie.sh  # Generation + sending script
+│   │   └── save-reference.sh # Base64 image decoder (used during onboarding)
+│   └── assets/
+│       └── gfclaw.png       # Default reference image (fallback)
+├── templates/
+│   └── soul-injection.md    # Persona template with onboarding flow
+├── package.json
+└── README.md
+```
+
+
+## Known Gotchas
+
+1. **`profile: "coding"` = no messaging tools** — Always use `"full"` profile for agents that need to send messages
+2. **`tools.allow` whitelist stacks with profile** — This can silently reduce available tools to zero. Avoid using it.
+3. **Skill injection is summary-only** — OpenClaw only injects ~200 chars from the skill into the system prompt. The full SKILL.md must be readable from the agent's workspace (copy it there).
+4. **`fs.workspaceOnly: true` blocks external reads** — The agent can't read files outside its workspace. Copy any needed docs into the workspace.
+5. **Output directory must be in the main workspace** — The `openclaw message send` CLI runs under the main agent's context, so files must be in `~/.openclaw/workspace/`.
+6. **Base64 images can be large** — During onboarding, the agent writes base64 data to a temp file then decodes it via script. This avoids command-line argument length limits.
+
+## Customization
+
+### Change the Reference Image (via Telegram)
+
+The easiest way is to send `/newphoto` to GFClaw on Telegram and send a new photo.
+
+Alternatively, replace `skill/assets/gfclaw.png` with your own image and reinstall. The Gemini model will edit this image to match selfie requests while maintaining the person's appearance.
+
+### Change the Persona (via Telegram)
+
+Send `/personality` to GFClaw on Telegram and describe the new personality you want.
+Alternatively, edit `templates/soul-injection.md` to customize the agent's backstory and behavior, then reinstall.
+
+### Change the Selfie Prompts
+
+Edit `skill/scripts/gfclaw-selfie.sh` — look for the `EDIT_PROMPT` variable to customize how mirror and direct selfie prompts are constructed.
+
+### Multi-Agent Setup
+
+The installer supports multiple agents on a single gateway. During Step 7, if you enter an agent name that doesn't exist, the installer will offer to create it with:
+- Telegram bot token (from @BotFather)
+- Telegram account binding
+- Allowed user configuration
+- Dedicated workspace directory
+
+This is useful for running a dedicated selfie agent alongside your main agent.
+
+## Upgrading from v1 (fal.ai)
+
+If you were using the previous version with fal.ai/Grok Imagine:
+
+1. Get a [Gemini API key](https://aistudio.google.com/apikey) (billing required)
+2. Run `npx gfclaw@latest` to reinstall
+3. The `FAL_KEY` is no longer needed — you can remove it from your `.env`
+
+## License
+
+MIT