Coze

Name: Coze
Rating: 3.5 (1 reviews)
Author: yesgit

By yesgit 👁 10 views ▲ 0 votes

OpenClaw plugin for integrating with Coze workflow bots via Chat V3 API

GitHub

Install

npm install openclaw-coze-plugin

Configuration Example

# openclaw.yaml
plugins:
  - id: openclaw-coze-plugin
    config:
      # apiKey and botId will be read from OPENCLAW_COZE_API_KEY and OPENCLAW_COZE_BOT_ID
      allowedUsers:
        - "user123"
        - "user456"
      workflowParams:
        current_page: "首页"
        predefined: false
        is_guide_question: false

README

# OpenClaw Coze Workflow Plugin

This plugin integrates OpenClaw with Coze workflow bots using the Chat V3 API.

## Features

- **Message Interception**: Automatically intercept messages from specific users
- **Streaming Responses**: Real-time streaming of Coze workflow responses
- **Workflow Parameters**: Support for custom workflow-defined parameters
- **Session Persistence**: Maintains conversation context across messages
- **Custom Tool**: Agents can query Coze workflow with custom parameters
- **Scheduled Tasks**: Support for cron-based proactive messaging

## Installation

```bash
npm install openclaw-coze-plugin
```

## Configuration

### Option 1: Using Environment Variables (Recommended for Security)

Set sensitive values as environment variables:

```bash
export OPENCLAW_COZE_API_KEY="pat_your_api_key"
export OPENCLAW_COZE_BOT_ID="your_bot_id"
export OPENCLAW_COZE_USER_TOKEN="your_user_token"  # Optional
```

Then configure the plugin:

```yaml
# openclaw.yaml
plugins:
  - id: openclaw-coze-plugin
    config:
      # apiKey and botId will be read from OPENCLAW_COZE_API_KEY and OPENCLAW_COZE_BOT_ID
      allowedUsers:
        - "user123"
        - "user456"
      workflowParams:
        current_page: "首页"
        predefined: false
        is_guide_question: false
```

### Option 2: Direct Configuration

Add the plugin to your OpenClaw configuration:

```yaml
plugins:
  - id: openclaw-coze-plugin
    config:
      apiKey: "your_coze_api_key"
      botId: "your_bot_id"
      baseUrl: "https://api.coze.cn"  # Optional, default value
      allowedUsers:                    # Optional, leave empty for all users
        - "user123"
        - "user456"
      userToken: "fixed_user_token"    # Optional, for testing (experimental)
      workflowParams:                  # Optional, default workflow parameters
        current_page: "首页"
        predefined: false
        is_guide_question: false
```

### Priority

Configuration values take priority over environment variables. If you set both, the config value will be used.

## Parameter Mapping

### Standard Chat V3 API Parameters
These are automatically handled by the plugin:
- `bot_id`: From configuration
- `user_id`: From OpenClaw message context
- `conversation_id`: Maintained across sessions
- `additional_messages`: User message content
- `stream`: Always enabled for real-time responses

### Workflow-Defined Parameters
These are passed via `extra_params` to your Coze workflow:

| Parameter | Type | Default | Source |
|-----------|------|---------|--------|
| `current_page` | String | `"首页"` | Config → Dynamic |
| `page_data` | String (JSON) | `"{}"` | Dynamic (or default) |
| `user_token` | String | From `userToken` config | Config → Dynamic |
| `predefined` | Boolean | `false` | Config → Dynamic |
| `is_guide_question` | Boolean | `false` | Config → Dynamic |

**Priority**: Dynamic parameters > Config defaults > Hardcoded defaults

## Usage

### Automatic Message Handling
Once configured, the plugin automatically:
1. Intercepts messages from allowed users
2. Forwards them to your Coze workflow
3. Streams the response back to the user

### Custom Tool
Agents can call the `coze_workflow_query` tool:

```javascript
{
  "tool": "coze_workflow_query",
  "parameters": {
    "query": "What's the weather today?",
    "current_page": "weather_page",
    "page_data": "{\"location\": \"Beijing\"}"
  }
}
```

### Scheduled Tasks
Configure cron tasks in OpenClaw to send proactive messages:

```yaml
cron:
  - name: "daily-reminder"
    schedule: "0 9 * * *"
    task: "send-reminder"
    plugin: "coze-workflow-integration"
```

## Building

```bash
npm run build
```

## Distribution

The plugin can be distributed as an npm package for deployment to other OpenClaw instances.

integration