OpenClaw 安装与像素风可视化实践

安装时常见困难（实战记录）

在 macOS 环境里，OpenClaw 安装阶段最容易卡在 4 个点： 1）命令能执行但路径不在 PATH； 2）API Key 已创建但没有 export 到当前 shell； 3）代理 / 网络导致首次拉取资源超时； 4）可视化窗口能开但像素边缘发糊（默认缩放和过滤导致）。

建议先做环境体检再安装，优先验证「命令是否可见」「环境变量是否生效」「CLI 帮助是否可读」， 这样后续问题排查成本最低。

操作指南（推荐安装顺序）

以下顺序用于减少返工。具体安装命令请以你当前 OpenClaw 版本文档为准。

1. 检查基础环境：终端、网络、权限、可执行路径。
2. 安装 OpenClaw CLI（按官方发布方式安装）。
3. 用 --help 验证子命令是否可用。
4. 配置 API（临时 export 或写入 shell 配置文件）。
5. 启动 openclaw tui 并进行可视化参数设置。

安装完成后的基础验证：

openclaw --help
openclaw tui --help
which openclaw

API 配置分支（你提到的两种模式）

模式 A：没有提前配置环境变量，每次开新终端都需要手动 export：

export OPENCLAW_API_KEY="your_api_key"
export OPENCLAW_BASE_URL="https://your-api-endpoint"

# 可选：确认是否已注入当前 shell
echo "$OPENCLAW_API_KEY"

openclaw tui

模式 B：已经写入 shell 配置（例如 ~/.zshrc），直接启动：

openclaw tui

如果你希望长期生效，可写入 shell 配置文件后重载：

echo 'export OPENCLAW_API_KEY="your_api_key"' >> ~/.zshrc
echo 'export OPENCLAW_BASE_URL="https://your-api-endpoint"' >> ~/.zshrc
source ~/.zshrc

像素风可视化操作（TUI 内外两层）

目标是保证像素边缘清晰、缩放不抖动、不同分辨率下观感一致。实践中优先遵循： 整数倍缩放（2x/3x/4x）→ 关闭线性过滤（Nearest）→ 固定基准分辨率。

命令层建议先查看当前版本支持的可视化参数：

openclaw tui --help
openclaw viz --help

若你的版本支持可视化参数，可按下面思路设置（示例，按实际参数名替换）：

# 示例：优先整数缩放 + nearest 过滤 + 固定帧率
openclaw tui --scale 3 --filter nearest --fps 60

若你的版本采用 TUI 内部配置界面，建议在 Visualization / Render 设置里依次检查： Scale、Filtering、Grid/Overlay、Frame Limit、VSync。保存配置后再重启 TUI 验证是否生效。

排障速查

# 1) 命令找不到
which openclaw

# 2) Key 未注入
echo "$OPENCLAW_API_KEY"

# 3) 启动失败时先看帮助和版本
openclaw --help
openclaw --version

文档替换说明（等你新文件）

你重新提供的新文档发来后，我会直接替换下方内嵌 PDF 文件，不改页面结构和入口排序。

PDF 在线阅读

下面内嵌完整 PDF，可直接滚动阅读：