ephron_ren/agent-skills

Fork 0

Files

Hermes Agent ccc63d1e70 first commit

2026-05-10 13:52:46 +08:00

10 KiB

Raw Blame History

sn-image-base

该技能属于 SenseNova-Skills 项目，提供图像生成、图像识别（VLM）和文本优化（LLM）的底层 API 能力。

完整行为请见 SKILL.md。

本文档主要介绍该技能的详细配置。

概览与技能安装、使用方法请参考项目根目录下的 README.md（中文可见 README_CN.md）；详细配置以本文档为准。

概览

该技能提供以下子命令：

sn-image-generate：图像生成
sn-image-recognize：图像识别（VLM）
sn-text-optimize：文本优化（LLM）

支持的模型服务如下：

图像生成：
- SenseNova
- Nano Banana API
- OpenAI 图像生成 API（例如 GPT-Image-2）
文本与视觉 Chat：
- SenseNova
- 通过 Anthropic Messages API 接入的模型（例如 Claude Sonnet 4.6）
- 通过 OpenAI Chat Completion API 接入的模型（例如 GPT、Gemini/Qwen 等 OpenAI 兼容格式模型）

配置

快速开始

推荐使用 SenseNova Token Plan。

前往 https://platform.sensenova.cn/token-plan/ 注册免费账号，并获取可用于图像生成和 chat 调用的 API Key。

将以下环境变量写入 ~/.openclaw/.env（OpenClaw）或 ~/.hermes/.env（Hermes）：

# 如果所有能力都走同一个网关，只需要配置这两个变量。
SN_BASE_URL="https://token.sensenova.cn/v1"
SN_API_KEY="<sensenova-token-plan-api-key>"

# 可选模型覆盖
SN_IMAGE_GEN_MODEL="sensenova-u1-fast"   # 或 Token Plan 中可用的其他图像生成模型
SN_CHAT_MODEL="sensenova-6.7-flash-lite"

注意：不要将 .env 文件或 API key 提交到 git。

详细配置

完成快速开始后即可使用本技能。

若需更进一步配置（例如使用不同模型、修改 base URL 等），请参考以下内容。

支持多重配置来源，优先级（从高到低）如下：

（推荐）~/.openclaw/.env（OpenClaw）或 ~/.hermes/.env（Hermes）
当前工作目录 .env（不一定存在，取决于 agent 运行技能的方式）
进程环境变量

进阶开发者可查看 configs.py 获取完整变量与默认值。

便于快速追踪行为的关键符号：

prepare_env()：.env 加载顺序

Field.resolve()：环境变量回退顺序（“第一个已设置值优先”）

Configs：默认值与环境变量映射

图像生成

环境变量解析优先级为：专用变量 > 领域共享变量 > 全局变量。

能力	API key fallback	Base URL fallback
文本模型	`SN_TEXT_API_KEY` -> `SN_CHAT_API_KEY` -> `SN_API_KEY`	`SN_TEXT_BASE_URL` -> `SN_CHAT_BASE_URL` -> `SN_BASE_URL`
视觉模型	`SN_VISION_API_KEY` -> `SN_CHAT_API_KEY` -> `SN_API_KEY`	`SN_VISION_BASE_URL` -> `SN_CHAT_BASE_URL` -> `SN_BASE_URL`
图像生成	`SN_IMAGE_GEN_API_KEY` -> `SN_API_KEY`	`SN_IMAGE_GEN_BASE_URL` -> `SN_BASE_URL`

图像生成完整配置如下：

配置键	说明	默认值
`SN_API_KEY`	所有能力共用的全局 API Key	`""`
`SN_BASE_URL`	所有能力共用的全局基础 URL	`""`
`SN_IMAGE_GEN_API_KEY`	可选的图像生成专用 API key 覆盖	`SN_API_KEY`
`SN_IMAGE_GEN_MODEL_TYPE`	图像生成模型类型	`"sensenova"`
`SN_IMAGE_GEN_MODEL`	图像生成模型名	`"sensenova-u1-fast"`
`SN_IMAGE_GEN_BASE_URL`	图像生成 API 的基础 URL	`SN_BASE_URL`，然后 `"https://token.sensenova.cn/v1"`

默认值适用于 SenseNova。

如果所有能力走同一个网关，只需要设置 SN_BASE_URL 和 SN_API_KEY。仅当图像生成需要不同 provider 时，再设置 SN_IMAGE_GEN_*。

如需使用非默认图像生成模型，请按以下步骤：

设置 SN_IMAGE_GEN_MODEL_TYPE 为对应模型类型，可选值如下：

# （默认）用于 [SenseNova](https://platform.sensenova.cn/)
SN_IMAGE_GEN_MODEL_TYPE="sensenova"
# 用于 Google Nano Banana 模型 API
SN_IMAGE_GEN_MODEL_TYPE="nano-banana"
# 用于 OpenAI 图像生成 API
SN_IMAGE_GEN_MODEL_TYPE="openai-image"

设置 SN_IMAGE_GEN_BASE_URL 为图像生成 API 的基础 URL，例如：

# （默认）用于 [SenseNova](https://platform.sensenova.cn/)
SN_IMAGE_GEN_BASE_URL="https://token.sensenova.cn/v1"
# 用于 Google Nano Banana 模型 API
SN_IMAGE_GEN_BASE_URL="https://generativelanguage.googleapis.com"
# 用于 OpenAI 图像生成 API
SN_IMAGE_GEN_BASE_URL="https://api.openai.com/v1"

设置 SN_IMAGE_GEN_MODEL 为对应类型下的模型名，例如：

