珊瑚语AI文档

Appearance

OpenClaw ​

OpenClaw 是自托管 AI 助手网关，可以把 WebChat、聊天渠道、节点和工具调用接到你自己的模型 Provider。新手先把它当成“本地/服务器 Gateway + 浏览器控制台”：先安装 Gateway 并打开 Control UI，再把 AIDMX 配置为 OpenAI 兼容 Provider，让默认 agent 或指定会话使用 aidmx/模型名。

下载和官方入口 ​

入口用途
OpenClaw 文档查看产品概念、安装、配置和排障。
OpenClaw 快速开始按官方引导完成 onboarding。
OpenClaw 安装说明查看 macOS、Linux、WSL、Windows 和 npm 安装方式。
OpenClaw 环境变量配置 OPENCLAW_HOME、OPENCLAW_CONFIG_PATH 和服务环境。
OpenClaw 模型说明理解 Provider、模型 ref、别名和 fallback。

官方安装命令：

bash
# macOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bash

Windows PowerShell：

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

已有 Node 环境时：

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

平台支持 ​

平台支持状态新手选择说明
macOS支持官方安装脚本适合本机运行 Gateway 和 Control UI。
Linux / WSL2支持官方安装脚本适合本机或服务器自托管，注意 systemd/daemon 环境变量。
Windows支持官方 PowerShell 安装脚本如果配合 WSL 使用，要确认 Gateway 和配置文件在哪个环境里。
npm支持已有 Node.js 22.14+ 或 Node.js 24 的用户安装和服务启动最好使用同一个用户和同一套 PATH。
Web UI支持启动 Gateway 后打开 Control UIWeb UI 是管理界面，不是独立模型服务。

核心能力 ​

  • Gateway：常驻本地或服务器，负责接收渠道消息并调度 agent。
  • Control UI：浏览器里的控制台，可用于聊天、配置和检查状态。
  • 多渠道：支持常见聊天工具和 WebChat，适合把同一个 agent 接入不同入口。
  • 多 agent：可以按场景配置不同 agent、工作区、模型和工具。
  • 模型策略：支持主模型、fallback、图片/PDF/生成类模型和模型 allowlist。
  • 模型命令：通过 /model 或 openclaw models 查看、切换、设置别名和 fallback。
  • 自定义 Provider：在 models.providers 中接入 OpenAI 兼容端点。

AIDMX 字段速查 ​

字段推荐值
Provider IDaidmx
Provider APIopenai-completions
Base URLhttps://ai.aidmx.xyz/v1
API Key${AIDMX_API_KEY} 或 SecretRef
Model refaidmx/控制台可用模型
Token 页面https://ai.aidmx.xyz/keys/

准备 Node.js 22+ ​

OpenClaw 当前推荐 Node.js 24，也支持 Node.js 22.14+。如果你用 nvm 或多版本 Node，先确认启动 Gateway 的用户能看到正确版本。

bash
node --version
npm --version

如果版本过低，先升级 Node，再安装 OpenClaw。长期运行的 daemon 不一定读取你当前 shell 的 nvm 环境，所以安装和服务启动最好用同一个用户、同一套 PATH。

安装和引导 ​

macOS、Linux 或 WSL2：

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

Windows PowerShell：

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

如果你已经自己管理 Node：

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

引导会配置模型、认证和 Gateway。

安装后检查 ​

安装完成后检查：

bash
openclaw --version
openclaw doctor
openclaw gateway status
openclaw dashboard

openclaw dashboard 能打开 Control UI，说明 Gateway 和 UI 基本可用。

环境变量 ​

先准备 AIDMX Token：

bash
export AIDMX_API_KEY="你的 API Token"

常用 OpenClaw 环境变量：

变量用途
OPENCLAW_HOME覆盖内部路径解析的 home，适合专用服务用户。
OPENCLAW_STATE_DIR覆盖状态目录，默认 ~/.openclaw。
OPENCLAW_CONFIG_PATH覆盖配置文件路径，默认 ~/.openclaw/openclaw.json。
OPENCLAW_INCLUDE_ROOTS允许 $include 解析到配置目录之外的目录。
OPENCLAW_LOG_LEVEL覆盖日志等级，例如 debug 或 trace。
OPENCLAW_LOAD_SHELL_ENV需要从登录 shell 补齐缺失环境变量时可设为 1。

daemon、LaunchAgent、systemd user service 或 Windows Scheduled Task 不一定继承当前终端的 export。如果 Gateway 是后台服务，请把 AIDMX_API_KEY、OPENCLAW_CONFIG_PATH 等变量写入服务环境，或改用 OpenClaw SecretRef。

配置文件路径 ​

默认配置文件：

text
~/.openclaw/openclaw.json

如果设置了 OPENCLAW_CONFIG_PATH，以该变量指向的文件为准。可以用命令确认当前路径：

bash
openclaw config file

编辑前建议查看当前结构：

bash
openclaw config get models --json
openclaw config get agents.defaults --json

配置 AIDMX ​

编辑 openclaw.json，加入或合并以下片段。示例使用 JSONC 展示，实际保存时如当前文件不支持注释，请去掉注释。

