ephron_ren/agent-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
agent-skills/sn-image-base/README.md
Hermes Agent ccc63d1e70 first commit
2026-05-10 13:52:46 +08:00

10 KiB
Raw Permalink Blame History

sn-image-base

The skill for the SenseNova-Skills project, providing low-level APIs for image generation, recognition (VLM), and text optimization (LLM).

See SKILL.md for full behavior.

This document describes detailed configurations for the skill.

For installation and usage, please refer to the project's README.md.

Overview

The skill provides the following subcommands:

  • sn-image-generate: image generation
  • sn-image-recognize: image recognition (VLM)
  • sn-text-optimize: text optimization (LLM)

The skill supports the following models services:

  • For image generation:

    • SenseNova
    • Nano Banana API
    • OpenAI Image Generation API (e.g. GPT-Image-2)

  • For text and vision chat:

    • SenseNova
    • Models via Anthropic Messages API (e.g. Claude Sonnet 4.6)
    • Models via OpenAI Chat Completion API (e.g. GPT and Gemini/Qwen etc. in OpenAI Compatible API format)

Configurations

Quick Start

We recommend you to try out our SenseNova Token Plan.

Go to https://platform.sensenova.cn/token-plan/ to register a free account and get your API key for image generation and chat calls.

Set the following environment variables in ~/.openclaw/.env (or ~/.hermes/.env if you are using Hermes):

# If all capabilities use the same gateway, these two variables are enough.
SN_BASE_URL="https://token.sensenova.cn/v1"
SN_API_KEY="<sensenova-token-plan-api-key>"

# Optional model overrides
SN_IMAGE_GEN_MODEL="sensenova-u1-fast"   # or other image generation models available in the SenseNova Token Plan
SN_CHAT_MODEL="sensenova-6.7-flash-lite"

Detailed Configurations

With the Quick Start, you can already use this skill.

If you want to configure the skill more (i.e. use different models, change the base URL, etc.), you can see the following configurations.

Multiple sources of configuration are supported, the priority is (high to low):

  • (Recommended) ~/.openclaw/.env (for OpenClaw) or ~/.hermes/.env (for Hermes)
  • current working directory .env (not necessarily exists, depends on how the agent runs the skill)
  • process environment variables

For experienced developers, see configs.py for the full list of variables and defaults.

Helpful symbols for tracing behavior quickly:

  • prepare_env() for .env loading order
  • Field.resolve() for env-var fallback order ("first set value wins")
  • Configs for all defaults and env-name mapping

Image Generation

Environment variables are resolved as: dedicated variable > domain shared variable > global variable.

Capability API key fallback Base URL fallback
Text model SN_TEXT_API_KEY -> SN_CHAT_API_KEY -> SN_API_KEY SN_TEXT_BASE_URL -> SN_CHAT_BASE_URL -> SN_BASE_URL
Vision model SN_VISION_API_KEY -> SN_CHAT_API_KEY -> SN_API_KEY SN_VISION_BASE_URL -> SN_CHAT_BASE_URL -> SN_BASE_URL
Image generation SN_IMAGE_GEN_API_KEY -> SN_API_KEY SN_IMAGE_GEN_BASE_URL -> SN_BASE_URL

Full configuration for image generation:

Config Key Description Default
SN_API_KEY Global API key used when capability-specific keys are unset ""
SN_BASE_URL Global base URL used when capability-specific base URLs are unset ""
SN_IMAGE_GEN_API_KEY Optional image-generation-only API key override SN_API_KEY
SN_IMAGE_GEN_MODEL_TYPE The type of image generation model to use "sensenova"
SN_IMAGE_GEN_MODEL The name of the image generation model to use "sensenova-u1-fast"
SN_IMAGE_GEN_BASE_URL The base URL for the image generation API SN_BASE_URL, then "https://token.sensenova.cn/v1"

The default values are recommended for the SenseNova.

When all capabilities use one gateway, set only SN_BASE_URL and SN_API_KEY. Set SN_IMAGE_GEN_* only when image generation needs a different provider.

To use non-default image generation models, please:

  1. Set SN_IMAGE_GEN_MODEL_TYPE according to the model type, available values are:

    # (Default) For [SenseNova](https://platform.sensenova.cn/)
SN_IMAGE_GEN_MODEL_TYPE="sensenova"
# For Google's Nano Banana model API
SN_IMAGE_GEN_MODEL_TYPE="nano-banana"
# For OpenAI's image generation API
SN_IMAGE_GEN_MODEL_TYPE="openai-image"

  2. Set SN_IMAGE_GEN_BASE_URL to the base URL for the image generation API. For example:

    # (Default) For [SenseNova](https://platform.sensenova.cn/)
SN_IMAGE_GEN_BASE_URL="https://token.sensenova.cn/v1"
# For Google's Nano Banana model API
SN_IMAGE_GEN_BASE_URL="https://generativelanguage.googleapis.com"
# For OpenAI's image generation API
SN_IMAGE_GEN_BASE_URL="https://api.openai.com/v1"

  3. Set SN_IMAGE_GEN_MODEL to the model name provided by the model type. For example:

    # (Default) For [SenseNova](https://platform.sensenova.cn/)
