AiCodeCat Docs

主题

🦞 什么是 OpenClaw？ ​

OpenClaw 是一个强大的 AI 编程助手框架，支持：

  • 🤖 多模型统一管理（GPT、Claude、Gemini）
  • 🧠 扩展思考（Extended Thinking）功能
  • 🔌 插件系统和 MCP 服务支持
  • 🌐 本地/远程 Gateway 模式
  • 📝 代码审查、自动化测试等内置功能

📋 系统要求 ​

  • Node.js: 18.0 或更高版本（建议 LTS）
  • npm: 包管理器
  • 操作系统: Windows 10/11

🚀 安装步骤 ​

1. 安装 Node.js ​

OpenClaw 需要 Node.js 环境。

方法一：官网下载（推荐） ​

  1. 访问 Node.js 官网 下载 LTS 版本
  2. 双击安装包并按向导完成安装

方法二：包管理器安装 ​

powershell
# Chocolatey
choco install nodejs-lts

# Scoop
scoop install nodejs-lts

验证安装 ​

powershell
node --version
npm --version

TIP

建议使用 PowerShell；如遇权限问题可尝试以管理员身份运行。

2. 安装 OpenClaw ​

powershell
npm install -g openclaw@latest

验证安装：

powershell
openclaw --version

⚙️ 配置 OpenClaw ​

方法一：快速配置（推荐，5 分钟跑通） ​

适用场景：已完成 OpenClaw 安装，希望先快速接入 AiCodeCat Codex 渠道。

步骤 1：先完成安装向导 ​

安装步骤请参考 OpenClaw 官方最新文档：

https://github.com/openclaw/openclaw

运行安装向导：

powershell
openclaw onboard --install-daemon

建议选择：

  • Model/auth provider：Skip for now
  • Filter models by provider：任意选择（后续会覆盖）
  • Select channel (QuickStart)：Skip for now
  • Configure skills now?：No
  • How do you want to hatch your bot?：Open the Web UI

访问 http://127.0.0.1:18789/overview，确认显示 Connected 后再进行下一步。

步骤 2：快速配置 Provider（替换为你的 API Key） ​

先在 API 密钥管理页面 创建密钥，然后执行：

$provider = @"
{
  "baseUrl": "https://aicode.cat/v1",
  "apiKey": "你的API密钥",
  "api": "openai-responses",
  "models": [
    {
      "id": "gpt-5.3-codex",
      "name": "GPT-5.3 Codex",
      "api": "openai-responses",
      "reasoning": true,
      "input": ["text", "image"],
      "contextWindow": 200000,
      "maxTokens": 65536
    }
  ]
}
"@
openclaw config set "models.providers.aicodecat-gpt" --json $provider

步骤 3：设置默认模型 ​

powershell
openclaw config set models.mode merge
openclaw models set 'aicodecat-gpt/gpt-5.3-codex'

步骤 4：重启 OpenClaw ​

powershell
openclaw gateway restart
openclaw daemon restart

步骤 5：快速测试 ​

powershell
openclaw agent --local -m "你好，你是谁，基于什么模型" --agent main

方法二：交互式配置（推荐新手） ​

运行配置向导：

powershell
openclaw onboard --install-daemon

按照提示选择：

  • ✅ 选择 "quick start" 快速开始
  • ✅ 选择您的 API 提供商
  • ✅ 选择默认模型
  • ✅ 配置技能和钩子

方法三：手动创建配置文件（推荐高级用户） ​

获取 API 密钥 ​

在配置 OpenClaw 之前，您需要先从平台获取 API 密钥。

本平台支持同时接入 Claude、OpenAI、Google 三个厂家的大模型。您需要为每个厂家分别生成独立的 API Key：

  1. 访问 API 密钥管理页面
  2. 点击"创建密钥"按钮
  3. 选择服务类型/分组：
    • Claude：选择 Claude 相关服务
    • OpenAI：选择 OpenAI/Codex 相关服务
    • Google：选择 Google/Gemini 相关服务
  4. 为每个密钥设置易于识别的名称（如"OpenClaw-Claude"、"OpenClaw-OpenAI"、"OpenClaw-Google"）
  5. 生成后妥善保存三个密钥，稍后将分别填入配置文件

TIP

建议为每个服务生成独立的密钥，便于后续管理和追踪使用情况。

配置文件路径 ​

C:\Users\<你的用户名>\.openclaw\openclaw.json

完整配置示例 ​

创建上述路径的配置文件，并填入以下内容：

