> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw

> OpenClaw 开源本地 AI 助手集成指南（GravitexAI）

## 一、产品简介

**OpenClaw** 是一款开源（MIT 协议）的本地 AI 助手，运行在你自己的电脑上，可通过 Telegram、WhatsApp、Discord、Slack、iMessage 等多平台交互，实现**文件操作、终端命令执行、浏览器自动控制、定时任务**等真正的自主任务执行能力。

通过对接 **GravitexAI**（OpenAI 兼容接口），你可以用一个密钥直接调用 GPT、Claude、Gemini、DeepSeek 等 400+ 主流模型。

<CardGroup cols={2}>
  <Card title="本地隐私" icon="shield">
    数据完全在本地处理，隐私安全有保障
  </Card>

  <Card title="多平台接入" icon="message-circle">
    支持 Telegram / WhatsApp / Discord / Slack / iMessage
  </Card>

  <Card title="自主执行" icon="wand-magic-sparkles">
    不只是聊天，能真正操作电脑、执行命令
  </Card>

  <Card title="可扩展" icon="puzzle-piece">
    支持自定义技能与插件扩展
  </Card>
</CardGroup>

<Info>
  官网：`openclaw.ai` ｜ 项目地址：`github.com/openclaw/openclaw` ｜ 协议：MIT
</Info>

## 二、前置条件

