小蓝中转站使用文档

接入 OpenClaw ​

OpenClaw 不是单纯的聊天客户端，它更像一套可以自托管的 AI Agent 平台：有 Web 界面、有配置文件、有技能系统，也可以继续往 Slack、Telegram、Discord 这类渠道扩展。

只想先把桌面聊天跑通时，优先用 Cherry Studio。准备把模型能力做成自己的内部服务、远程面板或团队入口时，再看 OpenClaw 会更合适。

第一次接入时，先把“OpenClaw”和“普通桌面客户端”分清楚会省很多时间：

  • Cherry Studio 更适合个人直接聊天
  • Claude Code / Codex 更适合在终端里改代码
  • OpenClaw 更适合长期运行、给多人或远端入口复用

现在只是想先确认账号、Key 和模型能不能正常回复时，先用 Cherry Studio 或 Claude Code 跑通一条链路，再回来配 OpenClaw，排障会轻很多。

下载与安装 ​

官方入口：

OpenClaw 官方安装页当前先强调一件事：Node.js 22+ 是前置条件，Node.js 24 更推荐。

Node.js 还没装时，先看 Windows Node 安装、macOS Node 安装 或 Linux Node 安装。

官方当前提供三种安装路线：

  1. 官方快速安装脚本
  2. npm install -g openclaw@latest
  3. 从源码安装

已经按前面的 Node 教程配好了 npm 镜像时，手动安装会更容易看清每一步到底成功没有，国内用户通常先走这一条：

bash
npm install -g openclaw@latest
openclaw onboard --install-daemon
openclaw --version

npm install -g 只负责把命令装上；真正把认证、Gateway 配置、后台服务一起准备好的是后面的 openclaw onboard --install-daemon。

用 npm 全局安装后，openclaw doctor、Gateway UI 资源或服务启动一直表现异常时，可以直接改走这两条回退路线之一：

  1. 改用 pnpm add -g openclaw@latest
  2. 改用官方安装脚本重新安装

这样做不是因为 小蓝中转站 配置一定有问题，而是 OpenClaw 最近版本里，社区里确实出现过少数 npm 全局安装后资源或依赖不完整的情况。先把安装层切干净，比反复怀疑 Key 和模型更省时间。

平时用 pnpm 时，也可以按官方安装页写法改成：

bash
pnpm add -g openclaw@latest
openclaw onboard --install-daemon
openclaw --version

想一步完成时，也可以直接用官方 quick install：

  • macOS / Linux：curl -fsSL https://openclaw.ai/install.sh | bash
  • Windows（WSL 2 或 PowerShell）：iwr -useb https://openclaw.ai/install.ps1 | iex

PowerShell 默认会拦一部分脚本执行，这不是 OpenClaw 特有的问题，而是系统默认在拦“来源不明的脚本”。
这一步被执行策略挡住时，先回到 Windows 快速接入 处理 PowerShell 执行策略，再继续安装。

接入前先准备 ​

OpenClaw 接入 小蓝中转站 之前，先准备好：

  1. Node.js 22+ 和 npm
  2. 一把给 OpenClaw 单独使用的 Key，建议命名为 Server-OpenClaw
  3. 一个先拿来测试的轻量模型名
  4. 一个准备自己修改的管理密码

OpenClaw 通常会长期运行。把它单独拆一把 Key，可以更容易在日志里分清这套服务自己的消耗，也方便以后做额度上限和吊销。

先让向导生成一份可用配置 ​

第一次接入时，先跑一遍官方向导会比从零手写 YAML 更稳：

bash
openclaw onboard --install-daemon

这个向导会做几件事：

  • 生成默认配置
  • 配置认证和 Gateway 相关项
  • 安装后台服务，方便长期运行

先让向导把骨架搭好，再回头把模型改成 小蓝中转站，通常比自己从空文件开始写更不容易踩缩进、字段名和默认路径的坑。

配置文件在哪里 ​