{
  "models": {
    "mode": "merge",
    "providers": {
      "aicodecat-gpt": {
        "baseUrl": "https://aicode.cat/v1",
        "apiKey": "你的API密钥",
        "auth": "api-key",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5.3-codex",
            "name": "GPT-5.3 Codex",
            "reasoning": true,
            "input": ["text", "image"],
            "cost": {
              "input": 1.75,
              "output": 14,
              "cacheRead": 0.175,
              "cacheWrite": 0
            },
            "contextWindow": 400000,
            "maxTokens": 128000
          },
          {
            "id": "gpt-5.2",
            "name": "GPT-5.2",
            "reasoning": true,
            "input": ["text", "image"],
            "cost": {
              "input": 1.75,
              "output": 14,
              "cacheRead": 0.175,
              "cacheWrite": 0
            },
            "contextWindow": 400000,
            "maxTokens": 128000
          }
        ]
      },
      "aicodecat-claude": {
        "baseUrl": "https://aicode.cat",
        "apiKey": "你的API密钥",
        "auth": "api-key",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-sonnet-4-5-20250929",
            "name": "Claude Sonnet 4.5",
            "reasoning": true,
            "input": ["text", "image"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 200000,
            "maxTokens": 64000
          },
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6",
            "reasoning": true,
            "input": ["text", "image"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 200000,
            "maxTokens": 64000
          }
        ]
      },
      "aicodecat-gemini": {
        "baseUrl": "https://aicode.cat/v1beta",
        "apiKey": "你的API密钥",
        "auth": "api-key",
        "api": "google-generative-ai",
        "models": [
          {
            "id": "gemini-3-pro-preview",
            "name": "Gemini 3 Pro Preview",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 1048576,
            "maxTokens": 65536
          },
          {
            "id": "gemini-3-flash-preview",
            "name": "Gemini 3 Flash Preview",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 1048576,
            "maxTokens": 65536
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "fallbacks": [
          "aicodecat-gpt/gpt-5.3-codex",
          "aicodecat-claude/claude-sonnet-4-5-20250929",
          "aicodecat-gemini/gemini-3-pro-preview"
        ],
        "primary": "aicodecat-claude/claude-opus-4-6"
      },
      "models": {
        "aicodecat-gpt/gpt-5.3-codex": {
          "alias": "GPT-5.3 Codex"
        },
        "aicodecat-gpt/gpt-5.2": {
          "alias": "GPT-5.2"
        },
        "aicodecat-claude/claude-opus-4-6": {
          "alias": "Claude Opus 4.6"
        },
        "aicodecat-claude/claude-sonnet-4-5-20250929": {
          "alias": "Claude Sonnet 4.5"
        },
        "aicodecat-gemini/gemini-3-pro-preview": {
          "alias": "Gemini 3 Pro Preview"
        },
        "aicodecat-gemini/gemini-3-flash-preview": {
          "alias": "Gemini 3 Flash Preview"
        }
      },
      "thinkingDefault": "high",
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token"
    }
  }
}

将上述模板内容填写好 key 并添加到配置文档中之后 ​

完成配置文件填写后，需要执行初始化配置和后续设置步骤。

步骤 1：执行初始化配置 ​

运行 onboard 命令安装守护进程：

powershell
openclaw onboard --install-daemon

系统将显示安全警告，选择 Yes 继续。

确认安全警告

安全提示

OpenClaw 是一个强大的工具，请确保您理解其权限范围。建议在受控环境中使用，并遵循安全最佳实践。

步骤 2：选择 QuickStart 模式 ​

在 Onboarding mode 界面，选择 QuickStart（稍后可通过 openclaw configure 配置详细设置）。

选择 QuickStart

步骤 3：使用已有配置 ​

在 Existing config detected 界面，选择 Use existing values（使用已有配置）。

选择 Use existing values

系统将读取您之前创建的配置文件内容。

步骤 4：选择暂时跳过 ​

在 Model/auth provider 列表中，滚动到最下方选择 Skip for now。

选择 Skip for now

步骤 5：选择 aicodecat 提供商 ​

在 Filter models by provider 界面，选择 aicodecat-gpt（推荐）。

也可以选择：

  • aicodecat-claude - Claude 模型
  • aicodecat-gemini - Gemini 模型

选择 aicodecat-gpt

推荐选择 aicodecat-gpt

GPT-5.2 系列模型具有最强的推理能力和代码生成质量。

步骤 6：选择默认模型 ​

在模型列表中选择 aicodecat-gpt/gpt-5.2。

选择 gpt-5.2 模型

模型选择建议

  • gpt-5.2: 通用任务，高推理能力
  • gpt-5.3-codex: 专注代码生成和调试

步骤 7：暂时跳过频道配置 ​

在 Select channel 界面，选择 Skip for now（稍后可通过 openclaw channels add 添加）。

暂时跳过频道

频道说明

频道用于将 OpenClaw 连接到 Telegram、Discord、Slack 等通讯工具。如果暂时不需要，可以跳过此步骤。

步骤 8：配置 Skills ​

