跳转到主要内容
适用范围：本文聚焦于如何在 OpenClaw 中配置和使用 StepFun 的 step-3.5-flash-2603 或 step-3.5-flash 模型。关于 OpenClaw 的其他功能（Skills、Channels、Multi-Agent 等），请参阅 OpenClaw 官方文档。

​
接入教学视频

​
第一步：订阅 Step Plan 并获取 API Key

在配置 OpenClaw 之前，你需要完成两件事：订阅 Step Plan 和 获取 API Key。

​
1.1 订阅 Step Plan

Step Plan 是阶跃星辰为 AI 编码 Agent 场景提供的专属服务计划。你需要先完成订阅，才能通过对应的 API 端点使用 step-3.5-flash-2603 或 step-3.5-flash 模型。 访问以下页面完成订阅： Step Plan 订阅

​
1.2 获取 API Key

  1. 访问阶跃星辰开放平台 platform.stepfun.com。
  2. 注册并登录账号（如已在订阅 Step Plan 时完成，可跳过）。
  3. 在控制台中找到 接口密钥（API Keys）管理页面，创建一个新的 API Key。
  4. 将生成的 Key 复制并妥善保管。

​
第二步：安装 OpenClaw

如果你尚未安装 OpenClaw，请先完成安装。

​
系统要求

项目最低要求推荐
Node.jsv22+v24
内存2 GB4 GB+
磁盘空间1 GB5 GB+
操作系统macOS / Linux / Windows (WSL2)—

​
macOS / Linux

打开终端，执行一键安装脚本： 
curl -fsSL https://openclaw.ai/install.sh | bash
该脚本会自动检测系统环境、安装所需依赖（包括 Node.js），并启动 Onboarding 引导。 也可以通过 npm 手动安装： 
npm install -g openclaw@latest
openclaw onboard --install-daemon

​
Windows

OpenClaw 在 Windows 上需要通过 WSL2（Windows Subsystem for Linux）运行。原生 Windows 环境因路径差异和工具链兼容性问题，不推荐直接使用。 1. 安装 WSL2（如已安装可跳过） 以管理员身份打开 PowerShell，执行： 
wsl --install
这将启用 WSL2 并安装默认的 Ubuntu 发行版。安装完成后重启计算机。 如需指定版本（如 Ubuntu 24.04）： 
wsl --install -d Ubuntu-24.04
2. 配置 systemd（OpenClaw Gateway 需要） 在 WSL 终端中执行： 
sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF
然后在 PowerShell 中执行 wsl --shutdown，再重新打开 Ubuntu 终端。 验证 systemd 是否正常： 
systemctl --user status
3. 在 WSL 中安装 OpenClaw 后续步骤与 macOS/Linux 一致，在 WSL 的 Ubuntu 终端中执行安装脚本即可： 
curl -fsSL https://openclaw.ai/install.sh | bash
Windows 用户注意事项：
  • Node.js 应安装在 WSL 内部，而非 Windows 本体，避免混合环境导致的问题。
  • OpenClaw 的工作目录应保留在 WSL 文件系统中（如 ~/），而非放在 /mnt/c/ 下，否则 I/O 性能会显著下降。

​
第三步：配置 <model_id> 模型

这是本文的核心部分。OpenClaw 通过 models.providers 配置节点支持自定义模型提供商。你有两种配置方式：CLI 引导方式和手动编辑配置文件方式。
说明：本文示例中的 <model_id> 可填写为 step-3.5-flash-2603 或 step-3.5-flash。 重要说明：无论使用哪种方式，最终都需要编辑配置文件来确保模型参数正确。CLI 引导方式可以快速完成基础配置（Provider、API Key 等），但它为自定义模型生成的默认参数（如 contextWindow 仅 16K）低于本文示例使用的推荐配置（256000），需要手动修正。

​
方式一：通过 Onboarding CLI + 手动修正

如果你是首次安装或希望重新运行引导流程： 
openclaw onboard
在引导过程中：
  1. 当提示选择模型提供商时，选择 “Custom Provider”。
  2. API 兼容模式选择 openai-completions（StepFun API 兼容 OpenAI 格式）。
  3. 填入 Base URL：https://api.stepfun.com/step_plan/v1
  4. 填入你在第一步获取的 API Key。
  5. Model ID 填写：<model_id>
完成 CLI 引导后，必须手动修正模型参数。 打开 ~/.openclaw/openclaw.json，找到 CLI 自动生成的 stepfun Provider 配置，将 models 数组中的参数调整为： 
"models": [
  {
    "id": "<model_id>",  // 可填写 step-3.5-flash-2603 或 step-3.5-flash
    "name": "<model_id>",
    "reasoning": true,
    "contextWindow": 256000,  // CLI 默认生成 16384，必须改为 256000
    "maxTokens": 8192
  }
]
如果不做此修正，OpenClaw 会按照 16K 的上下文窗口来截断输入，导致模型无法处理较长的代码文件或对话历史。

​
方式二：手动编辑配置文件（推荐高级用户）

OpenClaw 的配置文件位于 ~/.openclaw/openclaw.json。 使用你喜欢的编辑器打开它，在文件中添加或修改以下内容： 
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "stepfun/<model_id>" // <model_id> 可填写 step-3.5-flash-2603 或 step-3.5-flash
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "stepfun": {
        "baseUrl": "https://api.stepfun.com/step_plan/v1",
        "apiKey": "${STEP_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "<model_id>",
            "name": "<model_id>",
            "reasoning": true,
            "contextWindow": 256000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}