按 OpenClaw 官方配置页，默认配置文件是：

txt
~/.openclaw/openclaw.yaml

安装时改过 OPENCLAW_HOME 的话，配置文件会在：

txt
$OPENCLAW_HOME/openclaw.yaml

之所以先找到这个文件，是因为 OpenClaw 的模型来源、管理账号、端口和 Agent 默认行为都在这里。只改前端面板而不改这个配置文件，服务本身并不会真正切到 小蓝中转站。

OpenClaw 官方当前有个别页面还会把它写成 config.yaml，但配置页和完整示例实际使用的是 openclaw.yaml。
实际排查时，以你机器上的 ~/.openclaw/openclaw.yaml 为准。

现在不确定服务到底读的是哪一份配置文件时，不要先猜。
先确认你安装时有没有设置过 OPENCLAW_HOME，再去对应目录里找实际存在的文件。
真正拿来排障的优先级始终是：本机实际生成的文件 > 文档里的历史命名差异。

配置 小蓝中转站 网关 ​

下面是一份适合第一次接入的最小示例：

yaml
server:
  port: 3000
  host: 0.0.0.0

admin:
  username: admin
  password: 改成你自己的管理密码

models:
  xiaolan:
    # OpenClaw 这里走的是 OpenAI 兼容接口，所以地址要带 /v1
    api_key: sk-你的 OpenClaw 专属 Key
    base_url: https://xiaolan.ainb.plus/v1
    default_model: 从模型广场复制的模型名

agents:
  assistant:
    # 这里的 xiaolan 前缀要和上面的 models.xiaolan 保持一致
    model: xiaolan/从模型广场复制的模型名
    language: zh
    timezone: Asia/Shanghai

这里有三个关键点：

  • models.xiaolan 里的 xiaolan 只是这一组 Provider 的名字，你也可以改成别的名字
  • base_url 这里要带 /v1，因为 OpenClaw 这里走的是 OpenAI 兼容端点
  • agents.assistant.model 前缀要和上面的 Provider 名保持一致，所以这里写成 xiaolan/模型名

第一次配置时，最容易漏的是第三项。
很多人改了 default_model，却忘了下面的 agents.assistant.model 还停留在旧值，结果页面能打开，聊天却一直报模型不可达或模型不存在。

模型名继续以模型广场为准，不要沿用旧教程里的官方平台模型名。

准备把密钥放进环境变量而不是直接写进 YAML 时，OpenClaw 官方也支持环境变量覆盖。最常用的是这几个：

bash
export OPENCLAW_MODELS_小蓝中转站_API_KEY="sk-你的 OpenClaw 专属 Key"
export OPENCLAW_MODELS_小蓝中转站_DEFAULT_MODEL="从模型广场复制的模型名"
export OPENCLAW_ADMIN_PASSWORD="改成你自己的管理密码"

这样做的好处是服务端换 Key 更方便，也不容易把真实密钥误传到备份或仓库里。

修改后先验证，再启动 ​

OpenClaw 官方配置页专门给了校验命令。手动改完 YAML 后，先验证一遍：

bash
openclaw config validate

这样做的目的不是多跑一步，而是把 YAML 缩进错误、字段名写错、旧配置残留这类问题提前拦住。很多“启动失败”其实并不是网关问题，而是配置文件本身没过校验。

再做一次健康检查：

bash
openclaw doctor

doctor 会顺手检查 Node.js 版本、依赖、配置文件和一部分网络连通性。
现在就卡在这一层时，问题通常还没到 小蓝中转站 模型本身。

验证通过后再启动：

bash
openclaw start

希望它长期在后台跑时：

bash
openclaw start --daemon

官方首次对话页给出的默认访问地址是：

txt
http://localhost:3000

部署在远端服务器时，把 localhost 换成服务器 IP 或域名即可。

想确认当前服务有没有真的起来，也可以再执行：

bash
openclaw gateway status
openclaw dashboard

