OpenClaw 接入指南
通过 OpenAI 兼容接口在 OpenClaw 中接入 TokenPlus，配置模型并开始对话。
本文介绍如何在 OpenClaw 中配置 TokenPlus 自定义提供商，通过 OpenAI Chat Completions 接口调用模型。
第一步：准备 OpenClaw 和 TokenPlus API
开始前，请按照 OpenClaw 官方文档完成安装与初始化，并按照 TokenPlus 快速入门 完成注册、实名认证、充值和 API 密钥创建。
接入时需要以下信息：
| 配置项 | 填写内容 |
|---|---|
| API 密钥 | 在 TokenPlus 项目空间创建的完整密钥 |
| Base URL | https://api.tokenplus.cn/v1 |
| API 类型 | openai-completions |
| 模型 ID | 从 TokenPlus 模型广场复制的完整模型调用标识 |
请选择支持 OpenAI Chat Completions 和工具调用的模型，以便 OpenClaw 执行工具任务。模型 ID 不一定等于展示名称，请保留平台提供的完整标识及前缀。
Base URL 必须包含 /v1，不要在末尾再添加 /chat/completions；OpenClaw 会根据
API 类型拼接请求路径。
第二步：配置 TokenPlus 提供商
保存 API 密钥
在 OpenClaw 状态目录的 .env 文件中新增以下配置，默认路径为 ~/.openclaw/.env：
TOKENPLUS_API_KEY=YOUR_TOKENPLUS_API_KEY将 YOUR_TOKENPLUS_API_KEY 替换为实际密钥。如果文件已有其他变量，请保留原有内容，只新增或更新这一项。
密钥文件只应由本机受信任的用户访问，不要提交到代码仓库或分享给他人。配置中通过 ${TOKENPLUS_API_KEY} 引用密钥，避免把实际密钥直接写入模型配置示例。
编辑 openclaw.json
打开 OpenClaw 配置文件，默认路径为 ~/.openclaw/openclaw.json。如果设置了 OPENCLAW_CONFIG_PATH，请编辑该变量指定的文件；使用自定义状态目录时，密钥文件也应放在对应状态目录中。
编辑前先备份文件。将下面的 models 配置合并到现有配置中：
{
"models": {
"mode": "merge",
"providers": {
"tokenplus": {
"baseUrl": "https://api.tokenplus.cn/v1",
"apiKey": "${TOKENPLUS_API_KEY}",
"api": "openai-completions",
"models": [
{
"id": "YOUR_MODEL_ID",
"name": "TokenPlus 模型"
}
]
}
}
}
}将 YOUR_MODEL_ID 替换为从 TokenPlus 复制的完整模型调用标识，name 可以改为便于识别的名称。
上面的内容只展示本次接入所需字段，不是完整的 OpenClaw
初始化配置。不要用它覆盖整个文件。若已有 models.providers，只在该对象内新增
tokenplus，保留其他提供商、Agent、聊天渠道和安全设置；已有模型模式如需从
replace 改为 merge，请先确认是否允许合并其他模型目录。
示例省略了模型能力、上下文窗口、输出上限和价格等可选字段。需要配置这些字段时，请依据所选模型详情填写，不要直接套用其他模型的参数，也不要把价格设为 0 并理解为免费调用。实际费用以 TokenPlus 账单为准。
第三步：检查配置和模型
保存后，在终端运行：
openclaw config validate
openclaw models list
openclaw models status确认配置校验通过，并且模型列表包含 tokenplus/YOUR_MODEL_ID 对应的实际模型。
OpenClaw 的模型引用格式是 提供商 ID/模型 ID。这里的 tokenplus/ 是 OpenClaw 的提供商前缀，不是 TokenPlus API 模型 ID 的一部分。例如，若平台模型 ID 中已经包含 /，仍需保留完整 ID，并在前面加上 tokenplus/。
如果 Gateway 已作为服务运行，首次新增或修改 .env 密钥后，请重启服务以重新加载环境变量：
openclaw gateway restart如果 Gateway 在前台运行或由其他进程管理器托管，请通过原来的启动方式重启，而不是额外启动一个 Gateway。
第四步：切换模型并开始对话
在当前会话切换
在 OpenClaw Web 界面或已连接的聊天渠道中发送以下命令，将占位符替换为实际模型 ID：
/model tokenplus/YOUR_MODEL_ID再发送一条测试消息：
你好，请用一句话介绍你能帮我做什么。收到正常回复后，可以进入 TokenPlus 的 调用日志，核对请求状态、模型和费用。普通对话成功后，再测试所需的工具调用任务。
设置为默认模型
确认接入可用后，如需修改全局默认模型，在终端运行：
openclaw models set "tokenplus/YOUR_MODEL_ID"
openclaw models status该命令会更新默认模型配置。已有会话的模型选择或单个 Agent 的独立模型配置可能仍需单独调整；仅临时体验时，使用前面的 /model 命令即可。
常见问题
提示环境变量或 API 密钥缺失
检查 OpenClaw 状态目录中的 .env 是否包含 TOKENPLUS_API_KEY，变量名是否与配置引用一致，以及密钥是否完整、有效。Gateway 服务不会自动继承您在另一个终端中临时设置的变量，修改密钥文件后请重启相应服务。
提示模型不存在或不允许使用
确认配置中的模型 id 与 TokenPlus 模型详情一致，切换命令使用 tokenplus/完整模型 ID。若配置了模型选择限制，需在已有策略中允许该模型，不要为解决报错直接删除其他限制。不同 OpenClaw 版本的模型限制字段可能不同，请以所用版本的官方文档为准。
返回 401、余额不足或额度超限
检查密钥是否过期、被停用或包含多余空格，并检查账户余额、项目预算和密钥消费限额。具体原因可以在 TokenPlus 调用日志中查看。
普通对话正常，但工具调用失败
确认模型和接入接口支持工具调用，并核对 OpenClaw 的工具权限。涉及图片、推理或更大上下文时，按模型详情补充对应能力与限制，不要仅凭模型名称推断支持情况。
相关指南
快速入门 · 统一 API · 调用日志 · OpenClaw 自定义提供商 · OpenClaw 环境变量 · OpenClaw 模型命令