CLI 工具

OpenClaw

OpenClaw 接入 VisionCoder：openclaw.json 里配 provider，模型名必须带 visioncoder/ 前缀

OpenClaw 是开源的终端 AI Agent。它不读环境变量，所有配置集中在一份 openclaw.json 里 —— 写一次 provider，之后所有项目通用。

前提

在 API Key 管理创建 API Key
已装 Node.js 18+
Windows 用户：额外装 Git for Windows

步骤一：安装 OpenClaw

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw --version

只想装、不想立刻进引导流程：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

iwr -useb https://openclaw.ai/install.ps1 | iex
openclaw --version

只想装、不想进引导：

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

powershell -ExecutionPolicy Bypass -Command "iwr -useb https://openclaw.ai/install.ps1 | iex"
openclaw --version

能看到版本号就说明装好了。提示找不到 openclaw 命令？关掉终端重开再试。

步骤二：找到配置文件

路径：~/.openclaw/openclaw.json

mkdir -p ~/.openclaw

路径：C:\Users\你的用户名\.openclaw\openclaw.json

New-Item -ItemType Directory -Force "$env:USERPROFILE\.openclaw"
notepad "$env:USERPROFILE\.openclaw\openclaw.json"

路径：C:\Users\你的用户名\.openclaw\openclaw.json

mkdir "%USERPROFILE%\.openclaw"
notepad %USERPROFILE%\.openclaw\openclaw.json

步骤三：写入配置

把下面内容完整贴进 openclaw.json，把 YOUR_API_KEY 换成你的 Key。文件里原来有内容的话，先备份再合并。

{
  env: {
    VISIONCODER_API_KEY: 'YOUR_API_KEY',
  },
  models: {
    mode: 'merge',
    providers: {
      visioncoder: {
        baseUrl: 'https://coder.api.visioncoder.cn/v1',
        apiKey: 'VISIONCODER_API_KEY',
        api: 'openai-responses',
        models: [
          {
            id: 'gpt-5.4',
            name: 'GPT-5.4',
            reasoning: true,
            input: ['text', 'image'],
            contextWindow: 400000,
            contextTokens: 380000,
            maxTokens: 128000,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      models: {
        'visioncoder/gpt-5.4': {},
      },
      model: {
        primary: 'visioncoder/gpt-5.4',
      },
    },
  },
}

最容易填错的是这三处：

apiKey 填的是变量名，不是 Key 本身。真正的 Key 放在上面的 env.VISIONCODER_API_KEY 里，这里只写 'VISIONCODER_API_KEY' 这个名字。
baseUrl 必须带 /v1：https://coder.api.visioncoder.cn/v1
primary 要写全限定名 visioncoder/gpt-5.4，只写 gpt-5.4 找不到。

挂多个模型

models 是个数组，往里加就行；agents.defaults.models 里也要同步登记一份：

models: [
  { id: 'gpt-5.4', name: 'GPT-5.4', reasoning: true, input: ['text', 'image'],
    contextWindow: 400000, contextTokens: 380000, maxTokens: 128000 },
  { id: 'claude-sonnet-5', name: 'Claude Sonnet 5', reasoning: true, input: ['text', 'image'],
    contextWindow: 200000, contextTokens: 190000, maxTokens: 64000 },
]

agents: {
  defaults: {
    models: {
      'visioncoder/gpt-5.4': {},
      'visioncoder/claude-sonnet-5': {},
    },
    model: { primary: 'visioncoder/gpt-5.4' },
  },
}

完整模型 ID 列表：curl https://coder.api.visioncoder.cn/v1/models

步骤四：验证

openclaw

启动后随便问一句。想确认模型挂对了，看启动时打印的当前模型是不是 visioncoder/gpt-5.4。

故障排查

启动报找不到模型 visioncoder/xxx

三个地方要对得上：models.providers.visioncoder.models[].id、agents.defaults.models 的 key、model.primary。少登记一处就会找不到。

注意后两处要写全限定名（visioncoder/ 开头），第一处是裸 ID。

401 / 403

env.VISIONCODER_API_KEY 里是不是真的 Key（不是变量名）
apiKey 字段里是不是变量名（不是 Key）—— 这两个位置容易填反
baseUrl 带没带 /v1

配置改了不生效

OpenClaw 启动时读一次配置。改完退出重进。

另外确认改的是 ~/.openclaw/openclaw.json，不是项目目录下的同名文件。

JSON 格式报错

这个文件是 JSON5：key 可以不加引号、允许尾逗号、支持注释。但如果你的编辑器按标准 JSON 校验，会一路飘红 —— 那是编辑器的问题，不影响 OpenClaw 读取。

加群 & 客服