AI 实战文档

Appearance

FAQ（基于官方 Help/FAQ 主题） ​

Q1：最快怎么跑通首个可用环境？ ​

优先走官方路径：安装脚本 -> openclaw onboard --install-daemon -> openclaw gateway status -> openclaw dashboard。

参考：

快速检查清单 ​

bash
# 1. 检查安装
openclaw --version

# 2. 检查网关状态
openclaw gateway status

# 3. 检查配置
openclaw config list

# 4. 启动 Dashboard
openclaw dashboard

# 5. 验证渠道配对
openclaw channels list

Q2：OpenClaw 推荐运行时是什么？ ​

官方推荐 Node 运行时（Node 22+）。Windows 推荐 WSL2。Bun 为实验路径，不建议作为 Gateway 主运行时。

参考：

环境要求 ​

平台推荐配置最低配置
macOSNode 22+, 8GB RAMNode 20+, 4GB RAM
LinuxNode 22+, 8GB RAMNode 20+, 4GB RAM
WindowsWSL2 + Node 22+WSL2 + Node 20+

常见安装问题 ​

问题：安装后命令找不到

bash
# 检查 PATH 是否包含 npm 全局目录
echo $PATH

# 如果没有，添加到 ~/.bashrc 或 ~/.zshrc
export PATH="$(npm config get prefix)/bin:$PATH"

问题：网关启动失败

bash
# 查看详细日志
openclaw gateway start --verbose

# 检查端口占用
lsof -i :3000

# 重置网关配置
openclaw gateway reset

Q3：如何配置远程访问最稳妥？ ​

优先 Tailscale/VPN，其次 SSH 隧道。无论哪种方式，都要保留网关鉴权。

参考：

远程访问方案对比 ​

方案安全性便捷性适用场景
Tailscale/VPN高高团队协作
SSH 隧道高中临时访问
端口转发 + 鉴权中低测试环境

SSH 隧道配置示例 ​

bash
# 本地端口转发
ssh -L 3000:localhost:3000 user@remote-host

# 后台运行
ssh -fN -L 3000:localhost:3000 user@remote-host

# 通过隧道访问
openclaw --api-url http://localhost:3000

Q4：为什么我不建议多人共享一个高权限 Agent？ ​

官方安全模型不是对抗型多租户隔离。若用户互不信任，应该拆分网关与凭据。

参考：

安全建议 ​

  1. 最小权限原则：每个用户/角色只给必要权限
  2. 职责分离：敏感操作需要审批
  3. 审计日志：保留所有操作记录
  4. 定期审计：检查权限配置是否合理

多用户配置示例 ​

yaml
# ~/.openclaw/config.yaml
profiles:
  dev:
    permissions:
      tools:
        allow: [read, search]
        deny: [exec, write]
  admin:
    permissions:
      tools:
        allow: ['*']
        require_approval: ['exec:elevated', 'write:sensitive']

Q5：怎么减少工具误操作风险？ ​

使用 tools.profile + tools.allow/deny + 审批策略，逐步放开权限，不要一步到位。

参考：

工具权限配置示例 ​

yaml
# 工具配置
tools:
  # 使用预定义 profile
  profile: safe # safe | standard | full

  # 自定义权限
  allow:
    - 'read:*'
    - 'search:*'
    - 'web:*'

  deny:
    - 'exec:elevated'
    - 'write:sensitive'

  # 审批策略
  approvals:
    exec:
      mode: ask # off | on-miss | always
      timeout: 300 # 秒

分阶段权限放开 ​

txt
# 阶段 1：只读权限
tools:
  profile: "safe"
  allow: ["read:*", "search:*"]

# 阶段 2：添加写入权限（需要审批）
tools:
  profile: "standard"
  allow: ["read:*", "search:*", "write:*"]
  approvals:
    write:
      mode: "ask"

# 阶段 3：完整权限
tools:
  profile: "full"
  approvals:
    exec:elevated:
      mode: "ask"

Q6：模型与渠道文档为什么分开？ ​

OpenClaw 把"消息入口（channels）"和"模型后端（providers）"解耦，便于独立演进与替换。

参考：

解耦优势 ​

维度渠道层模型层
关注点消息路由、格式转换模型能力、成本控制
变更频率低（渠道稳定）中（模型迭代）
配置独立是是
可替换性高高

配置示例 ​

yaml
# 渠道配置
channels:
  discord:
    enabled: true
    bot_token: '${DISCORD_BOT_TOKEN}'
    model: gpt-4 # 默认模型

# 模型配置
providers:
  openai:
    models:
      gpt-4:
        enabled: true
        cost_limit: 100 # 美元/月
      gpt-4-turbo:
        enabled: true
        cost_limit: 50

Q7：遇到问题先看哪里？ ​

  • 网关层问题：/gateway/troubleshooting
  • 常见问题总览：/help/faq
  • 系统自检：openclaw doctor、openclaw security audit

常用诊断命令 ​

bash
# 系统诊断
openclaw doctor

# 安全审计
openclaw security audit

# 网关日志
openclaw gateway logs --tail 100

# 渠道状态
openclaw channels status

# 模型健康检查
openclaw providers health-check

日志查看 ​

bash
# 实时日志
openclaw gateway logs --follow

# 过滤日志
openclaw gateway logs --filter "error"

# 导出日志
openclaw gateway logs --export logs.json

Q8：如何排查模型响应慢的问题？ ​

排查步骤 ​

bash
# 1. 检查模型响应时间
openclaw providers latency-test

# 2. 检查网络延迟
ping api.openai.com

# 3. 检查网关负载
openclaw gateway stats

# 4. 检查并发配置
openclaw config get concurrency

优化建议 ​

问题解决方案
模型响应慢考虑换用更快的模型
网络延迟高使用代理或 CDN
网关负载高增加并发数或扩容
上下文太长减少输入 token 数

Q9：如何备份和恢复配置？ ​

备份配置 ​

bash
# 导出配置
openclaw config export --output config-backup.yaml

# 导出所有数据
openclaw backup create --output backup.tar.gz

恢复配置 ​

bash
# 导入配置
openclaw config import --input config-backup.yaml

# 恢复所有数据
openclaw backup restore --input backup.tar.gz

Q10：如何查看使用量和成本？ ​

bash
# 查看使用统计
openclaw stats usage

# 查看成本报告
openclaw stats cost --period month

# 按模型查看
openclaw stats cost --by model

# 按渠道查看
openclaw stats cost --by channel