240 lines
10 KiB
Markdown
240 lines
10 KiB
Markdown
# sn-image-base
|
||
|
||
该技能属于 [SenseNova-Skills](https://github.com/OpenSenseNova/SenseNova-Skills) 项目，提供图像生成、图像识别（VLM）和文本优化（LLM）的底层 API 能力。
|
||
|
||
完整行为请见 [SKILL.md](SKILL.md)。
|
||
|
||
本文档主要介绍该技能的详细配置。
|
||
|
||
概览与技能安装、使用方法请参考项目根目录下的 [README.md](../../README.md)（中文可见 [README_CN.md](../../README_CN.md)）；详细配置以本文档为准。
|
||
|
||
## 概览
|
||
|
||
该技能提供以下子命令：
|
||
|
||
- `sn-image-generate`：图像生成
|
||
- `sn-image-recognize`：图像识别（VLM）
|
||
- `sn-text-optimize`：文本优化（LLM）
|
||
|
||
支持的模型服务如下：
|
||
|
||
- 图像生成：
|
||
- [SenseNova](https://platform.sensenova.cn/)
|
||
- Nano Banana API
|
||
- OpenAI 图像生成 API（例如 GPT-Image-2）
|
||
|
||
- 文本与视觉 Chat：
|
||
- [SenseNova](https://platform.sensenova.cn/)
|
||
- 通过 Anthropic Messages API 接入的模型（例如 Claude Sonnet 4.6）
|
||
- 通过 OpenAI Chat Completion API 接入的模型（例如 GPT、Gemini/Qwen 等 OpenAI 兼容格式模型）
|
||
|
||
## 配置
|
||
|
||
### 快速开始
|
||
|
||
推荐使用 [SenseNova Token Plan](https://platform.sensenova.cn/token-plan)。
|
||
|
||
前往 <https://platform.sensenova.cn/token-plan/> 注册免费账号，并获取可用于图像生成和 chat 调用的 API Key。
|
||
|
||
将以下环境变量写入 `~/.openclaw/.env`（OpenClaw）或 `~/.hermes/.env`（Hermes）：
|
||
|
||
```ini
|
||
# 如果所有能力都走同一个网关，只需要配置这两个变量。
|
||
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](scripts/sn_image_base/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](https://platform.sensenova.cn/)。
|
||
|
||
如果所有能力走同一个网关，只需要设置 `SN_BASE_URL` 和 `SN_API_KEY`。
|
||
仅当图像生成需要不同 provider 时，再设置 `SN_IMAGE_GEN_*`。
|
||
|
||
如需使用非默认图像生成模型，请按以下步骤：
|
||
|
||
1. 设置 `SN_IMAGE_GEN_MODEL_TYPE` 为对应模型类型，可选值如下：
|
||
|
||
```ini
|
||
# （默认）用于 [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"
|
||
```
|
||
|
||
2. 设置 `SN_IMAGE_GEN_BASE_URL` 为图像生成 API 的基础 URL，例如：
|
||
|
||
```ini
|
||
# （默认）用于 [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"
|
||
```
|
||
|
||
3. 设置 `SN_IMAGE_GEN_MODEL` 为对应类型下的模型名，例如：
|
||
|
||
```ini
|
||
# （默认）用于 [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"
|
||
```
|
||
|
||
4. 如果图像生成使用不同于全局 key 的密钥，再设置 `SN_IMAGE_GEN_API_KEY`。如果 `SN_API_KEY` 已可用于图像生成，则无需设置。
|
||
|
||
```ini
|
||
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](https://platform.sensenova.cn/)。
|
||
|
||
仅当文本或视觉命令需要使用不同 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 设置，请按以下步骤：
|
||
|
||
1. 按 chat API 协议设置 `SN_CHAT_TYPE`。可选值如下：
|
||
|
||
```ini
|
||
# （默认）OpenAI 兼容 `/chat/completions` 接口（最常见）
|
||
SN_CHAT_TYPE="openai-completions"
|
||
# Anthropic Messages `/messages` 接口
|
||
SN_CHAT_TYPE="anthropic-messages"
|
||
```
|
||
|
||
2. 将 `SN_CHAT_BASE_URL` 设置为共享 chat endpoint 的基础 URL，例如：
|
||
|
||
```ini
|
||
# （默认）用于 [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/"
|
||
```
|
||
|
||
3. 设置 `SN_CHAT_MODEL`，仅在文本或视觉命令需要不同模型时再设置 `SN_TEXT_MODEL` / `SN_VISION_MODEL`：
|
||
|
||
```ini
|
||
# （默认）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. 设置 `SN_CHAT_API_KEY` 为共享 chat endpoint 的 API key，或使用全局 `SN_API_KEY`：
|
||
|
||
```ini
|
||
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`），避免在脚本或提示词中硬编码密钥。
|