YL AI

Appearance

OpenClaw 从安装到入门的完全指南（2026-02-04） ​

版本说明：本文基于 OpenClaw 最新版本编写，最后更新：2026-02-04 适用平台：Windows（推荐 WSL2）、macOS、Linux

你可能已经体验过"AI 写得很像，但事还是得自己做"：邮件写好了还得你点发送，日历建议给了还得你自己改，Bug 分析完了还得你开 IDE 修。

OpenClaw 的定位更像一个"能动手的同事"：你在聊天里发一句话，它在你自己的机器上执行（读写文件、跑命令、调邮箱/日历/浏览器），然后把结果回你。

这篇文章只做一件事：带你从 0 安装到跑通第一个可用闭环，并把新手最容易踩的坑提前标出来。

🚀 快速通关路径（20 分钟） ​

如果你只想最快跑通，按这个顺序：

  1. 安装：curl -fsSL https://openclaw.ai/install.sh | bash
  2. 配置：openclaw onboard --install-daemon
    • 选择模型（Anthropic/Moonshot）
    • 选择 Telegram
    • 安装 daemon
  3. 配对：在 Telegram 私聊 bot，运行 openclaw pairing approve telegram
  4. 测试：发消息给 bot，看是否回复

详细说明见下文各章节。如果卡住，直接跳到 常见问题排查。

目录 ​

  1. 开装前先搞清楚：你要的是什么
  2. OpenClaw 架构全景：Gateway、Agent、Channels、Tools 如何协作
  3. 环境准备
  4. 安装 OpenClaw（两种路线）
  5. 首次配置：onboard 向导逐项填写指南（含命令行视图）
  6. 6. 接入 YL API (Huobao)：从获取 API Key 到验证
  7. 跑通最小闭环：从"能回复"到"真执行"
  8. 新手最佳实践：先只接一个能力
  9. 常见问题排查（80% 的问题在这里）
  10. 安全与隐私：越能干活越要克制
  11. 下一步：从"能用"到"好用"

1. 开装前先搞清楚：你要的是什么 ​

OpenClaw 不是"又一个聊天机器人"，更像一个自托管的个人智能体：

  • 入口：你用 Telegram / WhatsApp 等聊天应用发指令
  • 大脑：背后接一个大模型（可能是云端 API，也可能是本地模型）
  • 双手：在你机器上执行你授权过的动作（终端、浏览器、邮件、日历……）
  • 记忆：能跨会话保存配置与上下文（取决于你怎么部署与配置）

你装它的正确理由只有一个：你手上有一件重复、琐碎、需要切来切去的事，想用"发一句话"替代"打开 5 个 App 点 20 次"。

2. OpenClaw 架构全景：Gateway、Agent、Channels、Tools 如何协作 ​

在开始安装前，先理解 OpenClaw 的架构能帮你少走弯路。

核心组件 ​

┌─────────────────────────────────────────────────────────────┐
│                     你的聊天应用                              │
│  (Telegram / WhatsApp / Discord / Signal / WebChat)        │
└────────────────────┬──────────────────────────────────────┘
                      │ 消息流入/流出
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                    Gateway (守护进程)                         │
│  • 管理所有 Channels（Telegram、WhatsApp 等）                │
│  • 暴露 WebSocket API (默认 127.0.0.1:18789)                 │
│  • 处理配对（pairing）、认证、事件分发                        │
│  • 一个 Gateway 控制一台机器上的所有会话                      │
└────────────────────┬──────────────────────────────────────┘
                      │ RPC 调用
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                    Agent Runtime (智能体运行时)               │
│  • 维护会话（Session）与上下文（Context）                      │
│  • 执行 Agent Loop：接收消息 → 调用模型 → 执行工具 → 返回    │
│  • 管理持久记忆（Memory）                                     │
│  • 可配置多个 Agent（不同 workspace、不同模型）              │
└────────────────────┬──────────────────────────────────────┘
                      │ 工具调用
        ┌─────────────┼─────────────┬─────────────┐
        ▼             ▼             ▼             ▼
┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
│  Browser │  │   Exec   │  │   Web    │  │  Skills  │
│  (浏览器) │  │ (终端命令) │  │ (网页搜索) │  │ (插件)   │
└──────────┘  └──────────┘  └──────────┘  └──────────┘
        │             │             │             │
        └─────────────┴─────────────┴─────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                     Model Provider                           │
│  (Anthropic / OpenAI / Moonshot / 本地模型)                 │
└─────────────────────────────────────────────────────────────┘

数据流向（一次完整对话） ​

  1. 消息流入：你在 Telegram 发"清一下今天的邮件"
    • Gateway 接收消息 → 标准化为内部消息格式 → 路由到对应 Agent
  2. Agent Loop：
    • Agent 读取会话历史 + 系统提示词（System Prompt）
    • 调用模型 API（例如 moonshot/kimi-k2.5）
    • 模型返回"需要调用 Gmail API"
    • Agent 执行工具（例如 gmail.list）
    • 工具返回结果 → Agent 再次调用模型 → 生成回复
  3. 消息流出：Agent 的回复 → Gateway → Telegram → 你看到结果

关键概念 ​

  • Gateway：唯一的长驻进程（daemon），管理所有 Channels 和连接
    • 类比：Gateway 就像"总机"，所有消息都经过它
    • 位置：运行在后台，通过 systemd（Linux/WSL2）/ LaunchAgent（macOS）管理
    • 端口：默认 127.0.0.1:18789（WebSocket API）
  • Agent：处理对话逻辑的运行时，可以有多个（不同用途）
    • 类比：Agent 是"接线员"，负责理解你的意图并执行
    • 配置：每个 Agent 有独立的 workspace 和模型
    • 存储：配置在 ~/.openclaw/agents/<agent_id>/
  • Session：一次对话的上下文容器（跨消息保持）
    • 存储位置：~/.openclaw/agents/<agent_id>/sessions/
    • 生命周期：会话会被定期修剪（可配置保留策略）
    • 作用：让 Agent 记住之前的对话内容
  • Workspace：Agent 的工作目录（文件、脚本、配置）
    • 默认位置：~/.openclaw/workspace/
    • 用途：存放 Agent 创建/修改的文件、脚本、配置模板
    • 结构：包含 BOOT.md、IDENTITY.md、SOUL.md、TOOLS.md 等模板文件
  • Pairing：设备/用户配对机制，用于安全接入
    • 流程：首次连接 → 生成配对码（8位） → 用户批准 → 建立信任
    • 存储：~/.openclaw/credentials/*-pairing.json
    • 用途：防止陌生人把你的机器人当公共服务使用
  • Tools：Agent 能调用的能力（浏览器、终端、Skills）
    • 内置工具：browser（浏览器）、exec（终端命令）、web（网页搜索）
    • Skills：社区插件，扩展能力（如 Gmail、Calendar）
  • Channels：消息入口（Telegram、WhatsApp 等）
    • 作用：接收和发送消息
    • 配置：每个 Channel 需要对应的 Token/凭证

为什么需要 Gateway？ ​

Gateway 的设计让 OpenClaw 能：

  • 统一管理：一个进程控制所有聊天渠道
  • 多客户端：CLI、Web UI、macOS App 都连同一个 Gateway
  • 远程访问：通过 SSH 隧道或 Tailscale 访问远程 Gateway
  • 设备配对：iOS/Android 节点通过配对机制安全接入

配置文件位置 ​

类型路径
主配置~/.openclaw/openclaw.json
凭证~/.openclaw/credentials/（OAuth、API Keys）
会话~/.openclaw/agents/<agent_id>/sessions/
Workspace~/.openclaw/workspace/（默认）

3. 环境准备 ​

下面按"能跑起来优先"的顺序来。你不需要一次装齐所有东西，但缺关键依赖会导致安装/构建失败。

必备（所有平台） ​

  • Node.js：官方要求 Node >= 22
  • Git：走源码路线时需要
  • 可用的模型 API：比如 Anthropic / OpenAI / Moonshot 等（或你已有本地推理环境）

平台特定要求 ​

Windows ​

  • WSL2（强烈建议）：官方明确推荐 Windows 通过 WSL2（Ubuntu 推荐）运行；原生 Windows "未充分测试"，工具兼容性更差
  • PowerShell 5.1+ 或 PowerShell Core 7+（用于安装脚本）

如果你还没装 WSL2（可选，但很值得）：

PowerShell（管理员）：

powershell
wsl --install
# 或者指定发行版：
wsl --list --online
wsl --install -d Ubuntu-24.04

为 WSL2 开启 systemd：

bash
sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

回到 PowerShell 执行：

powershell
wsl --shutdown

再打开 Ubuntu 终端，验证：

bash
systemctl --user status

macOS ​

  • macOS 14+（如果要用 macOS 伴侣应用）
  • Xcode Command Line Tools（如果从源码构建）：xcode-select --install

Linux ​

  • systemd（用于 daemon 安装，大多数现代发行版已内置）
  • curl 或 wget（用于安装脚本）

可选（但强烈建议） ​

  • 密码/密钥管理习惯：至少做到"不要把 Key 直接写进公开文档/截图"
  • pnpm（如果从源码构建，推荐使用 pnpm）

开始前先做两条自检（30 秒） ​

bash
node -v
npm -v

预期输出：

v22.0.0  # 或更高版本
10.0.0   # npm 版本

如果 Node 版本 < 22，先升级再继续。否则后面你会在各种奇怪的地方卡住。

各平台升级 Node.js：

  • macOS：brew install node@22 或从 nodejs.org 下载
  • Linux/WSL2：使用 nvm 或从 nodejs.org 下载
  • Windows：从 nodejs.org 下载安装包

参考入口：官网 https://openclaw.ai/，官方文档 https://docs.openclaw.ai/（以最新为准）。

4. 安装 OpenClaw（两种路线） ​

路线 A：CLI 安装（推荐新手） ​

目标是：最少步骤，先跑通。

方式 1：一键安装脚本（推荐） ​

macOS / Linux / WSL2（bash）：

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

命令行输出示例：

🦞 OpenClaw Installer
─────────────────────────────────────

Detected platform: linux (WSL2)
Node version: v22.1.0 ✓
Installing openclaw@latest...
✓ Installed successfully

Next step: Run 'openclaw onboard --install-daemon'

Windows（PowerShell，原生，不推荐）：

powershell
iwr -useb https://openclaw.ai/install.ps1 | iex

注意：Windows 原生支持有限，强烈建议使用 WSL2。

方式 2：手动全局安装（你已经有 Node 时） ​

bash
npm install -g openclaw@latest

或者（如果你用 pnpm）：

bash
pnpm add -g openclaw@latest
pnpm approve-builds -g

安装后下一步（别跳过） ​

bash
openclaw onboard --install-daemon
openclaw doctor
openclaw dashboard

官方提示：如果你要用 WhatsApp 或 Telegram，Gateway 运行时建议使用 Node；Bun 在这些渠道上有已知问题。

路线 B：源码安装（适合想改代码的人） ​

目标是：能调试、能二次开发。

bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
openclaw onboard --install-daemon

5. 首次配置：onboard 向导逐项填写指南（含命令行视图） ​

新手最常见的失败不是"模型不聪明"，而是消息根本没到你的 OpenClaw。openclaw onboard 是官方推荐的配置方式，下面逐项说明每个步骤该怎么填、为什么这样填。

启动向导 ​

bash
openclaw onboard --install-daemon

命令行输出示例：

🦞 OpenClaw Onboarding Wizard
─────────────────────────────────────

Welcome! This wizard will help you set up OpenClaw.

Mode selection:
  [1] QuickStart (recommended for first-time users)
  [2] Advanced (full control over every setting)

Choose mode [1]:

选择建议：第一次用选 1（QuickStart），它会用合理的默认值；想完全控制选 2。

步骤 1：检测现有配置 ​

如果之前跑过，向导会检测到：

Found existing config at ~/.openclaw/openclaw.json

What would you like to do?
  [1] Keep existing config
  [2] Modify existing config
  [3] Reset (start fresh)

Choose [1-3] [1]:

选择建议：

  • 1：保留现有配置，只补充缺失项
  • 2：修改部分配置
  • 3：清空重来（会提示确认，包括是否删除凭证和会话）

步骤 2：选择模式（Local vs Remote） ​

Gateway mode:
  [1] Local (run Gateway on this machine)
  [2] Remote (connect to Gateway elsewhere)

Choose [1-2] [1]:

选择建议：第一次用选 1（Local）。Remote 模式只配置客户端连接，不安装 Gateway。

步骤 3：模型与认证（最重要） ​

这是最容易卡住的地方。向导会先检测环境变量：

Checking for existing API keys...
  ✓ Found ANTHROPIC_API_KEY in environment
  ✓ Found OPENAI_API_KEY in environment
  ✗ No MOONSHOT_API_KEY found

Authentication method:
  [1] Anthropic API Key (recommended)
  [2] Anthropic OAuth (Claude Code CLI)
  [3] Anthropic setup-token (paste)
  [4] OpenAI Code (Codex) subscription
  [5] OpenAI API Key
  [6] Moonshot (Kimi K2)
  [7] MiniMax M2.1
  [8] OpenCode Zen
  [9] Vercel AI Gateway
  [10] Synthetic
  [11] Skip (configure later)

Choose [1-11] [1]:

选择建议（按常见度）：

  • 1 Anthropic API Key：如果你有 Claude API Key
  • 6 Moonshot (Kimi K2)：如果你要用 Kimi
  • 2 Anthropic OAuth：如果你有 Claude Code 订阅

步骤 4：Workspace 配置 ​

Workspace location:
  Default: ~/.openclaw/workspace
  [1] Use default
  [2] Custom path

Choose [1-2] [1]:

选择建议：第一次用选 1。

步骤 5：Gateway 配置 ​

Gateway settings:
  Port: 18789
  Bind: 127.0.0.1 (loopback)
  Auth: Token (auto-generated)

  [1] Keep defaults
  [2] Customize

Choose [1-2] [1]:

选择建议：第一次用选 1。

步骤 6：渠道配置（Channels） ​

Channel setup:
  [1] Telegram
  [2] WhatsApp
  [3] Discord
  [4] Google Chat
  [5] Signal
  [6] Skip (configure later)

Choose channels (comma-separated, e.g., 1,3) [1]:

选择建议：第一次用选 1（Telegram），最简单。

输入 Token：粘贴你从 BotFather 拿到的 token（类似 123456789:ABCdefGHIjklMNOpqrsTUVwxyz）

步骤 7：Daemon 安装（后台服务） ​

Daemon installation:
  Install Gateway as a background service?
  This allows Gateway to run automatically on startup.

  [1] Yes (recommended)
  [2] No (run manually)

Choose [1-2] [1]:

选择建议：选 1，这样 Gateway 会在后台运行，重启后自动启动。

步骤 8：健康检查 ​

Running health check...
  Starting Gateway...
  ✓ Gateway started
  ✓ Health check passed
  ✓ Model API accessible
  ✓ Telegram channel connected

Status:
  Gateway: running (PID 12345)
  Port: 18789
  Channels: telegram (connected)
  Model: anthropic/claude-3.5-sonnet-20241022

步骤 9：Skills 安装（可选） ​

Skills installation:
  Skills are plugins that extend Agent capabilities.
  Recommended skills:
    - gmail (email management)
    - calendar (calendar integration)
    - web-search (Brave Search API)

  [1] Install recommended skills
  [2] Skip (install later)

Choose [1-2] [1]:

选择建议：第一次用可以选 2（跳过），先跑通基本流程再装 Skills。

步骤 10：完成 ​

  2. Test the connection:
     openclaw status
     openclaw health

  3. Open the dashboard:
     openclaw dashboard
     (or visit http://127.0.0.1:18789/)

  4. Configure skills (optional):
     openclaw configure --section web
     openclaw configure --section gmail

Config saved to: ~/.openclaw/openclaw.json

非交互模式（脚本/自动化） ​

bash
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice moonshot-api-key \
  --moonshot-api-key "$MOONSHOT_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills

注意：非交互模式的参数格式可能因 OpenClaw 版本而异。建议先运行 openclaw onboard --help 查看实际可用参数。

配置修改（后续调整） ​

如果后续想修改配置，用：

bash
openclaw configure

先用"最快路径"验证：不接任何渠道也能先聊天 ​

官方给的最快体验方式是直接开 Web 控制台（不需要先配 Telegram/WhatsApp）：

bash
openclaw dashboard

或直接打开 http://127.0.0.1:18789/（在 gateway 所在机器上）。

6. 接入 YL API (Huobao)：从获取 API Key 到验证 ​

步骤 1：获取 Huobao API Key ​

  1. 访问 Moonshot 官网：https://huobaoapi.com/
  2. 注册/登录账号
  3. 创建 API Key：进入控制台 → API Keys → 点击"令牌管理" → 复制 Key（格式类似 sk-...）

启动openclaw的配置程序

openclaw onboard

选择yes

*  I understand this is powerful and inherently risky. Continue?
|    > Yes /  No

选择quick Start

*  Onboarding mode
|  > QuickStart (Configure details later via openclaw configure.)
|    Manual

选择custom Provider

这里需要一直往下翻（小键盘下）

 Model/auth provider
|  > OpenAI (Codex OAuth + API key)
|    Anthropic
|    Chutes
|    vLLM
|    MiniMax
|    Moonshot AI (Kimi K2.5)
|    Google
|    xAI (Grok)
|    Mistral AI
|    Volcano Engine
|    BytePlus
|    OpenRouter
|    Qwen
|    Z.AI
|    Qianfan
|    Copilot
|    Vercel AI Gateway
|    OpenCode Zen
|    Xiaomi
|    Synthetic
|    Together AI
|    Hugging Face
|    Venice AI
|    LiteLLM
|    vLLM
|    MiniMax
|    Moonshot AI (Kimi K2.5)
|    Google
|    xAI (Grok)
|    Mistral AI
|    Volcano Engine
|    BytePlus
|    OpenRouter
|    Qwen
|    Z.AI
|    Qianfan
|    Copilot
|    Vercel AI Gateway
|    OpenCode Zen
|    Xiaomi
|    Synthetic
|    Together AI
|    Hugging Face
|    Venice AI
|    LiteLLM
|    Cloudflare AI Gateway
|  > Custom Provider (Any OpenAI or Anthropic compatible endpoint)
|    Skip for now

填写API Base URL (https://huobaoapi.com/v1)

o  API Base URL
|  https://huobaoapi.com/v1

填写你的API Key

API key的获取流程
1.登录 https://huobaoapi.com 
2.进入 (令牌管理)
3.添加令牌  --》 名称任意 --》 Anthropic Claude分组(这里看你使用什么模型就选择什么分组)
4.复制令牌填写

sk开头的密钥

o  API Key (leave blank if not required)
|  sk-z2c8yMCOY4JFc3pUy6RVImo2oXXnAn6UCoXxxxxxxx

选择是Anthropic 还是 OpenAI 的模型

*  Endpoint compatibility
|  > OpenAI-compatible (Uses /chat/completions)
|    Anthropic-compatible
|    Unknown (detect automatically)

除了 [Anthropic Claude] 和 [Claude] 分组 需要选择Anthropic-compatible ，其他的通通选择OpenAI-compatible , 我们演示的是Claude opus-4-6 所以我们选择Anthropic

o  Endpoint compatibility
|  Anthropic-compatible

选择你的Model ID ,这里填写的是模型名称 。 你需要去模型广场找到需要使用的模型名称。

我们这里演示的是 claude-opus-4-6

o  Model ID
|  claude-opus-4-6
|
o  Verification successful.

填写Endpoint ID 和model ID 一致

claude-opus-4-6

填写* Model alias (optional) 随意填写 也可以跳过

o  Model alias (optional)
|  c

上述就是YL API配置龙虾Key的全流程

7. 跑通最小闭环：从"能回复"到"真执行" ​

把它当成"新同事入职考核"，别一上来就让它接 Gmail、改生产库、开 PR。

第一步：确认它能稳定回复 ​

在聊天里发：

  • 「你是谁？你能做什么？」
  • 「把你当前的能力用 5 条列出来」

只要它稳定回复，说明聊天链路基本 OK。

第二步：做一个"低风险的执行任务" ​

挑一个不会造成损失的任务，例如：

  • 「告诉我现在的时间」
  • 「把我这段文字改成更清晰的三句话」（纯文本）
  • 「列出当前工作目录有哪些文件」（如果你允许它访问本机文件）

关键不是任务大小，而是看到这个闭环：

发消息 → 它执行（调用工具/读取环境） → 结构化返回结果

如果你卡在这一步，先跳到 常见问题排查。

0 成本的"官方自检三连"（强烈建议跑一次） ​

bash
openclaw status
openclaw health
openclaw security audit --deep

Gateway 运行方式说明：

  • openclaw gateway run：前台运行，便于调试，按 Ctrl+C 停止
  • openclaw gateway start：后台启动服务（需要先 openclaw gateway install）
  • openclaw gateway status：查看服务状态

想手动前台跑（便于看日志）：

bash
openclaw gateway run --port 18789 --verbose

8. 新手最佳实践：先只接一个能力 ​

OpenClaw 的上限很高，但新手最容易犯的错是"第一次就想全自动化人生"。

我的建议是：只接一个你明天就会用的能力，比如二选一：

  • 邮件：你每天要清收件箱。任务例子：「把今天所有促销类邮件标已读并归档」
  • 日历：你总忘看行程。任务例子：「把我明天的日程按时间顺序整理成 5 行摘要」

这样做的好处：

  • 可验证：你能立刻判断它做对没做对
  • 可收敛：出问题也好定位（邮箱问题就看邮箱链路）
  • 可控风险：权限越多，误操作代价越大

9. 常见问题排查（80% 的问题在这里） ​

1）发消息没反应 ​

场景 A：Telegram bot 完全没反应 ​

检查步骤：

  1. Gateway 是否在运行？

    bash
    openclaw gateway status

    如果显示 "not running"，启动它：

    bash
    openclaw gateway run --port 18789 --verbose

  2. Telegram channel 是否连接？

    bash
    openclaw channels status

    如果显示 "disconnected"，检查：

    • Token 是否正确（openclaw configure --section channels）
    • 网络是否可达 api.telegram.org（某些地区可能需要代理）

  3. Pairing 是否已批准？

    bash
    openclaw pairing list telegram

    如果有 pending 的配对码，批准它：

    bash
    openclaw pairing approve telegram ABC12345

场景 B：能收到配对码，但批准后仍无反应 ​

可能原因：Gateway 重启后配置丢失，或 Token 在配置文件中格式错误（多空格/引号）

bash
# 检查配置
openclaw doctor

# 重新配置 Telegram
openclaw configure --section channels

场景 C：Web UI 发消息没回复（Moonshot 中国区） ​

bash
openclaw config set models.providers.moonshot.baseUrl "https://api.moonshot.cn/v1"
openclaw gateway restart
openclaw agent --agent main --message "你好"

场景 D：PATH 配置问题（所有平台） ​

常见错误：bash: openclaw: command not found

Linux/macOS/WSL2：

bash
# 检查 openclaw 是否在 PATH
which openclaw

# 如果找不到，添加 npm global bin 到 PATH
export PATH="$(npm prefix -g)/bin:$PATH"

# 永久添加（添加到 ~/.bashrc 或 ~/.zshrc）
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell：

powershell
# 检查 openclaw 是否在 PATH
where.exe openclaw

# 如果找不到，添加 npm global bin 到 PATH
$npmPath = npm prefix -g
$env:Path += ";$npmPath"

# 永久添加
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$npmPath", "User")

场景 E：macOS 下 LaunchAgent 启动失败 ​

bash
# 检查服务状态
launchctl list | grep openclaw

# 查看日志
openclaw logs --follow

# 重新安装 daemon
openclaw configure --section gateway

常见问题：权限不足（在"系统设置 > 隐私与安全性"中授权）、环境变量未加载（检查 ~/.openclaw/.env）。

场景 F：Linux/WSL2 下 systemd 服务启动失败 ​

bash
# 检查服务状态
systemctl --user status openclaw-gateway

# Lingering 未启用（用户登出后服务停止）
sudo loginctl enable-linger $USER

# 重启服务
systemctl --user restart openclaw-gateway

2）能回复，但一执行就报错 ​

场景 A：模型 API 调用失败 ​

bash
openclaw health

解决步骤：验证 API Key 是否有效、检查环境变量、重新配置（openclaw configure --section models）。

场景 B：工具调用失败（缺权限） ​

常见错误：Error: Permission denied: /path/to/file

检查 sandbox 配置：

bash
openclaw sandbox explain

如果需要修改 sandbox 模式，编辑 ~/.openclaw/openclaw.json：

json
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "off"
      }
    }
  }
}

"off" = 主机运行，"non-main" = 仅非主会话沙箱，"all" = 全部沙箱

修改后重启 Gateway：openclaw gateway restart

场景 C：浏览器工具失败（缺依赖） ​

常见错误：Error: Browser launch failed: Chrome/Chromium not found

  • macOS：brew install --cask google-chrome
  • Linux/WSL2：sudo apt-get install chromium-browser
  • Windows：从 chrome.google.com 下载安装

3）它做了"你没让它做的事" ​

这通常不是"它叛变了"，而是：

  • 你的指令不够具体：例如"整理文件" vs "把 Downloads 文件夹里超过 30 天的文件移到 Archive"
  • 它在补全隐含步骤时做了错误假设

解决方法：

  1. 把目标、范围、禁止项写清楚
  2. 要求它先复述计划再执行
  3. 配置审批流程（见安全章节）

4）Gateway 启动失败 ​

场景 A：端口被占用 ​

错误信息：Error: Port 18789 is already in use

bash
# Linux/macOS/WSL2
lsof -i :18789

# Windows PowerShell
netstat -ano | findstr :18789

解决：杀死占用进程或改用其他端口。

场景 B：配置文件格式错误 ​

bash
openclaw doctor

如果 JSON 语法有误，修复或重置配置：

bash
openclaw reset
# 选择 "Config only" 保留凭证和会话

10. 安全与隐私：越能干活越要克制 ​

一句话原则：先当它是"会犯错的实习生"，再慢慢给权限。

最小权限原则 ​

OpenClaw 使用三层权限控制：Sandbox（运行位置）、Tool Policy（工具可用性）、Elevated（主机执行）。

先查看当前生效配置：

bash
openclaw sandbox explain

示例：限制工具可用性（只允许读取，不允许写入/删除）

编辑 ~/.openclaw/openclaw.json：

json
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      },
      "tools": {
        "allow": ["read", "exec"],
        "deny": ["write", "delete", "edit"],
        "sandbox": {
          "tools": {
            "allow": ["read", "exec"],
            "deny": ["write", "delete"]
          }
        }
      }
    }
  }
}

逐步开放权限：

  1. 第一阶段：只允许文本处理（allow: ["read"]，禁用 exec）
  2. 第二阶段：允许读取和执行（allow: ["read", "exec"]，禁用 write）
  3. 第三阶段：允许写入特定目录（通过 Sandbox bind mounts 限制范围）
  4. 最后阶段：根据信任度开放更多权限

验证配置生效：

bash
openclaw sandbox explain --agent main

修改后重启 Gateway：openclaw gateway restart

不暴露公网 ​

检查当前绑定：

bash
openclaw status --all | grep "Bind"

如果显示 0.0.0.0，改为 127.0.0.1：

bash
openclaw configure --section gateway
# 选择 bind: 127.0.0.1 (loopback)

如果需要远程访问，使用 SSH 隧道，不要直接暴露端口：

bash
# 在本地机器执行
ssh -N -L 18789:127.0.0.1:18789 user@remote-host

# 然后访问 http://127.0.0.1:18789/（实际连接到远程 Gateway）

或使用 Tailscale（官方推荐）：

bash
openclaw configure --section gateway
# 选择 "Enable Tailscale exposure"

敏感信息管理 ​

不要做的事：

  • 在 Telegram 对话中直接发 API Key
  • 把 Key 写进公开的配置文件（如 GitHub）
  • 截图时暴露 Token
  • 在日志中打印完整 Key

正确做法：

  1. 使用环境变量：

    bash
    # Linux/macOS/WSL2
export MOONSHOT_API_KEY="sk-..."

# Windows PowerShell
$env:MOONSHOT_API_KEY="sk-..."

  2. 使用 ~/.openclaw/.env（daemon 会自动读取）：

    bash
    echo "MOONSHOT_API_KEY=sk-..." >> ~/.openclaw/.env

  3. 定期轮换 API Key：每月检查一次 Key 使用情况，发现异常立即轮换。

高风险动作二次确认 ​

OpenClaw 使用 exec-approvals.json 文件管理需要审批的命令。

bash
# 查看当前配置
openclaw approvals get

# 添加危险命令到审批列表
openclaw approvals allowlist add "rm -rf"
openclaw approvals allowlist add "/usr/bin/dd"
openclaw approvals allowlist add "~/.scripts/dangerous.sh"

或从文件批量导入审批规则：

json
{
  "allowlist": [
    "rm -rf",
    "/usr/bin/dd",
    "~/.scripts/dangerous.sh"
  ]
}
bash
openclaw approvals set --file ./exec-approvals.json

配置后，执行这些命令时 Agent 会先请求批准，在 Telegram/Dashboard 中会显示审批按钮。

注意：审批机制仅适用于 exec 工具。文件删除、写入等操作需要通过 Sandbox 配置和 Tool Policy 控制。

定期安全检查 ​

bash
openclaw security audit --deep

其他安全建议 ​

  1. 定期更新：

    bash
    openclaw update

  2. 审查日志：

    bash
    # 实时查看日志并过滤错误
openclaw logs --follow | grep -i "error\|warning\|unauthorized"

    Windows PowerShell：

    powershell
    openclaw logs --follow | Select-String -Pattern "error|warning|unauthorized" -CaseSensitive:$false

  3. 备份配置：

    Linux/macOS/WSL2：

    bash
    # 备份配置（不包含敏感 Key）
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

# 备份整个配置目录（排除会话和临时文件）
tar -czf ~/openclaw-backup-$(date +%Y%m%d).tar.gz \
  ~/.openclaw/openclaw.json \
  ~/.openclaw/credentials/ \
  --exclude='*.log' \
  --exclude='sessions/'

    Windows PowerShell：

    powershell
    Copy-Item ~\.openclaw\openclaw.json ~\.openclaw\openclaw.json.backup

$backupName = "openclaw-backup-$(Get-Date -Format 'yyyyMMdd').zip"
Compress-Archive -Path ~\.openclaw\* -DestinationPath ~\$backupName -Exclude *.log,sessions

  4. 监控使用情况：定期检查 API 调用量，设置使用上限（在模型提供商控制台），发现异常立即停止服务。

OpenClaw 的价值是"自托管可控"，但"可控"的另一面是你需要对权限负责。

YL AI

Copyright © 2024-present