* 在 [GravitexAI 控制台](https://maas.gravitex.ai/#/keys) 创建 API Key
* Node.js 22 或更高版本
* 系统：macOS / Linux / Windows

## 三、安装 OpenClaw

### 1. 安装 Node.js

<CodeGroup>
  ```bash macOS (Homebrew) theme={null}
  brew install node@22
  ```

  ```bash Linux (nvm) theme={null}
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
  nvm install 22
  nvm use 22
  ```

  ```powershell Windows (fnm) theme={null}
  winget install Schniz.fnm
  fnm install 22
  fnm use 22
  ```
</CodeGroup>

### 2. 安装 OpenClaw

<CodeGroup>
  ```bash npm 安装（推荐） theme={null}
  npm install -g openclaw
  ```

  ```bash 一键脚本 (macOS/Linux) theme={null}
  curl -fsSL https://openclaw.ai/install.sh | bash
  ```

  ```powershell Windows PowerShell theme={null}
  irm https://openclaw.ai/install.ps1 | iex
  ```
</CodeGroup>

### 3. 验证安装

```bash theme={null}
openclaw --version
openclaw doctor
```

若 `openclaw doctor` 报告问题，可执行 `openclaw doctor --fix` 自动修复。

## 四、配置 GravitexAI

OpenClaw 使用 JSON 配置文件，位于 `~/.openclaw/openclaw.json`。

### 方式一：配置文件方式（推荐）

创建或编辑配置文件 `~/.openclaw/openclaw.json`：

```json theme={null}
{
  "agents": {
    "defaults": {
      "model": { "primary": "gravitex/claude-sonnet-4-6" }
    }
  },
  "models": {
    "providers": {
      "gravitex": {
        "baseUrl": "https://api.gravitex.ai/v1",
        "apiKey": "sk-你的GravitexAI密钥",
        "api": "openai-completions",
        "models": [
          { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6" },
          { "id": "gpt-5.4", "name": "GPT-5.4" },
          { "id": "deepseek-v3-2-251201", "name": "DeepSeek V3.2" },
          { "id": "gemini-3.1-pro-preview", "name": "Gemini 3.1 Pro" }
        ]
      }
    }
  }
}
```

<Tip>
  * `baseUrl` 必须以 `/v1` 结尾
  * `api` 字段选用 `openai-completions`；若希望直连 Claude 原生接口，可改为 `anthropic-messages`
</Tip>

### 方式二：CLI 交互式配置

执行向导，按提示填入 Base URL 与 API Key：

```bash theme={null}
openclaw onboard
```

| 配置项         | 填写内容                            |
| ----------- | ------------------------------- |
| Provider 名称 | `gravitex`                      |
| API 类型      | `openai-completions`            |
| Base URL    | `https://api.gravitex.ai/v1`    |
| API Key     | 你的 GravitexAI 密钥                |
| 默认模型        | `claude-sonnet-4-6` 或 `gpt-5.4` |

### 方式三：Anthropic 原生配置

若希望使用 Claude 模型原生 Messages 接口（更好的工具调用体验）：

```json theme={null}
{
  "agents": {
    "defaults": {
      "model": { "primary": "gravitex/claude-sonnet-4-6" }
    }
  },
  "models": {
    "providers": {
      "gravitex": {
        "baseUrl": "https://api.gravitex.ai",
        "apiKey": "sk-你的GravitexAI密钥",
        "api": "anthropic-messages",
        "models": [
          { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6" },
          { "id": "claude-haiku-4-5-20251001", "name": "Claude Haiku 4.5" }
        ]
      }
    }
  }
}
```

配置完成后，重启 Gateway 服务使其生效：

```bash theme={null}
openclaw gateway restart
```

## 五、启动与使用

### 1. Web UI（推荐方式）

最简单、无需任何代理：

```bash theme={null}
openclaw dashboard
```

浏览器会自动打开 `http://127.0.0.1:18789/`，直接在页面聊天即可。

### 2. Telegram Bot

1. 在 Telegram 搜索 `@BotFather`，发送 `/newbot` 创建机器人
2. 获取 Bot Token，在 `openclaw onboard` 中填入
3. 国内使用需要代理：

```bash theme={null}
export https_proxy=http://127.0.0.1:代理端口
export http_proxy=http://127.0.0.1:代理端口
openclaw gateway restart
```

### 3. 其他平台

OpenClaw 还支持 **WhatsApp**（扫码连接）、**Discord**（创建 Bot）、**Slack**、**Signal**、**iMessage**、**Microsoft Teams** 等。

## 六、推荐模型配置

| 任务类型   | 推荐模型 ID                     | 说明           |
| ------ | --------------------------- | ------------ |
| 复杂任务执行 | `claude-sonnet-4-6`         | 理解准确、工具调用稳定  |
| 日常对话   | `gpt-5.5`                   | 响应自然，通用性好    |
| 编程开发   | `deepseek-v3-2-251201`      | 中文编程性价比高     |
| 长文档处理  | `gemini-3.1-pro-preview`    | 超长上下文        |
| 快速响应   | `claude-haiku-4-5-20251001` | 速度与成本兼顾      |
| 推理增强   | `claude-opus-4-7`           | 复杂推理、算法 / 逻辑 |

完整模型列表请见 [GravitexAI 模型市场](https://maas.gravitex.ai/#/models)。

## 七、核心技能

OpenClaw 内置丰富技能，可自动完成各类任务：

### 文件与系统

| 技能                                 | 功能                |
| ---------------------------------- | ----------------- |
| `fs.read` / `fs.write` / `fs.edit` | 读取、写入、编辑文件        |
| `shell.exec`                       | 执行终端命令            |
| `shell.process`                    | 管理运行中的进程          |
| `browser.*`                        | 自动控制浏览器（打开、截图、点击） |

### 智能功能

| 技能                             | 功能      |
| ------------------------------ | ------- |
| `web_search` / `web_fetch`     | 网页搜索与抓取 |
| `memory_search` / `memory_get` | 记忆搜索与读取 |
| `cron.*`                       | 定时任务、提醒 |
| `tts`                          | 文字转语音   |

## 八、常用命令

### 终端命令

| 命令                                    | 功能            |
| ------------------------------------- | ------------- |
| `openclaw onboard`                    | 运行安装向导        |
| `openclaw gateway start/stop/restart` | 启停 Gateway 服务 |
| `openclaw status`                     | 查看运行状态        |
| `openclaw doctor [--fix]`             | 诊断（与修复）配置     |
| `openclaw dashboard`                  | 打开 Web 控制面板   |
| `openclaw logs --follow`              | 查看实时日志        |
| `openclaw configure`                  | 修改配置          |
| `openclaw update`                     | 升级到最新版本       |

### 聊天命令

| 命令                | 功能        |
| ----------------- | --------- |
| `/help`           | 显示帮助      |
| `/new` / `/reset` | 新建 / 重置对话 |
| `/stop`           | 停止当前任务    |
| `/model <名称>`     | 切换模型      |
| `/think <级别>`     | 调整思考深度    |
| `/verbose on/off` | 详细模式开关    |
| `/skills`         | 查看可用技能    |

## 九、使用示例

直接用中文与 OpenClaw 对话即可：

```text theme={null}
> 帮我在桌面创建 test.txt，写入 "hello GravitexAI"
> 列出我桌面上的所有文件
> 打开浏览器访问 maas.gravitex.ai 并截图当前页面
> 每天早上 9 点提醒我喝水
> 帮我写一个 Python 脚本，批量重命名 ~/Pictures 下的所有图片
```

## 十、故障排查

<AccordionGroup>
  <Accordion title="401 / API Key 无效">
    * 重新检查 [GravitexAI 控制台](https://maas.gravitex.ai/#/keys) 中的密钥是否存在多余空格
    * 配置文件中 `apiKey` 字段必须完整，无中文符号
  </Accordion>

  <Accordion title="404 / 接口错误">
    * 确认 `baseUrl` 是否以 `/v1` 结尾（`openai-completions` 模式）
    * 若使用 `anthropic-messages`，`baseUrl` 应为 `https://api.gravitex.ai`（不带 `/v1`）
  </Accordion>

  <Accordion title="模型找不到">
    * 在 [模型市场](https://maas.gravitex.ai/#/models) 核对模型 ID
  </Accordion>

  <Accordion title="配置修改未生效">
    * 修改配置后必须执行 `openclaw gateway restart`
    * 可用 `openclaw doctor` 进行诊断
  </Accordion>
</AccordionGroup>