8848AI 工具指南
配置 · 使用 · 排错
个人助手 · Gateway · 最小权限

OpenClaw 接入 8848API：安装、网关与安全起步

把模型提供商、Gateway认证、工具权限和消息通道分开配置。提供向导与最小禁工具配置两条路径，从本机状态到一轮对话逐层检查，再按需扩展自动化。

从这里开始返回文档首页

更新：2026-10-15 · 菜单随客户端版本变化，以实际版本为准。模型权限、协议和价格以当前账户可用服务为准。

1. 先区分两类密钥和两种服务

先登录控制台，在「令牌管理」创建单独用于此工具的令牌。检查有效期、额度、允许模型和访问限制；令牌不是网站登录密码，也不是厂商官方账号。

对象用途不能混用
8848API令牌Gateway向模型平台请求时认证不是OpenClaw网页控制台登录令牌
OpenClaw Gateway令牌控制端连接你自己的Gateway不填写到平台模型Key框，不分享Dashboard私密链接
模型Provider指定上游协议、URL、模型ID不自动开通消息通道或外部工具

本教程选OpenAI Chat Completions，Base URL为 https://api.884819.xyz/v1。默认模型写成Provider ID加实际模型ID；不能只写一个没有Provider归属的显示名称。

OpenClaw可以读写文件、执行工具和长期自动化。不要假定首次向导默认已经禁工具或开启沙箱；初次测试应主动限制工具，不接收陌生人消息。

2. 安装官方版本

按 官方安装文档检查当前运行环境；版本要求会更新，不照搬旧教程的Node版本。macOS / Linux / WSL可使用官方安装器：

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

脚本会下载并执行代码，并可能进入向导；在确认来源和接入费用后再运行。若只准备安装、暂不进入初始化，可用官方安装器选项：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard

只安装也可能更新已有安装或服务；已有环境先备份，不把它当完全无副作用的检查命令。Windows使用官方当期支持的原生或WSL流程，不复制未经核实的启动方式。

openclaw --version

先确定实际运行用户与环境；服务进程、WSL和你当前shell的家目录/变量可能不同。

3. 路径A：按官方向导添加模型

会产生真实调用：以下发消息、检查模型连接或执行 Agent 任务可能计费；先核预算，不反复点击检测、不批量试模型。只查看版本、静态配置和本地状态不等于模型已经可用。
openclaw onboard

需要详细Provider和Gateway控制时，当前官方提供classic向导：

openclaw onboard --classic
  1. 选择本机Gateway与自定义模型提供商；新旧版本菜单顺序不同，不假定QuickStart一定出现同名按钮。
  2. Base URL填 https://api.884819.xyz/v1，兼容协议选择OpenAI Chat Completions（不是Responses或Anthropic）。
  3. 模型ID从当前账户复制；Provider ID可用 api8848，显示名可自行设置。
  4. 选择密钥引用方式时，确保引用的变量或Secret Provider确实可被Gateway运行用户解析；仅写引用字符串不等于认证已生效。
  5. 先禁用非必要工具、暂跳过消息通道与技能，保持本机回环监听和认证。
  6. 阅读模型验证提示后再继续；向导可能发真实completion，跳过health不等于跳过模型验证。

已有用户不加reset、不清空配置来重跑。需要长期服务可按当前官方流程安装daemon；服务安装不代表模型已经可用。若希望初始配置明确禁工具，可改用下节路径B，不重复覆盖。

4. 路径B：可审阅的最小禁工具配置

先备份，合并到默认 ~/.openclaw/openclaw.json，不要覆盖既有agents、channels和SecretRef。模型占位值必须在两处替换为同一个完整ID：

{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    }
  },
  "models": {
    "providers": {
      "api8848": {
        "baseUrl": "https://api.884819.xyz/v1",
        "apiKey": "${API8848_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "REPLACE_WITH_AVAILABLE_MODEL_ID", "name": "8848API model" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "api8848/REPLACE_WITH_AVAILABLE_MODEL_ID" }
    }
  },
  "tools": { "deny": ["*"] }
}