jsonc
{
"models": {
"mode": "merge",
"providers": {
"aidmx": {
"name": "AIDMX",
"api": "openai-completions",
"baseUrl": "https://ai.aidmx.xyz/v1",
"apiKey": "${AIDMX_API_KEY}",
"models": [
{
"id": "控制台可用模型",
"name": "AIDMX Main"
},
{
"id": "控制台可用备用模型",
"name": "AIDMX Fallback"
}
]
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "aidmx/控制台可用模型",
"fallbacks": [
"aidmx/控制台可用备用模型"
]
},
"models": {
"aidmx/控制台可用模型": {
"alias": "aidmx-main"
},
"aidmx/控制台可用备用模型": {
"alias": "aidmx-fallback"
}
}
}
}
}

配置重点：

  • models.mode 建议保持 merge，这样 AIDMX 会和已有 Provider 合并，不会覆盖 OpenClaw 内置或其他已配置模型。
  • models.providers.aidmx.baseUrl 填 https://ai.aidmx.xyz/v1，不要填完整 /chat/completions。
  • apiKey 可以使用 ${AIDMX_API_KEY}，由 Gateway 进程启动时解析。
  • agents.defaults.model.primary 使用 provider/model 格式。
  • 如果配置了 agents.defaults.models allowlist，必须把 AIDMX 模型加入 allowlist，否则 /model 或会话切换时会提示 model not allowed。

保存后验证并重启 Gateway：

bash
openclaw config validate
openclaw gateway restart
openclaw models status

模型列表、别名和 fallback ​

查看 AIDMX Provider 下的模型：

bash
openclaw models list --provider aidmx
openclaw models status

设置默认模型：

bash
openclaw models set aidmx/控制台可用模型

添加 fallback：

bash
openclaw models fallbacks add aidmx/控制台可用备用模型
openclaw models fallbacks list

添加别名：

bash
openclaw models aliases add aidmx-main aidmx/控制台可用模型
openclaw models aliases list

聊天中也可以使用：

text
/model list
/model aidmx/控制台可用模型
/model status

如果模型 ID 本身包含 /，输入时仍要保留 Provider 前缀，例如 aidmx/vendor/model-name。

Gateway 和 UI 验证 ​

  1. 确认 Gateway 在运行。
bash
openclaw gateway status

打开 Control UI。

bash
openclaw dashboard

在 Control UI 中发送一条测试消息。查看模型状态。

bash
openclaw models status

到 使用日志 确认请求出现。

daemon 环境常见坑 ​

  • 当前终端 export AIDMX_API_KEY=...，但后台 Gateway 看不到：把变量写到 daemon/service 环境，或重新安装服务后重启。
  • 改了 OPENCLAW_CONFIG_PATH，但服务仍读默认配置：确认服务环境也设置了同一个变量。
  • 用 nvm 安装 Node 后，daemon 找不到 node 或版本过低：把正确的 Node bin 目录写进服务 PATH。
  • HTTPS 抓取失败且日志出现 fetch failed：nvm 的 Node 可能缺 CA，需要在进程启动前设置 NODE_EXTRA_CA_CERTS，只写到 ~/.openclaw/.env 可能太晚。
  • 修改 openclaw.json 后未重启 Gateway：运行 openclaw gateway restart。

成功验证 ​

  • openclaw gateway status 显示 Gateway 正常。
  • openclaw dashboard 能打开 Control UI。
  • openclaw models status 显示 primary 或 fallback 指向 aidmx/...。
  • Control UI 或渠道消息能返回 AIDMX 模型回复。
  • 使用日志 中出现 OpenClaw 请求。

常见失败 ​

Model "aidmx/..." is not allowed ​

你配置了模型 allowlist，但没有把该模型加入 agents.defaults.models。把模型加入 allowlist，或暂时移除 allowlist 后再测试。

models list 看不到 AIDMX ​

检查 models.mode 是否为 merge，models.providers.aidmx 是否在当前配置文件里，以及 Gateway 是否读取了你编辑的 OPENCLAW_CONFIG_PATH。

日志里没有 AIDMX 请求 ​

先确认 Control UI 当前会话真的选中了 aidmx/模型名，再检查 Gateway 进程是否能解析 AIDMX_API_KEY。必要时运行 openclaw models status --json 看 auth 状态。

应该把 Token 写进配置文件吗 ​

不建议。优先使用 ${AIDMX_API_KEY} 或 SecretRef。若必须临时明文写入，只用于本地验证，并确保配置文件不会提交到公开仓库。

baseUrl 要不要加 /chat/completions ​

OpenClaw 的自定义 OpenAI 兼容 Provider 使用 baseUrl: "https://ai.aidmx.xyz/v1"，由 provider 模式拼接对应接口。

官方链接 ​

  • OpenClaw 文档
  • OpenClaw 快速开始
  • OpenClaw 安装说明
  • OpenClaw 环境变量
  • OpenClaw 模型说明

下一步 ​

  • 阅读 OpenAI 兼容工具 了解通用字段。
  • 使用 使用日志 验证真实请求。
  • 如果同时管理多个 CLI，参考 CC Switch。