1. OpenClaw StepFun 插件概述
OpenClaw StepFun 插件是 OpenClaw 生态中的官方扩展组件,主要用于对接 StepFun 平台提供的 AI 模型服务。这个插件实际上包含两个独立的 provider(服务提供者):
- 标准端点(stepfun)
- Step Plan 端点(stepfun-plan)
这两个 provider 使用不同的 API 端点,模型引用前缀也不同(stepfun/... vs stepfun-plan/...)。在实际使用中,需要特别注意中国区(.com)和国际区(.ai)的域名区别,以及对应的 API key 使用规则。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 插件安装与基础配置
2.1 安装步骤
安装 OpenClaw StepFun 插件非常简单,只需执行以下命令:
bash复制openclaw plugins install @openclaw/stepfun-provider
openclaw gateway restart
安装完成后需要重启网关服务使插件生效。这里有几个需要注意的点:
- 确保你的 OpenClaw 版本是最新的
- 安装过程需要网络连接
- 如果遇到权限问题,可能需要使用 sudo
2.2 区域与端点配置
StepFun 服务根据用户所在区域提供了不同的访问端点:
| 端点类型 | 中国区(.com) | 国际区(.ai) |
|---|---|---|
| 标准端点 | https://api.stepfun.com/v1 | https://api.stepfun.ai/v1 |
| Step Plan端点 | https://api.stepfun.com/step_plan/v1 | https://api.stepfun.ai/step_plan/v1 |
选择正确的端点非常重要,否则可能会导致连接失败或性能下降。一般来说:
- 中国大陆用户应使用 .com 域名
- 海外用户应使用 .ai 域名
3. 模型与功能详解
3.1 内置模型目录
StepFun 插件提供了多个预配置的模型:
标准端点模型(stepfun):
- stepfun/step-3.5-flash:默认标准模型,支持262,144 tokens上下文,最大输出65,536 tokens
- stepfun/step-3.7-flash:增强版模型,支持图像输入,最大输出262,144 tokens
Step Plan端点模型(stepfun-plan):
- stepfun-plan/step-3.5-flash:默认Step Plan模型
- stepfun-plan/step-3.7-flash:支持图像输入的Step Plan模型
- stepfun-plan/step-3.5-flash-2603:特殊版本Step Plan模型
3.2 模型特性对比
| 特性 | step-3.5-flash | step-3.7-flash |
|---|---|---|
| 上下文长度 | 262k | 262k |
| 最大输出 | 65k | 262k |
| 多模态支持 | 仅文本 | 文本+图像 |
| 推理能力 | 基础 | 增强 |
| 适用场景 | 常规任务 | 复杂任务 |
4. 快速入门指南
4.1 标准端点配置
对于大多数常规用途,建议使用标准端点:
bash复制# 国际区配置
openclaw onboard --auth-choice stepfun-standard-api-key-intl
# 中国区配置
openclaw onboard --auth-choice stepfun-standard-api-key-cn
配置完成后,可以通过以下命令验证模型是否可用:
bash复制openclaw models list --provider stepfun
4.2 Step Plan端点配置
Step Plan 端点更适合需要复杂推理的任务:
bash复制# 国际区配置
openclaw onboard --auth-choice stepfun-plan-api-key-intl
# 中国区配置
openclaw onboard --auth-choice stepfun-plan-api-key-cn
验证命令:
bash复制openclaw models list --provider stepfun-plan
5. 高级配置选项
5.1 标准端点完整配置
json5复制{
env: { STEPFUN_API_KEY: "your-key" },
agents: { defaults: { model: { primary: "stepfun/step-3.5-flash" } } },
models: {
mode: "merge",
providers: {
stepfun: {
baseUrl: "https://api.stepfun.ai/v1",
api: "openai-completions",
apiKey: "${STEPFUN_API_KEY}",
models: [
{
id: "step-3.7-flash",
name: "Step 3.7 Flash",
reasoning: true,
input: ["text", "image"],
thinkingLevelMap: { off: "low", minimal: "low", xhigh: "high", max: "high" },
cost: { input: 0.2, output: 1.15, cacheRead: 0.04, cacheWrite: 0 },
contextWindow: 262144,
maxTokens: 262144,
compat: {
supportsStore: false,
supportsDeveloperRole: false,
supportsUsageInStreaming: false,
supportsReasoningEffort: true,
supportsStrictMode: false,
supportedReasoningEfforts: ["low", "medium", "high"],
maxTokensField: "max_tokens",
reasoningEffortMap: {
off: "low",
none: "low",
minimal: "low",
low: "low",
medium: "medium",
high: "high",
xhigh: "high",
adaptive: "high",
max: "high",
},
},
},
{
id: "step-3.5-flash",
name: "Step 3.5 Flash",
reasoning: true,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 262144,
maxTokens: 65536,
},
],
},
},
},
}
5.2 Step Plan端点完整配置
json5复制{
env: { STEPFUN_API_KEY: "your-key" },
agents: { defaults: { model: { primary: "stepfun-plan/step-3.5-flash" } } },
models: {
mode: "merge",
providers: {
"stepfun-plan": {
baseUrl: "https://api.stepfun.ai/step_plan/v1",
api: "openai-completions",
apiKey: "${STEPFUN_API_KEY}",
models: [
{
id: "step-3.7-flash",
name: "Step 3.7 Flash",
reasoning: true,
input: ["text", "image"],
thinkingLevelMap: { off: "low", minimal: "low", xhigh: "high", max: "high" },
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 262144,
maxTokens: 262144,
compat: {
supportsStore: false,
supportsDeveloperRole: false,
supportsUsageInStreaming: false,
supportsReasoningEffort: true,
supportsStrictMode: false,
supportedReasoningEfforts: ["low", "medium", "high"],
maxTokensField: "max_tokens",
reasoningEffortMap: {
off: "low",
none: "low",
minimal: "low",
low: "low",
medium: "medium",
high: "high",
xhigh: "high",
adaptive: "high",
max: "high",
},
},
},
{
id: "step-3.5-flash",
name: "Step 3.5 Flash",
reasoning: true,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 262144,
maxTokens: 65536,
},
{
id: "step-3.5-flash-2603",
name: "Step 3.5 Flash 2603",
reasoning: true,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 262144,
maxTokens: 65536,
},
],
},
},
},
}
6. 使用技巧与最佳实践
6.1 模型选择建议
- 对于常规文本处理任务,使用 step-3.5-flash 即可
- 需要处理图像或多模态任务时,选择 step-3.7-flash
- 复杂推理任务建议使用 Step Plan 端点的模型
- 长文本生成任务优先考虑 step-3.7-flash(支持更大输出)
6.2 性能优化
- 合理设置 max_tokens 参数,避免不必要的计算
- 对于重复性任务,启用缓存可以显著提高响应速度
- 根据任务复杂度选择合适的 reasoning effort 级别
- 批量处理任务时,考虑使用异步接口
6.3 常见问题排查
- 认证失败:检查 API key 是否正确,确保使用了对应区域的 key
- 模型不可用:运行 openclaw models list 确认模型是否加载成功
- 响应慢:尝试切换到地理位置上更近的端点
- 输出截断:检查是否设置了足够的 max_tokens
7. 进阶功能探索
7.1 多模态输入处理
step-3.7-flash 支持图像输入,可以通过 OpenClaw 的特定接口传递图像数据。需要注意的是:
- 图像需要先进行 base64 编码
- 单次请求的图像大小有限制
- 图像处理会消耗更多 tokens
7.2 自定义推理级别
StepFun 模型支持通过 thinkingLevelMap 配置不同的推理级别:
- low:快速响应,适合简单任务
- medium:平衡模式
- high:深度推理,适合复杂问题
7.3 模型切换与管理
OpenClaw 提供了便捷的模型管理命令:
bash复制# 列出所有可用模型
openclaw models list
# 切换当前使用的模型
openclaw models set stepfun/step-3.7-flash
# 查看模型详情
openclaw models info stepfun-plan/step-3.5-flash-2603
8. 安全与监控
8.1 API 密钥管理
- 建议通过环境变量传递 API key 而不是硬编码在配置中
- 定期轮换 API key
- 在 StepFun 平台设置适当的用量限制
8.2 使用监控
- 关注 OpenClaw 的日志输出
- 可以在 StepFun 平台查看使用统计
- 设置用量告警
8.3 错误处理
- 实现适当的重试机制
- 对不同的错误代码采取不同的处理策略
- 考虑实现降级方案
9. 集成与扩展
9.1 与其他插件配合使用
StepFun 插件可以与其他 OpenClaw 插件协同工作,例如:
- 与存储插件配合实现结果缓存
- 与转换插件配合进行数据预处理
- 与监控插件配合实现使用统计
9.2 自定义扩展
高级用户可以基于 StepFun 插件进行二次开发:
- 扩展新的模型配置
- 添加自定义预处理逻辑
- 实现特殊的后处理流程
10. 版本升级与维护
10.1 插件升级
bash复制openclaw plugins update @openclaw/stepfun-provider
openclaw gateway restart
升级注意事项:
- 查看变更日志了解兼容性变化
- 测试环境先验证
- 考虑备份当前配置
10.2 故障恢复
- 遇到严重问题时可以回退到旧版本
- 检查 OpenClaw 官方文档获取最新解决方案
- 在社区论坛寻求帮助