配置字段说明：
字段说明
agents.defaults.model.primary将 stepfun/<model_id> 设为默认主模型，格式为 provider/model
models.mode设置为 "merge" 表示自定义 Provider 与内置 Provider 合并，而非覆盖
models.providers.stepfunProvider 的标识符，可自行命名，但建议使用有意义的名称
baseUrlStep Plan API 端点：https://api.stepfun.com/step_plan/v1
apiKeyAPI Key。这里使用 ${STEP_API_KEY} 引用环境变量（推荐做法），也可直接填写 Key 字符串
api设为 "openai-completions"，表示使用 OpenAI 兼容的 Chat Completions 格式
models[].id填写 StepFun API 要求的模型 ID：<model_id>
models[].name模型的显示名称，仅用于 OpenClaw 界面展示
models[].reasoning设为 true 表示该模型支持思维链/推理模式
models[].contextWindow模型支持的最大输入 token 数。本文示例统一使用 256000，请与所选 <model_id> 的能力保持一致
models[].maxTokens模型单次最大输出 token 数。根据实际需求设置，默认 8192 即可
关于默认值：如果你省略 reasoning、contextWindow、maxTokens 等字段，OpenClaw 会使用以下默认值：
  • reasoning: false
  • contextWindow: 200000
  • maxTokens: 8192
但建议显式设置这些值，以获得最佳体验。
提示：如果你在其他地方看到如下格式的配置示例，请勿使用，这不是 OpenClaw 的配置格式： 
{
  "provider": "stepfun",
  "base_url": "https://api.stepfun.com/step_plan/v1",
  "api": "/chat/completions",
  "api_key": "sk-..."
}
这种格式与 OpenClaw 的 openclaw.json 结构不兼容，字段名（如 base_url、api_key）和 api 字段的值均有差异，配置后将无法正常运行。建议以本文”方式二”中的完整示例为准。

​
第四步：设置环境变量（推荐）

如果你在配置文件中使用了 ${STEP_API_KEY} 引用环境变量（推荐做法，避免将敏感信息硬编码在配置文件中），你需要在系统中设置该环境变量。

​
macOS / Linux（Bash / Zsh）

将以下行添加到你的 Shell 配置文件中：
  • Zsh（macOS 默认）：编辑 ~/.zshrc
  • Bash：编辑 ~/.bashrc 或 ~/.bash_profile
export STEP_API_KEY="你的API Key"
保存后让配置生效： 
# Zsh
source ~/.zshrc

# Bash
source ~/.bashrc

​
Windows (WSL2)

与 Linux 一致，在 WSL 的 Ubuntu 终端中编辑 ~/.bashrc： 
echo 'export STEP_API_KEY="你的API Key"' >> ~/.bashrc
source ~/.bashrc
安全提示：不要将 API Key 提交到版本控制系统中。如果你的 openclaw.json 纳入版本管理，务必使用环境变量方式引用 Key。

​
第五步：验证配置

配置完成后，通过以下步骤验证一切是否正常工作。

​
检查 Gateway 状态

openclaw gateway status
确保 Gateway 正在运行（默认监听端口 18789）。

​
列出可用模型

openclaw models list
在输出中确认 stepfun/<model_id> 出现在模型列表中。

​
切换到 <model_id> 模型

如果你没有将其设为默认模型，也可以通过 CLI 快速切换： 
openclaw models set stepfun/<model_id>
或者在 OpenClaw 对话中使用 /model 命令来切换。

​
发送一条测试消息

在 OpenClaw 的对话界面中发送任意消息，确认模型能正常响应。如果出现错误，请检查：
  1. API Key 是否正确
  2. baseUrl 是否与你获取 Key 的平台一致
  3. 环境变量是否已正确加载（可通过 echo $STEP_API_KEY 验证）
  4. 网络是否能正常访问 api.stepfun.com

​
常见问题

​
Q: 配置后提示 “Model is not allowed”

如果你设置了 agents.defaults.models（模型允许列表），需要确保 stepfun/<model_id> 也被加入到该列表中，否则模型会被拦截。解决方法： 
{
  "agents": {
    "defaults": {
      "models": {
        "stepfun/<model_id>": {
          "alias": "Step Model"
        }
      }
    }
  }
}
或者直接移除 agents.defaults.models 配置项以取消白名单限制。

​
Q: api 字段为什么选 openai-completions？

StepFun API 完整兼容 OpenAI 的 Chat Completions 请求格式。OpenClaw 在配置自定义 Provider 时支持两种 API 类型：
  • openai-completions：适用于兼容 OpenAI 格式的提供商（绝大多数第三方提供商）
  • anthropic-messages：适用于兼容 Anthropic Messages 格式的提供商
StepFun 属于前者。

​
Q: Windows 上可以不用 WSL2 吗？

不推荐。OpenClaw 依赖 Linux 工具链（make、g++ 等）和 systemd 服务管理，原生 Windows 环境会遇到诸多兼容性问题。WSL2 是官方推荐的 Windows 使用方式。

​
参考链接