# （默认）用于 [SenseNova](https://platform.sensenova.cn/)
SN_IMAGE_GEN_MODEL="sensenova-u1-fast"
# 用于 Google Nano Banana 模型 API
SN_IMAGE_GEN_MODEL="gemini-3.1-flash-image-preview"
# 用于 OpenAI 图像生成 API
SN_IMAGE_GEN_MODEL="gpt-image-2"

如果图像生成使用不同于全局 key 的密钥，再设置 SN_IMAGE_GEN_API_KEY。如果 SN_API_KEY 已可用于图像生成，则无需设置。
```
SN_IMAGE_GEN_API_KEY="sk-your-image-generation-api-key"
```

文本与视觉 Chat

配置共享 Chat Runtime

文本优化和图像识别现在共享一套 chat runtime。协议、endpoint、API key 与默认模型配置一次，仅在需要时分别覆盖文本或视觉模型：

配置键	说明	默认值
`SN_CHAT_API_KEY`	text/vision chat 调用共用 API key	`SN_API_KEY`
`SN_CHAT_BASE_URL`	共享 Chat API 基础 URL	`SN_BASE_URL`，然后 `"https://token.sensenova.cn/v1"`
`SN_CHAT_TYPE`	共享 Chat 协议类型	`"openai-completions"`
`SN_CHAT_MODEL`	text/vision chat 调用共用默认模型	`"sensenova-6.7-flash-lite"`
`SN_TEXT_API_KEY`	可选文本 provider API key	`SN_CHAT_API_KEY` -> `SN_API_KEY`
`SN_TEXT_BASE_URL`	可选文本 provider 基础 URL	`SN_CHAT_BASE_URL` -> `SN_BASE_URL`
`SN_TEXT_TYPE`	可选文本协议类型	`SN_CHAT_TYPE`
`SN_TEXT_MODEL`	可选的 `sn-text-optimize` 模型覆盖	`SN_CHAT_MODEL`
`SN_VISION_API_KEY`	可选视觉 provider API key	`SN_CHAT_API_KEY` -> `SN_API_KEY`
`SN_VISION_BASE_URL`	可选视觉 provider 基础 URL	`SN_CHAT_BASE_URL` -> `SN_BASE_URL`
`SN_VISION_TYPE`	可选视觉协议类型	`SN_CHAT_TYPE`
`SN_VISION_MODEL`	可选的 `sn-image-recognize` 视觉模型覆盖	`SN_CHAT_MODEL`

默认值适用于 SenseNova。

仅当文本或视觉命令需要使用不同 provider 时，才需要配置 SN_TEXT_* 或 SN_VISION_*。

对于 chat 调用，runner 也兼容不带路径的 host-only base URL，例如 https://token.sensenova.cn：如果 URL 中没有 path，会先补上 API 版本路径再追加具体接口。为保持和内置默认值一致，建议优先使用带版本路径的 base URL，例如 https://token.sensenova.cn/v1。

如需使用非默认 chat 设置，请按以下步骤：

按 chat API 协议设置 SN_CHAT_TYPE。可选值如下：

# （默认）OpenAI 兼容 `/chat/completions` 接口（最常见）
SN_CHAT_TYPE="openai-completions"
# Anthropic Messages `/messages` 接口
SN_CHAT_TYPE="anthropic-messages"

将 SN_CHAT_BASE_URL 设置为共享 chat endpoint 的基础 URL，例如：

# （默认）用于 [SenseNova](https://platform.sensenova.cn/)
SN_CHAT_BASE_URL="https://token.sensenova.cn/v1"
# 用于 Anthropic Messages API
SN_CHAT_BASE_URL="https://api.anthropic.com/v1"
# 用于 OpenAI Chat Completion API
SN_CHAT_BASE_URL="https://api.openai.com/v1"
# 用于 Google Gemini API（OpenAI 兼容）
SN_CHAT_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"

设置 SN_CHAT_MODEL，仅在文本或视觉命令需要不同模型时再设置 SN_TEXT_MODEL / SN_VISION_MODEL：

# （默认）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"

设置 SN_CHAT_API_KEY 为共享 chat endpoint 的 API key，或使用全局 SN_API_KEY：
```
SN_CHAT_API_KEY="sk-your-api-key"
```

故障排查

缺少 API key

现象：报错包含 "required but not set"、"missing api key" 或请求未授权。
处理：如果所有能力使用同一个 key，设置全局 SN_API_KEY 即可。不要重复设置 SN_IMAGE_GEN_API_KEY，除非图像生成需要不同 provider 或 key；仅当 chat/text/vision 需要不同 provider 时，再设置 SN_CHAT_API_KEY、SN_TEXT_API_KEY 或 SN_VISION_API_KEY。

base URL 配置错误

现象：请求立即失败，或出现 URL 校验 / endpoint 相关错误。
处理：检查 SN_BASE_URL 或能力专用 base URL 是否为完整基础 URL（包含 scheme + host），例如 https://token.sensenova.cn/v1。

模型名不支持

现象：provider 返回 HTTP 404 / model-not-found / bad request。
处理：确认 *_MODEL_TYPE / *_TYPE 与 *_MODEL 来自同一 provider，且模型在当前账号下可用。

鉴权 / 权限错误

现象：HTTP 401/403、"permission denied"、"forbidden"。
处理：确认密钥与所选 provider endpoint 匹配，检查账号配额/权限，并使用已知可用模型重试。

安全说明

不要将 .env 文件或 API key 提交到 git。
若密钥泄露，请立即轮换并更新本地环境变量文件。
优先使用本地密钥管理（~/.openclaw/.env 或 ~/.hermes/.env），避免在脚本或提示词中硬编码密钥。

10 KiB Raw Blame History Unescape Escape