Linux / WSL2 | AiCodeCat Docs

🦞 什么是 OpenClaw？

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

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

📋 系统要求

Node.js: 18.0 或更高版本（建议 LTS）
npm: 包管理器
操作系统: Ubuntu 20.04+, Debian 11+, Fedora 35+, Arch Linux

🚀 安装步骤

1. 安装 Node.js

OpenClaw 需要 Node.js 环境。

Ubuntu / Debian

bash

# 使用 NodeSource 官方源（推荐）
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 或使用系统包管理器
sudo apt update
sudo apt install -y nodejs npm

Fedora / RHEL / CentOS

bash

# 使用 NodeSource 官方源
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo dnf install -y nodejs

# 或使用系统包管理器
sudo dnf install -y nodejs npm

Arch Linux

bash

sudo pacman -S nodejs npm

使用 nvm（推荐开发者）

bash

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重新加载 shell 配置
source ~/.bashrc  # 或 source ~/.zshrc

# 安装 Node.js LTS
nvm install --lts
nvm use --lts

验证安装

bash

node --version
npm --version

2. 安装 OpenClaw

bash

npm install -g openclaw@latest

验证安装：

bash

openclaw --version

权限问题

如遇权限错误，可使用 sudo：

bash

sudo npm install -g openclaw@latest

或配置 npm 使用用户目录（推荐）：

bash

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

⚙️ 配置 OpenClaw

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

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

步骤 1：先完成安装向导

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

https://github.com/openclaw/openclaw

运行安装向导：

bash

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_json=$(cat <<JSON
{
  "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
    }
  ]
}
JSON
)
openclaw config set models.providers.aicodecat-gpt --json "$provider_json"

步骤 3：设置默认模型

bash

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

步骤 4：重启 OpenClaw

bash

openclaw gateway restart
openclaw daemon restart

步骤 5：快速测试

bash

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

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

运行配置向导：

bash

openclaw onboard --install-daemon

按照提示选择：

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

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

获取 API 密钥

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

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

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

TIP

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

配置文件路径

~/.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"
    }
  }
}

创建配置文件

bash

# 创建目录（如不存在）
mkdir -p ~/.openclaw

# 使用编辑器创建配置文件
nano ~/.openclaw/openclaw.json
# 或使用 vim
vim ~/.openclaw/openclaw.json

粘贴上述配置内容，将 你的API密钥 替换为实际密钥后保存。

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

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

步骤 1：执行初始化配置

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

bash

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 命令进入配置菜单重新选择。

✅ 验证配置

运行配置验证命令：

bash

openclaw configure

查看可用模型：

bash

openclaw models list

🎯 启动 Gateway

启动 OpenClaw Gateway：

bash

openclaw gateway run

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

后台运行

使用 systemd 创建系统服务（推荐）：

bash

# 创建服务文件
sudo nano /etc/systemd/system/openclaw.service

内容：

ini

