npm package: @ontos-ai/snapfill-claw
Description: SnapFill tools for OpenClaw
Latest version: 0.2.2

# SnapFill OpenClaw Plugin

SnapFill plugin for OpenClaw. It registers `snapfill_*` tools and ships a default `snapfill` skill so users can complete form filling in one conversation flow.

This package follows the current OpenClaw plugin packaging pattern:

- plugin entry is the built artifact `dist/index.js`
- package metadata exports the built plugin entry
- runtime config resolution prefers the plugin-scoped runtime config object exposed by OpenClaw, with compatibility fallbacks for older getter-style runtimes

## Who This Is For

- OpenClaw users who want to install SnapFill as a plugin
- Operators who manage plugin config for teams

## What This Plugin Provides

- Tool layer: `snapfill_*` tools that call SnapFill Facade API (`/v1/fill-jobs`)
- Skill layer: built-in `skills/snapfill/SKILL.md` with orchestration rules
- Error normalization: user-friendly errors for common backend codes

Tool list:

- `snapfill_prepare_file`
- `snapfill_list_knowledge_files`
- `snapfill_list_profiles`
- `snapfill_ingest_instant_knowledge`
- `snapfill_submit_job`
- `snapfill_get_job_status`
- `snapfill_finalize_job`
- `snapfill_get_job_result`

## Prerequisites

- A running OpenClaw instance with plugin support
- Valid SnapFill API key (`sfk_...`) from https://www.gosnapfill.com/home/api-key

## Install

### Production (npm)

```bash
openclaw plugins install @ontos-ai/snapfill-claw
```

### Local path (development)

```bash
npm run build
openclaw plugins install /absolute/path/to/openclaw-plugin
```

Then enable plugin explicitly (safe even if already enabled by default):

```bash
openclaw plugins enable snapfill-claw
```

## Configure

Configure `plugins.entries.snapfill-claw.config` in `~/.openclaw/openclaw.json`:

```json
{
  "plugins": {
    "entries": {
      "snapfill-claw": {
        "enabled": true,
        "config": {
          "apiKey": "sfk_xxx",
          "timeoutSeconds": 300,
          "pollIntervalMs": 1000,
          "maxPollAttempts": 100,
          "kbPollTimeoutSeconds": 60
        }
      }
    }
  }
}
```

`apiKey` is recommended but no longer required at install time. You can install and enable the plugin first, then set the API key later.

For more responsive progress updates, keep `pollIntervalMs` around `1000`. Lower values can increase API traffic.

If the plugin is installed but `apiKey` is still empty, open https://www.gosnapfill.com/home/api-key to create or copy your API key first.

If you are upgrading from older releases that used plugin id `snapfill`, move your config from `plugins.entries.snapfill` to `plugins.entries.snapfill-claw`. The runtime still reads the old config keys as a fallback, but OpenClaw CLI and config validation should now target `snapfill-claw`.

## Verify Installation

```bash
openclaw plugins list
openclaw plugins info snapfill-claw
openclaw plugins doctor
```

Expected result:

- `snapfill-claw` plugin is enabled
- config schema validation passes
- `snapfill_*` tools are available in agent sessions

## Quick Usage

Ask OpenClaw with natural language, for example:

- `Help me fill this application form using my existing profile.`
- `帮我填这个申请表，如果资料不够就从历史对话提取。`

The built-in skill enforces:

- knowledge-source check
- field confirmation before finalize
- result link return after job success

## Skill Packaging and Override

This plugin uses integrated delivery (plugin + skill in one package):

- skill path: `skills/snapfill/SKILL.md`
- manifest field: `openclaw.plugin.json -> skills`

OpenClaw precedence still applies:

- workspace skills (`<workspace>/skills`) override managed/global skills
- managed/global skills (`~/.openclaw/skills`) override bundled/plugin skills

## Troubleshooting

- `config.apiKey is required`
  - Get your API key from https://www.gosnapfill.com/home/api-key, then set `plugins.entries.snapfill-claw.config.apiKey`.
- `KNOWLEDGE_SOURCE_REQUIRED`
  - Upload knowledge files first, or allow instant knowledge ingestion from conversation history.
- Plugin installs but tools are missing
  - Confirm plugin is enabled and restart/refresh the OpenClaw Gateway session.

## Development

```bash
npm install
npm run check
```

This repository is only the OpenClaw integration layer (TypeScript/Node.js). The Python backend remains a separate service repository.