在受保护的 ~/.openclaw/.env中用本地编辑器设置：

API8848_KEY=REPLACE_WITH_YOUR_PLATFORM_TOKEN
OPENCLAW_GATEWAY_TOKEN=REPLACE_WITH_A_LONG_RANDOM_GATEWAY_SECRET

POSIX环境可对私密文件限制权限（先确保文件存在并归你所有）：

chmod 600 ~/.openclaw/.env ~/.openclaw/openclaw.json

Windows使用等效的当前用户专属访问权限。不要在包含其他服务配置的目录上递归chmod。

5. 启动与检查Gateway

先校验配置，再选择前台运行或后台服务一种方式：

openclaw config validate

前台：便于首次观察日志

openclaw gateway --port 18789

保持此终端运行；18789是常见示例端口，以你实际配置为准。如果已有服务占用，不启动第二套也不随意杀进程。

需要后台常驻时

openclaw gateway install
openclaw gateway start
openclaw gateway status

由实际系统的服务管理器支持情况决定安装方式；不把前台进程退出后失联误判成模型故障。

本地状态与安全诊断

openclaw health
openclaw doctor
openclaw security audit

健康检查通过仅证明Gateway层正常；不证明模型或消息平台已接通。查看输出再决定处理，不在未理解的情况下运行自动修复。

6. 先验证一轮无工具对话

会产生真实调用：以下发消息、检查模型连接或执行 Agent 任务可能计费；先核预算，不反复点击检测、不批量试模型。只查看版本、静态配置和本地状态不等于模型已经可用。
openclaw dashboard
  1. 在本机打开Dashboard，核当前默认模型对应 api8848/实际模型ID。
  2. 不要向他人分享包含私密访问令牌的地址。发送一轮短消息，不附文件、不启工具。
  3. 确认回复完整，再在平台调用记录核模型、时间和用量。
  4. 如果使用路径B禁工具配置，工具不可用是预期结果，不为通过测试直接删掉全部权限限制。

文字对话、Gateway状态、工具调用和消息投递分别验收。短消息通过不能推出长期自动化安全可用。

7. 工具和消息通道最后再加

  1. 明确具体任务和所需工具，只对必要能力逐项放行；本教程初始deny全部工具，扩展前需审阅并调整这条全局策略。
  2. 文件、Shell、浏览器和外部服务分别评估权限；配置工具策略不等于进程已隔离，需要时单独设置沙箱。
  3. 模型需支持相应工具调用与多轮响应，视觉能力也要另核，不通过改标签伪装能力。
  4. 消息平台先配置允许用户/配对，先私聊验证，再考虑群组和长期任务。通道凭据不混入模型Provider。
  5. 定时任务与自动重试设置次数/预算边界；停止无人值守任务前确认它没有仍在提交请求。

不要把聊天平台所有成员默认当授权操作人，也不要从不明技能包复制命令直接执行。

8. 排错、备份与恢复

401 / Key引用未生效

核令牌、环境变量、Gateway运行用户和配置路径，不输出.env。独立检查Gateway认证与模型认证，不把一种令牌填到另一处。

404 / 模型未找到

核/v1、openai-completions协议、models列表及primary引用，保证Provider ID和实际模型ID一致。

Gateway正常但没有回复

状态正常不代表上游可用；看脱敏错误与请求ID，核模型权限、限流和用量后再受控验证。

备份与恢复

按官方backup工具生成可校验备份，不直接复制正在运行的数据库来代替安全备份。备份包含配置、凭据与工作区，需加密私下保存；恢复前停止相关服务、保存当前状态并核归档可信，不盲目覆盖运行目录。

官方资料与核验边界

本文整理安装与配置方法，不代表所有客户端版本、模型、工具调用或远程功能均已实测。本次文档更新未发起付费模型请求；文中的模型验证、首次对话和自动化运行可能计费，请确认模型与预算后自行执行。

静态工具指南｜本页不收集密钥，不读取用户数据库；密钥仅填写到你信任的本地客户端。