SN_IMAGE_GEN_MODEL="sensenova-u1-fast"
# For Google's Nano Banana model API
SN_IMAGE_GEN_MODEL="gemini-3.1-flash-image-preview"
# For OpenAI's image generation API
SN_IMAGE_GEN_MODEL="gpt-image-2"

  4. If image generation uses a different key than the global key, set SN_IMAGE_GEN_API_KEY. If SN_API_KEY already works for image generation, skip this.

    SN_IMAGE_GEN_API_KEY="sk-your-image-generation-api-key"

Text and Vision Chat

Configure the shared chat runtime

Text optimization and image recognition now share one chat runtime. Configure the protocol, endpoint, API key, and default model once, then override text or vision models only when needed:

Config Keys Description Default
SN_CHAT_API_KEY API key for text and vision chat calls SN_API_KEY
SN_CHAT_BASE_URL Shared base URL for the chat API SN_BASE_URL, then "https://token.sensenova.cn/v1"
SN_CHAT_TYPE Shared chat protocol type "openai-completions"
SN_CHAT_MODEL Shared default model for text and vision chat calls "sensenova-6.7-flash-lite"
SN_TEXT_API_KEY Optional text-only provider API key SN_CHAT_API_KEY -> SN_API_KEY
SN_TEXT_BASE_URL Optional text-only provider base URL SN_CHAT_BASE_URL -> SN_BASE_URL
SN_TEXT_TYPE Optional text-only protocol type SN_CHAT_TYPE
SN_TEXT_MODEL Optional model override for sn-text-optimize SN_CHAT_MODEL
SN_VISION_API_KEY Optional vision provider API key SN_CHAT_API_KEY -> SN_API_KEY
SN_VISION_BASE_URL Optional vision provider base URL SN_CHAT_BASE_URL -> SN_BASE_URL
SN_VISION_TYPE Optional vision protocol type SN_CHAT_TYPE
SN_VISION_MODEL Optional vision-capable model override for sn-image-recognize SN_CHAT_MODEL

The default values are recommended for the SenseNova.

Configure SN_TEXT_* or SN_VISION_* only when a command needs a different provider than the shared SN_CHAT_* provider.

For chat calls, the runner also accepts host-only base URLs such as https://token.sensenova.cn: if no URL path is present, it appends the API version path before the interface endpoint. Prefer the documented versioned base URL, for example https://token.sensenova.cn/v1, for consistency with the built-in defaults.

To use non-default shared chat settings, please:

  1. Set SN_CHAT_TYPE according to the chat API protocol. Available values are:

    # (Default) OpenAI-compatible `/chat/completions` interface (most widely supported)
SN_CHAT_TYPE="openai-completions"
# Anthropic Messages `/messages` interface
SN_CHAT_TYPE="anthropic-messages"

  2. Set SN_CHAT_BASE_URL to the shared chat endpoint base URL. For example:

    # (Default) For [SenseNova](https://platform.sensenova.cn/)
SN_CHAT_BASE_URL="https://token.sensenova.cn/v1"
# For Anthropic Messages API
SN_CHAT_BASE_URL="https://api.anthropic.com/v1"
# For OpenAI's chat completion API
SN_CHAT_BASE_URL="https://api.openai.com/v1"
# For Google Gemini API (OpenAI-compatible)
SN_CHAT_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"

  3. Set SN_CHAT_MODEL, or set SN_TEXT_MODEL / SN_VISION_MODEL only when a command needs a different model:

    # (Default) SenseNova 6.7 Flash Lite
SN_CHAT_MODEL="sensenova-6.7-flash-lite"
# Anthropic Claude Sonnet 4.6
SN_VISION_MODEL="claude-sonnet-4-6"
# Google Gemini 3 Flash Preview
SN_VISION_MODEL="gemini-3-flash-preview"
# OpenAI GPT 5.5
SN_TEXT_MODEL="gpt-5.5"

  4. Set SN_CHAT_API_KEY to the API key for the shared chat endpoint, or use global SN_API_KEY.

    SN_CHAT_API_KEY="sk-your-api-key"

Troubleshooting

Missing API key

  • Symptom: errors like "required but not set", "missing api key", or request unauthorized.
  • Fix: set global SN_API_KEY when all capabilities use one key. Do not also set SN_IMAGE_GEN_API_KEY unless image generation needs a different provider or key. Use SN_CHAT_API_KEY, SN_TEXT_API_KEY, or SN_VISION_API_KEY only when chat/text/vision needs a different provider.

Wrong base URL

  • Symptom: request fails immediately, or URL validation/auth endpoint errors.
  • Fix: verify SN_BASE_URL or capability-specific base URLs are full base URLs (with scheme + host), for example https://token.sensenova.cn/v1.

Unsupported model name

  • Symptom: provider returns HTTP 404 / model-not-found / bad request.
  • Fix: ensure *_MODEL_TYPE / *_TYPE and *_MODEL are from the same provider, and that the model is available in your account.

Auth / permission errors

  • Symptom: HTTP 401/403, "permission denied", "forbidden".
  • Fix: check whether the key matches the selected provider endpoint, confirm account quotas/permissions, and retry with a known-valid model.

Security Notes

  • Never commit .env files or API keys to git.
  • If a key is leaked, rotate it immediately and update local env files.
  • Prefer local secret management (~/.openclaw/.env or ~/.hermes/.env) over hardcoding keys in scripts or prompts.
Reference in New Issue View Git Blame Copy Permalink