gateway status 更适合看后台服务是不是真的起来了，dashboard 可以直接把 Web 面板打开。排障时，这两个命令比反复猜“是不是没启动起来”更直接。

还想看更完整的总体状态时，再补一条：

bash
openclaw status

但只想确认 Gateway 本身是不是健康，优先看 openclaw gateway status 会更直接。

第一次进入后看什么 ​

登录 Web 面板后，先做三件事：

  1. 发一条“你好”
  2. 看页面顶部、会话信息或日志里是否显示你刚配置的模型
  3. 确认管理密码已经不是默认值

能正常回复后，再继续接入团队成员、Bot 渠道或更多技能。

真正算接通时，通常要同时满足：

  1. openclaw doctor 和 openclaw config validate 都通过
  2. openclaw gateway status 显示服务已经起来
  3. 面板里能正常登录
  4. 发一句“你好”后能正常返回
  5. 当前回复使用的确实是你刚配置的 小蓝中转站 模型

使用建议 ​

先用轻量模型把链路跑通 ​

OpenClaw 部署层级比普通桌面客户端更深：安装、配置文件、管理面板、模型 Provider、技能系统，任何一层写错都可能表现成“对话失败”。

第一次先用轻量模型测试，目的是把问题范围缩小到“服务能不能连上模型”。等这一层稳定后，再换更强的长上下文或代码模型。

面向公网时一定要分开控制 ​

如果这套 OpenClaw 会给团队或公网用户使用，建议至少做三件事：

  • 给 OpenClaw 单独建 Key
  • 给这把 Key 设置额度上限
  • 把 admin.password 改掉，不使用默认密码

这样即使某个入口暴露，也不会把你所有客户端的额度和配置一起带出去。

如果只是自己本机临时用，先不要急着上公网。
先在 localhost 把整条链路跑通，再决定是否加反向代理、域名、团队入口和外部渠道。

常见问题 ​

openclaw start 能启动，但聊天时报模型不可达 ​

优先回看这三项：

  • base_url 是否写成了 https://xiaolan.ainb.plus/v1
  • api_key 是否复制完整
  • agents.assistant.model 是否和 models.xiaolan.default_model 使用了同一个实际模型名

很多人只改了 default_model，却忘了下面 assistant.model 还是旧值。

把 Key 放到了环境变量里时，还要再确认当前终端或后台服务真的拿到了这些变量。
很多“明明写了 Key 还是鉴权失败”，最后查出来只是服务进程启动时根本没读到新的环境变量。

配置文件改完后没有生效 ​

先重新执行：

bash
openclaw config validate
openclaw restart

Docker 部署时，再确认容器里挂载的就是你正在编辑的那份 openclaw.yaml。

前面改的是环境变量时，不要只重开浏览器，要把 OpenClaw 服务本身一起重启。

怀疑服务读的不是这一份 YAML 时，再回去确认：

  • 当前机器有没有设置 OPENCLAW_HOME
  • 当前是不是 Docker 部署
  • 你正在编辑的文件，和服务实际挂载的文件是不是同一份

页面能打开，但登录不上 ​

先检查是不是还在使用默认 admin / changeme123，或者你修改过密码后忘了同步当前浏览器里的保存记录。

管理密码和模型 Key 是两套东西：一个保护面板登录，一个保护模型调用，别把两者混在一起排查。

端口被占用 ​

如果 3000 已经被别的服务占用，直接改 server.port，或者先停掉冲突服务后再启动。

页面打不开不一定是网关故障，端口冲突和本机防火墙也很常见。

openclaw doctor 一开始就报 Node 版本不对 ​

这说明你现在卡在安装层，不在模型层。
先把 Node.js 升到 22 或更高版本，再继续改 Key 和模型，否则后面的 Gateway、Web UI、技能系统都可能表现异常。

下一步 ​

小蓝中转站使用文档

© 2026 小蓝中转站