OpenClaw

OpenClaw 是运行在个人设备上的开源 AI 助手。它通过 Gateway 统一管理模型、会话、工具和消息渠道，并提供终端 TUI 与浏览器 Control UI。将 AGTCloud 添加为 Custom Provider 后，OpenClaw 可以通过 OpenAI Chat Completions 兼容入口调用当前 API Key 可用的模型。

本教程只完成本机安装、模型接入、Gateway 启动和基础验证。消息渠道、远程 Gateway、ClawHub 插件、Skills、MCP、定时任务和多代理功能不在本页展开。

准备工作

开始前，请确认你已经：

• 准备一台受 OpenClaw 支持的 macOS、Linux、WSL2 或 Windows 设备；
• 在 API Keys 页面创建 AGTCloud API Key；
• 从模型广场复制当前 Key 可见、且支持 Chat Completions 的模型 ID；
• 准备一个不包含生产凭证和敏感源码的测试目录。

MODEL_ID 是需要替换的占位符。若要测试工具调用，请选择当前 API Key 可见且明确支持工具调用的模型。

安装 OpenClaw

OpenClaw 官方安装器可以在需要时准备受支持的 Node.js 运行环境。已经自行管理 Node.js 的客户也可以使用 npm 安装。

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

安装完成后检查版本和运行环境：

openclaw --version
openclaw doctor

如果安装器自动打开引导向导，可以先退出模型配置步骤，完成下方 AGTCloud Provider 配置后再运行 openclaw onboard --install-daemon。这样引导程序可以保留已经验证过的默认模型配置。

安全保存 API Key

OpenClaw 会读取 ~/.openclaw/.env 作为全局环境变量回退文件。先创建该文件，再写入 AGTCloud API Key：

~/.openclaw/.env

文件内容：

AGTCLOUD_API_KEY=your-api-key

该文件包含真实凭证，不要提交到代码仓库、上传到网盘或作为排障附件发送。

添加 AGTCloud Custom Provider

OpenClaw 将 Custom Provider 保存到 models.providers。本教程使用增量配置命令合并 agtcloud Provider，不覆盖现有 openclaw.json。

openclaw config set models.providers.agtcloud \
  '{"baseUrl":"https://api.agtcloud.cn/v1","apiKey":"${AGTCLOUD_API_KEY}","api":"openai-completions","auth":"api-key","authHeader":true,"models":[{"id":"MODEL_ID","name":"MODEL_ID","input":["text"]}]}' \
  --strict-json \
  --merge

配置中的关键字段如下：

教程只把模型声明为文本输入，不填写未经确认的上下文长度、最大输出、价格、推理或图像能力。掌握目标模型的真实能力后，可以再按照 OpenClaw 官方模型字段说明补充元数据。

设置模型并检查配置

将刚刚登记的模型设为默认模型：

openclaw models set agtcloud/MODEL_ID

依次检查配置文件、Provider 模型和当前默认模型：

openclaw config validate
openclaw models list --provider agtcloud
openclaw models status

如果 config validate 报告无效字段，请先修复配置，不要继续启动 Gateway。若模型列表中没有 agtcloud/MODEL_ID，请检查模型是否已经加入 models.providers.agtcloud.models。

需要执行真实连接探测时，可以运行：

openclaw models status --probe

完成本地引导并启动 Gateway

Provider 配置通过后，运行本地引导并安装 Gateway 守护进程：

openclaw onboard --install-daemon

如果向导询问模型配置，请选择保留现有模型配置；消息渠道、Web Search、Skills 和其他扩展可以先跳过。首次配置建议保持 Gateway 仅监听本机，并保留访问认证。

完成后重启并检查 Gateway：

openclaw gateway restart
openclaw gateway status

Gateway 无法启动时，先运行 openclaw config validate 和 openclaw doctor，不要使用开放公网监听或关闭认证作为临时绕过方案。

启动并验证连接

打开 Control UI 或终端 TUI

使用浏览器 Control UI：

openclaw dashboard

或者在终端连接本地 Gateway：

openclaw tui

验证基础文本回复

首次输入以下内容：

请只回复：AGTCloud 连接成功。不要调用任何工具。

能够返回指定文本，说明 Gateway、AGTCloud Provider、API Key 和模型 ID 已建立基础连接。

可选：验证只读工具能力

确认普通对话稳定后，在安全测试项目中输入：

请读取 README.md，并用三点概括项目用途。不要修改任何文件，也不要执行其他命令。

检查 OpenClaw 提出的每项操作，只批准读取目标文件所需的权限。普通对话成功但该步骤失败，通常表示目标模型或当前兼容入口尚未完整支持所需的工具调用结构。

添加或切换模型

OpenClaw 的模型引用格式为 provider/model，因此 AGTCloud 模型写作：

agtcloud/MODEL_ID

Custom Provider 不保证自动读取 AGTCloud /v1/models 的全部结果。需要增加模型时，应把新的模型对象合并到 models.providers.agtcloud.models，再使用以下命令切换：

openclaw models set agtcloud/MODEL_ID
openclaw gateway restart

修改模型名称后，应确认该模型对当前 API Key 可见且支持对应协议，否则可能出现模型不存在或不允许使用的错误。

常见问题

遇到无法定位的问题时，请记录 OpenClaw 版本、请求时间、API Base URL、Provider、模型 ID、HTTP 状态和脱敏错误信息，然后查看错误与排障。不要提交 .env、完整配置备份或任何 API Key。

安全建议

• OpenClaw 面向单一可信操作者设计，不要把未经保护的 Gateway 暴露到公网；
• 首次测试只使用隔离目录，并逐项审查文件、命令、网络和工具权限；
• 不在仓库、截图、会话导出、日志或共享配置中保存 API Key；
• 接入消息渠道、其他用户或自动化任务前，先阅读 OpenClaw 官方安全与沙箱文档。

下一步

• API Key 与认证
• Chat Completions API Reference
• 错误与排障
• OpenClaw 官方文档