OpenClaw 接入指南

适用范围：本文聚焦于如何在 OpenClaw 中配置和使用 StepFun 的 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 模型。

访问以下页面完成订阅：

platform.stepfun.com/step-plan

1.2 获取 API Key

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

第二步：安装 OpenClaw

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

系统要求

项目	最低要求	推荐
Node.js	v22+	v24
内存	2 GB	4 GB+
磁盘空间	1 GB	5 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 性能会显著下降。

第三步：配置 step-3.5-flash 模型

这是本文的核心部分。OpenClaw 通过 models.providers 配置节点支持自定义模型提供商。你有两种配置方式：CLI 引导方式和手动编辑配置文件方式。

重要说明：无论使用哪种方式，最终都需要编辑配置文件来确保模型参数正确。CLI 引导方式可以快速完成基础配置（Provider、API Key 等），但它为自定义模型生成的默认参数（如 contextWindow 仅 16K）远低于 step-3.5-flash 的实际能力（256K），需要手动修正。

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

如果你是首次安装或希望重新运行引导流程：


openclaw onboard

在引导过程中：

当提示选择模型提供商时，选择 “Custom Provider”。
API 兼容模式选择 openai-completions（StepFun API 兼容 OpenAI 格式）。
填入 Base URL：https://api.stepfun.com/step_plan/v1
填入你在第一步获取的 API Key。
Model ID 填写：step-3.5-flash

完成 CLI 引导后，必须手动修正模型参数。 打开 ~/.openclaw/openclaw.json，找到 CLI 自动生成的 stepfun Provider 配置，将 models 数组中的参数调整为：


"models": [
  {
    "id": "step-3.5-flash",
    "name": "step-3.5-flash",
    "reasoning": true,
    "contextWindow": 256000,  // CLI 默认生成 16384，必须改为 256000
    "maxTokens": 8192
  }
]

如果不做此修正，OpenClaw 会按照 16K 的上下文窗口来截断输入，导致模型无法处理较长的代码文件或对话历史。

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

OpenClaw 的配置文件位于 ~/.openclaw/openclaw.json。

使用你喜欢的编辑器打开它，在文件中添加或修改以下内容：


{
  "agents": {
    "defaults": {
      "model": {
        "primary": "stepfun/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": "step-3.5-flash",
            "name": "step-3.5-flash",
            "reasoning": true,
            "contextWindow": 256000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

配置字段说明：

字段	说明
`agents.defaults.model.primary`	将 `step-3.5-flash` 设为默认主模型，格式为 `provider/model`
`models.mode`	设置为 `"merge"` 表示自定义 Provider 与内置 Provider 合并，而非覆盖
`models.providers.stepfun`	Provider 的标识符，可自行命名，但建议使用有意义的名称
`baseUrl`	Step Plan API 端点：`https://api.stepfun.com/step_plan/v1`
`apiKey`	API Key。这里使用 `${STEP_API_KEY}` 引用环境变量（推荐做法），也可直接填写 Key 字符串
`api`	设为 `"openai-completions"`，表示使用 OpenAI 兼容的 Chat Completions 格式
`models[].id`	填写 StepFun API 要求的模型 ID：`step-3.5-flash`
`models[].name`	模型的显示名称，仅用于 OpenClaw 界面展示
`models[].reasoning`	设为 `true` 表示该模型支持思维链/推理模式
`models[].contextWindow`	模型支持的最大输入 token 数。`step-3.5-flash` 支持 256K
`models[].maxTokens`	模型单次最大输出 token 数。根据实际需求设置，默认 8192 即可

关于默认值：如果你省略 reasoning、contextWindow、maxTokens 等字段，OpenClaw 会使用以下默认值：

reasoning: false

contextWindow: 200000

maxTokens: 8192

但建议显式设置这些值，以获得最佳体验。

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

如果你在配置文件中使用了 ${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/step-3.5-flash 出现在模型列表中。

切换到 step-3.5-flash 模型

如果你没有将其设为默认模型，也可以通过 CLI 快速切换：


openclaw models set stepfun/step-3.5-flash

或者在 OpenClaw 对话中使用 /model 命令来切换。

发送一条测试消息

在 OpenClaw 的对话界面中发送任意消息，确认模型能正常响应。如果出现错误，请检查：

API Key 是否正确
baseUrl 是否与你获取 Key 的平台一致
环境变量是否已正确加载（可通过 echo $STEP_API_KEY 验证）
网络是否能正常访问 api.stepfun.com

常见问题

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

如果你设置了 agents.defaults.models（模型允许列表），需要确保 stepfun/step-3.5-flash 也被加入到该列表中，否则模型会被拦截。解决方法：


{
  "agents": {
    "defaults": {
      "models": {
        "stepfun/step-3.5-flash": {
          "alias": "Step Flash"
        }
      }
    }
  }
}

或者直接移除 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 使用方式。