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

# OpenClaw 手动安装

> 手动安装和配置 OpenClaw 并连接 AihubMax

## 概述

[OpenClaw](https://github.com/open-claw/open-claw) 是一个开源的 AI Agent 网关，用于将聊天应用桥接到 AI 编程 Agent。它支持多种 AI 模型提供商和 API 格式，让你可以通过统一的网关连接 Claude Code、Cursor 等 AI 编程工具。

本指南将引导你从零开始手动安装 OpenClaw 并将其连接到 AihubMax。

<Info>
  如果你希望更快速地完成安装，可以参考 [OpenClaw 一键安装](/zh/integration-guide/openclaw-auto) 指南。
</Info>

## 前置条件

<CardGroup cols={2}>
  <Card title="AihubMax API Key" icon="key">
    一个有效的 AihubMax API Key。
  </Card>

  <Card title="Node.js" icon="node-js">
    Node.js >= 22.12.0。
  </Card>

  <Card title="npm" icon="npm">
    npm（随 Node.js 一同安装）。
  </Card>

  <Card title="Git" icon="git">
    已安装 Git。
  </Card>
</CardGroup>

## 安装与配置

<Steps>
  <Step title="安装 OpenClaw">
    通过 npm 全局安装 OpenClaw：

    ```bash theme={null}
    npm install -g openclaw@latest
    ```
  </Step>

  <Step title="验证安装">
    确认 OpenClaw 已正确安装：

    ```bash theme={null}
    openclaw --version
    ```
  </Step>

  <Step title="运行初始化">
    运行 onboarding 命令以初始化 OpenClaw 并安装后台守护进程：

    ```bash theme={null}
    openclaw onboard --install-daemon
    ```

    该命令会创建配置目录和默认配置文件。
  </Step>

  <Step title="配置模型提供商">
    编辑主配置文件，添加 AihubMax 作为模型提供商。

    <Tabs>
      <Tab title="macOS / Linux">
        ```bash theme={null}
        ~/.openclaw/openclaw.json
        ```
      </Tab>

      <Tab title="Windows">
        ```bash theme={null}
        %USERPROFILE%\.openclaw\openclaw.json
        ```
      </Tab>
    </Tabs>

    在 `models.providers` 部分，添加以下三个提供商配置块（分别对应不同的 API 格式）：

    ```json theme={null}
    {
      "models": {
        "providers": {
          "foxapi-anthropic": {
            "api": "anthropic-messages",
            "baseUrl": "https://api.aihubmax.com",
            "apiKey": "sk-your-foxapi-api-key",
            "models": [
              { "id": "claude-opus-4-6", "name": "Claude Opus 4.6" },
              { "id": "claude-sonnet-4-20250514", "name": "Claude Sonnet 4" }
            ]
          },
          "foxapi-google": {
            "api": "google-generative-ai",
            "baseUrl": "https://api.aihubmax.com/v1beta",
            "apiKey": "sk-your-foxapi-api-key",
            "models": [
              { "id": "gemini-2.5-pro", "name": "Gemini 2.5 Pro" },
              { "id": "gemini-2.5-flash", "name": "Gemini 2.5 Flash" }
            ]
          },
          "foxapi-openai": {
            "api": "openai-completions",
            "baseUrl": "https://api.aihubmax.com/v1",
            "apiKey": "sk-your-foxapi-api-key",
            "models": [
              { "id": "gpt-4o", "name": "GPT-4o" },
              { "id": "deepseek-chat", "name": "DeepSeek V3" }
            ]
          }
        }
      }
    }
    ```

    <Warning>
      请将所有三个提供商配置块中的 `sk-your-foxapi-api-key` 替换为你的实际 AihubMax API Key。
    </Warning>
  </Step>

  <Step title="配置默认 Agent 模型">
    编辑 Agent 模型配置文件以设置默认模型：

    <Tabs>
      <Tab title="macOS / Linux">
        ```bash theme={null}
        ~/.openclaw/agents/main/agent/models.json
        ```
      </Tab>

      <Tab title="Windows">
        ```bash theme={null}
        %USERPROFILE%\.openclaw\agents\main\agent\models.json
        ```
      </Tab>
    </Tabs>

    在 `agents` 字段中设置主模型：

    ```json theme={null}
    {
      "model": {
        "primary": "foxapi-anthropic/claude-opus-4-6"
      }
    }
    ```

    格式为 `<提供商名称>/<模型ID>`。
  </Step>
</Steps>

## 验证连接

1. 切换到指定模型以确认其可用：
   ```bash theme={null}
   openclaw model switch foxapi-anthropic/claude-opus-4-6
   ```
2. 启动与 Agent 的对话，测试连接是否正常。
3. 如果能正常收到响应，说明 AihubMax 集成已成功。

## 切换模型

你可以随时使用以下命令切换当前活跃模型：

```bash theme={null}
openclaw model switch <提供商>/<模型ID>
```

示例：

```bash theme={null}
# 切换到 Claude Sonnet 4
openclaw model switch foxapi-anthropic/claude-sonnet-4-20250514

# 切换到 Gemini 2.5 Pro
openclaw model switch foxapi-google/gemini-2.5-pro

# 切换到 GPT-4o
openclaw model switch foxapi-openai/gpt-4o
```

## 常见问题

<AccordionGroup>
  <Accordion title="找不到 openclaw 命令">
    * 确认 Node.js 版本 >= 22.12.0：`node --version`
    * 重新安装 OpenClaw：`npm install -g openclaw@latest`
    * 检查 npm 全局 bin 目录是否在系统 `PATH` 中。
  </Accordion>

  <Accordion title="无法连接到 AI 模型">
    * 检查 `openclaw.json` 中的 `apiKey` 和 `baseUrl` 是否正确。
    * 确认各 API 格式对应的 Base URL：
      * Anthropic：`https://api.aihubmax.com`
      * Google：`https://api.aihubmax.com/v1beta`
      * OpenAI：`https://api.aihubmax.com/v1`
    * 使用 curl 测试 API Key 是否有效：
      ```bash theme={null}
      curl https://api.aihubmax.com/v1/models \
        -H "Authorization: Bearer sk-your-foxapi-api-key"
      ```
  </Accordion>

  <Accordion title="模型切换失败">
    * 确认提供商名称和模型 ID 与 `openclaw.json` 中定义的完全一致。
    * 格式必须为 `<提供商>/<模型ID>`，例如 `foxapi-anthropic/claude-opus-4-6`。
  </Accordion>

  <Accordion title="守护进程未运行">
    * 重新运行初始化命令：`openclaw onboard --install-daemon`
    * 检查系统日志获取守护进程错误信息。
  </Accordion>
</AccordionGroup>