系统询问是否配置 Skills，选择 Yes。

配置 Skills

什么是 Skills？

Skills 是 OpenClaw 的扩展功能模块，提供额外的能力（如 GitHub 集成、PDF 处理、笔记管理等）。

步骤 9：选择包管理器 ​

选择 npm 作为 Skills 的包管理器。

选择 npm

步骤 10：选择需要的 Skills ​

在 Skills 列表中，使用空格键选择需要的功能，选择完成后按回车键确认。

Skills 列表

推荐选择（基础功能）：

  • blogwatcher - 监控/阅读博客和 RSS 订阅
  • clawhub - ClawHub 文档和技能管理
  • mcporter - MCP 服务器管理工具
更多 Skills 说明（点击展开）

开发者推荐：

  • github - GitHub 仓库操作（issue、PR、代码搜索）
  • nano-pdf - PDF 文件处理
  • summarize - 文本摘要工具

笔记管理：

  • obsidian - Obsidian 笔记集成
  • apple-notes - Apple 备忘录（Mac 用户）
  • bear-notes - Bear 笔记应用

内容创作：

  • openai-image-gen - AI 图像生成
  • openai-whisper - 语音转文字
  • video-frames - 视频帧提取

其他工具：

  • 1password - 密码管理器集成
  • himalaya - 邮件客户端
  • things-mac - Things 任务管理

大部分 Skills 可以先跳过，需要时再通过 openclaw skills install 单独安装。

选择完成后，系统将开始安装依赖，请耐心等待（可能需要几分钟）。

步骤 11：跳过 API 配置 ​

系统会询问是否配置各种第三方 API（Google Places、Gemini、Notion 等），全部选择 No。

跳过 API 配置

TIP

这些 API 用于特定 Skills 的高级功能，暂时用不上可以跳过。

步骤 12：启用 Hooks ​

在 Enable hooks 界面，全部启用（使用空格键选择）：

  • boot-md - Gateway 启动时运行
  • command-logger - 记录所有命令事件
  • session-memory - 保存会话上下文

启用 Hooks

Hooks 说明

Hooks 可以自动化执行任务，例如在启动时加载配置、记录操作日志、保存会话历史等。

步骤 13：选择启动方式 ​

在 How do you want to hatch your bot 界面，选择 Open the Web UI。

选择 Web UI

系统将自动在浏览器中打开 OpenClaw 的 Web 界面。

步骤 14：安装 Shell Completion ​

最后询问是否安装 Shell 自动补全脚本，选择 Yes。

安装 Shell Completion

TIP

Shell Completion 可以让你在命令行中使用 Tab 键自动补全 OpenClaw 命令。

🎉 配置完成 ​

恭喜！OpenClaw 已成功配置完成。浏览器将自动打开 Dashboard 页面，您可以开始使用 OpenClaw 进行 AI 对话和代码开发。

后续重新配置

如需修改任何配置项，可以随时使用 openclaw configure 命令进入配置菜单重新选择。

🔑 配置说明 ​

API 提供商配置 ​

每个 provider 包含：

  • baseUrl: API 服务地址
  • apiKey: 您的 API 密钥
  • auth: 认证方式（固定为 \"api-key\"）
  • api: API 类型
    • openai-responses - OpenAI 兼容接口
    • anthropic-messages - Claude 模型
    • google-generative-ai - Gemini 模型

推理功能配置 ​

thinkingDefault（思考强度） ​

json
"thinkingDefault": "high"

可选值：

  • \"off\" - 关闭
  • \"minimal\" - 最小
  • \"low\" - 低
  • \"medium\" - 中
  • \"high\" - 高（推荐）
  • \"xhigh\" - 超高（仅 GPT-5.2/Codex 支持）

reasoning（模型支持） ​

每个模型的 reasoning 属性表示是否支持推理功能：

  • GPT-5.2 系列: true ✅
  • Claude Sonnet 4.5 / Opus 4.6: true ✅
  • Gemini 系列: false ❌

模型选择 ​

  • primary: 主要使用的模型
  • fallbacks: 降级备用模型列表（当主模型不可用时自动切换）
  • alias: 模型的显示名称

✅ 验证配置 ​

运行配置验证命令：

powershell
openclaw configure

查看可用模型：

powershell
openclaw models list

🎯 启动 Gateway ​

启动 OpenClaw Gateway：

powershell
openclaw gateway run

默认地址：ws://127.0.0.1:18789

后台运行

如需后台运行，可使用：

powershell
openclaw gateway run --daemon

🎉 开始使用 ​

配置完成后，您可以通过以下方式使用 OpenClaw：

  • ✅ 命令行界面 (CLI) - 直接在终端中与 AI 对话
  • ✅ Web 界面 - 浏览器访问可视化界面
  • ✅ IDE 集成 - VS Code、JetBrains 等编辑器插件
  • ✅ Telegram Bot - 移动端随时使用
  • ✅ API 调用 - 集成到您的应用程序中

