Coze-Power

SKILL.md

---
name: coze-power
description: |
  Bridge your Coze bots to local machine capabilities. Coze bots run in the cloud and can't access local files, run commands, or control your machine — Coze-Power fixes that with a lightweight HTTP server + Coze-compatible OpenAPI plugin. 10-minute setup: web search, file operations, command execution, clipboard, desktop notifications, and more.
  
  Use this skill when:
  - You want your Coze bot to read/write local files
  - You need a Coze bot to execute shell commands on your machine
  - Your Coze bot should search the web and return structured results
  - You want to give Coze bots local data access (clipboard, directory listings, system info)
  - You're building a two-way bridge between Coze cloud agents and your local environment
  - You need to expose OpenClaw agent capabilities to Coze through a webhook/API
---

# Coze-Power: Bridge Coze Bots to Local Capabilities

## Overview

Coze bots are powerful, but they live in the cloud. They can't read your local files, run terminal commands, or interact directly with your machine. **Coze-Power** solves this with a lightweight HTTP server that exposes local tools through a standard OpenAPI interface that Coze plugins can consume.

### Architecture

![Coze-Power Architecture](assets/coze-power.drawio.svg)

```
┌──────────────┐     HTTPS      ┌────────────────┐      HTTP      ┌──────────────────┐
│              │  ──────────▶   │                │  ───────────▶  │                  │
│   Coze Bot   │                │  ngrok / Tunnel │               │  coze-power      │
│   (Cloud)    │  ◀──────────   │  (Public URL)   │  ◀───────────  │  Local Server    │
│              │     JSON       │                │     JSON       │  localhost:8899  │
└──────────────┘               └────────────────┘                └──────────────────┘
                                                                          │
                                                                          ▼
                                                                ┌──────────────────┐
                                                                │  Local Actions   │
                                                                │  • Read/Write    │
                                                                │  • Shell Cmds    │
                                                                │  • Web Search    │
                                                                │  • System Info   │
                                                                └──────────────────┘
```



## Quick Start (5 minutes)

### 1. Start the server

```bash
cd coze-power
python3 server.py
# Server starts on http://localhost:8899
```

### 2. Expose it publicly (one of these)

```bash
# Using ngrok (recommended for beginners)
ngrok http 8899
# → https://xxxx.ngrok.io  (copy this URL)

# Or using Cloudflare Tunnel
cloudflared tunnel --url http://localhost:8899
```

### 3. Import the Coze plugin

1. In Coze Studio, go to **Plugins → Create Plugin**
2. Import from OpenAPI → Upload `assets/openapi-spec.json`
3. Set **Server URL** to your ngrok/cloudflare URL (e.g. `https://xxxx.ngrok.io`)
4. Add API key authentication: header name `X-API-Key`, value from your `config.json`
5. Save and enable the plugin
6. Add the plugin to your Coze bot

### 4. Test it

In your Coze bot, try:
> "Search the web for latest AI news"
> "List files on my desktop"
> "Show me the current system status"

## Available Tools

| Tool | Method | Endpoint | Description |
|------|--------|----------|-------------|
| Web Search | POST | `/tools/web-search` | Search the web and return results |
| Read File | POST | `/tools/read-file` | Read content from local files |
| Write File | POST | `/tools/write-file` | Write content to local files |
| List Directory | POST | `/tools/list-dir` | List files in a directory |
| Run Command | POST | `/tools/run-command` | Execute shell commands |
| System Info | POST | `/tools/system-info` | Get OS, CPU, memory info |
| Read Clipboard | POST | `/tools/clipboard-read` | Read clipboard contents |
| Write Clipboard | POST | `/tools/clipboard-write` | Write to clipboard |
| Send Notification | POST | `/tools/notify` | Send desktop notification |
| Health Check | GET | `/health` | Check server status |

## Configuration

Create `config.json` in the skill directory:

```json
{
  "api_key": "your-secret-api-key",
  "host": "0.0.0.0",
  "port": 8899,
  "allowed_commands": ["ls", "pwd", "cat", "echo", "python3", "node"],
  "allowed_paths": ["/home", "/tmp"],
  "max_file_size_kb": 1024
}
```

## Security

⚠️ **You are exposing your local machine to the internet.** Follow these rules:

- Always use **API key authentication** (never run without it)
- Use `allowed_commands` and `allowed_paths` to restrict access
- For production: add HTTPS via ngrok (it automatically provides TLS)
- Never expose this server without authentication
- Consider running it in a Docker container for isolation

## Coze Plugin Setup (Detailed)

See `references/coze-plugin-setup.md` for step-by-step Coze configuration.

## Examples

See `references/examples.md` for real Coze bot prompts and expected behaviors.

## API Reference

See `references/api-reference.md` for complete endpoint documentation.