[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=your-username
ExecStart=/usr/bin/openclaw gateway run
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

启用并启动服务：

bash

sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw

# 查看状态
sudo systemctl status openclaw

🎉 开始使用

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

✅ 命令行界面 (CLI) - 直接在终端中与 AI 对话
✅ Web 界面 - 浏览器访问可视化界面
✅ IDE 集成 - VS Code、JetBrains 等编辑器插件
✅ SSH 远程 - 在服务器上运行并远程访问

祝您使用愉快！🦞

💡 常用命令

基础命令

bash

# 查看版本
openclaw --version

# 查看帮助
openclaw --help

# 查看日志
openclaw logs

Gateway 管理

bash

# 启动 Gateway
openclaw gateway run

# 停止 Gateway
openclaw gateway stop

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

# 查看 Gateway 状态
openclaw gateway status

模型管理

bash

# 列出所有模型
openclaw models list

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

🔧 故障排除

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

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

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

解决方案：

运行配置命令：
bash
```
openclaw configure
```
在菜单中选择 Gateway
选择 Regenerate token 重新生成认证令牌
重启 Gateway：
bash
```
openclaw gateway run
```

安全提示

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

⚠️ 常见问题

Q: 端口被占用？

A: 查找并终止占用进程：

bash

# 查找占用端口的进程
sudo lsof -i :18789
# 或使用 ss
ss -tlnp | grep :18789

# 终止进程
sudo kill -9 <PID>

Q: 防火墙配置？

A: 如需远程访问，配置防火墙规则：

bash

# UFW (Ubuntu/Debian)
sudo ufw allow 18789/tcp

# firewalld (Fedora/RHEL)
sudo firewall-cmd --permanent --add-port=18789/tcp
sudo firewall-cmd --reload

# iptables
sudo iptables -A INPUT -p tcp --dport 18789 -j ACCEPT
sudo iptables-save > /etc/iptables/rules.v4

Q: 权限被拒绝？

A: 检查文件权限：

bash

# 修复配置文件权限
chmod 600 ~/.openclaw/openclaw.json

# 修复目录权限
chmod 700 ~/.openclaw

Q: 如何卸载？

A: 完全卸载 OpenClaw：

bash

# 卸载全局包
npm uninstall -g openclaw

# 删除配置文件
rm -rf ~/.openclaw

# 如使用了 systemd 服务
sudo systemctl stop openclaw
sudo systemctl disable openclaw
sudo rm /etc/systemd/system/openclaw.service
sudo systemctl daemon-reload

需要帮助？

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

🦞 什么是 OpenClaw？ ​

📋 系统要求 ​

🚀 安装步骤 ​

1. 安装 Node.js ​

Ubuntu / Debian ​

Fedora / RHEL / CentOS ​

Arch Linux ​

使用 nvm（推荐开发者） ​

验证安装 ​

2. 安装 OpenClaw ​

⚙️ 配置 OpenClaw ​

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

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

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

步骤 3：设置默认模型 ​

步骤 4：重启 OpenClaw ​

步骤 5：快速测试 ​

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

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

获取 API 密钥 ​

配置文件路径 ​

完整配置示例 ​

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

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

步骤 2：选择 QuickStart 模式 ​

步骤 3：使用已有配置 ​

步骤 4：选择暂时跳过 ​

步骤 5：选择 aicodecat 提供商 ​

步骤 6：选择默认模型 ​

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

步骤 8：配置 Skills ​

步骤 9：选择包管理器 ​

步骤 10：选择需要的 Skills ​

步骤 11：跳过 API 配置 ​

步骤 12：启用 Hooks ​

步骤 13：选择启动方式 ​

步骤 14：安装 Shell Completion ​

🎉 配置完成 ​

✅ 验证配置 ​

🎯 启动 Gateway ​

🎉 开始使用 ​

💡 常用命令 ​

基础命令 ​

Gateway 管理 ​

模型管理 ​

🔧 故障排除 ​

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

⚠️ 常见问题 ​

Q: 端口被占用？ ​

Q: 防火墙配置？ ​

Q: 权限被拒绝？ ​

Q: 如何卸载？ ​

🦞 什么是 OpenClaw？

📋 系统要求

🚀 安装步骤

1. 安装 Node.js

Ubuntu / Debian

Fedora / RHEL / CentOS

Arch Linux

使用 nvm（推荐开发者）

验证安装

2. 安装 OpenClaw

⚙️ 配置 OpenClaw

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

步骤 1：先完成安装向导

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

步骤 3：设置默认模型

步骤 4：重启 OpenClaw

步骤 5：快速测试

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

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

获取 API 密钥

配置文件路径

完整配置示例

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

步骤 1：执行初始化配置

步骤 2：选择 QuickStart 模式

步骤 3：使用已有配置

步骤 4：选择暂时跳过

步骤 5：选择 aicodecat 提供商

步骤 6：选择默认模型

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

步骤 8：配置 Skills

步骤 9：选择包管理器

步骤 10：选择需要的 Skills

步骤 11：跳过 API 配置

步骤 12：启用 Hooks

步骤 13：选择启动方式

步骤 14：安装 Shell Completion

🎉 配置完成

✅ 验证配置

🎯 启动 Gateway

🎉 开始使用

💡 常用命令

基础命令

Gateway 管理

模型管理

🔧 故障排除

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

⚠️ 常见问题

Q: 端口被占用？

Q: 防火墙配置？

Q: 权限被拒绝？

Q: 如何卸载？