祝您使用愉快！🦞

💡 常用命令 ​

基础命令 ​

powershell
# 查看版本
openclaw --version

# 查看帮助
openclaw --help

# 查看日志
openclaw logs

Gateway 管理 ​

powershell
# 启动 Gateway
openclaw gateway run

# 停止 Gateway
openclaw gateway stop

# 重启 Gateway
openclaw gateway stop && openclaw gateway run

# 查看 Gateway 状态
openclaw gateway status

模型管理 ​

powershell
# 列出所有模型
openclaw models list

# 查看模型详情
openclaw models show <model-name>

# 测试模型连接
openclaw models test <model-name>

插件管理 ​

powershell
# 列出已安装插件
openclaw plugins list

# 安装插件
openclaw plugins install <plugin-name>

# 启用插件
openclaw plugins enable <plugin-name>

# 禁用插件
openclaw plugins disable <plugin-name>

🔧 进阶配置 ​

启用推理可见性 ​

在 OpenClaw 会话中，发送命令查看思考过程：

/reasoning on

关闭推理可见性：

/reasoning off

TIP

推理功能始终在后台运行（如果 thinkingDefault 已设置）， /reasoning 命令只是控制是否显示思考过程。

自定义工作空间 ​

修改配置文件中的 workspace 路径：

json
{
  "agents": {
    "defaults": {
      "workspace": "D:\\MyProjects\\OpenClawWorkspace"
    }
  }
}

并发控制 ​

json
{
  "agents": {
    "defaults": {
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  }
}
  • maxConcurrent: 主代理最大并发数
  • subagents.maxConcurrent: 子代理最大并发数

远程 Gateway 模式 ​

如需在其他设备访问 Gateway：

json
{
  "gateway": {
    "port": 18789,
    "mode": "remote",
    "bind": "0.0.0.0",
    "auth": {
      "mode": "token",
      "token": "your-custom-token-here"
    }
  }
}

安全提示

远程模式下请务必设置强密码 token，并配置防火墙规则。

🔧 故障排除 ​

错误：Gateway auth is set to token, but no token is configured ​

如果启动 Gateway 时遇到此错误：

Error: Gateway auth is set to token, but no token is configured.

解决方案：

  1. 运行配置命令：

    powershell
    openclaw configure

  2. 在菜单中选择 Gateway

  3. 选择 Regenerate token 重新生成认证令牌

  4. 重启 Gateway：

    powershell
    openclaw gateway run

安全提示

生成的 token 会保存在配置文件中，请妥善保管。如需远程访问，建议设置强密码 token。

⚠️ 常见问题 ​

Q: 配置文件验证失败？ ​

A: 检查 JSON 格式是否正确：

  1. 确保所有引号、逗号、括号匹配
  2. 使用在线 JSON 验证器检查语法
  3. 注意最后一个属性后不要有多余的逗号
powershell
# 验证配置
openclaw configure

Q: 无法连接到 Gateway？ ​

A: 排查步骤：

  1. 确保 Gateway 已启动：

    powershell
    openclaw gateway run

  2. 检查端口是否被占用：

    powershell
    netstat -ano | findstr :18789

  3. 检查防火墙设置，确保允许端口 18789

  4. 查看错误日志：

    powershell
    openclaw logs

Q: 模型调用失败？ ​

A: 检查清单：

  1. ✅ 验证 API Key 是否正确
  2. ✅ 检查网络连接
  3. ✅ 确认 API 额度是否充足
  4. ✅ 验证 baseUrl 是否正确
  5. ✅ 查看详细错误信息：
    powershell
    openclaw logs --tail 50

Q: 思考功能不生效？ ​

A: 解决方案：

  1. 确认模型支持推理功能（reasoning: true）
  2. 检查配置中 thinkingDefault 是否设置
  3. 在会话中发送 /reasoning on 查看推理过程
  4. 重启 Gateway 使配置生效

TIP

只有 GPT-5.2、GPT-5.3 Codex 和 Claude Sonnet 4.5 / Opus 4.6 支持推理功能。

Q: 如何切换模型？ ​

A: 在会话中使用命令：

/model aicodecat-gpt/gpt-5.3-codex

或修改配置文件中的 primary 字段：

json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "aicodecat-gpt/gpt-5.3-codex"
      }
    }
  }
}

Q: 如何更新 OpenClaw？ ​

A: 运行更新命令：

powershell
npm update -g openclaw@latest

验证更新：

powershell
openclaw --version

📚 参考资源 ​

需要帮助？

如遇到问题，请访问 AiCodeCat 支持中心 获取技术支持。