这份笔记已经非常详实，涵盖了从安装、配置、自启到故障排查的全过程。我帮你进行了结构化整理、逻辑分层和格式美化，修正了部分命令的上下文描述（特别是区分了“用户级服务”和“系统级服务”的操作差异），使其更适合作为长期维护的文档。

🦞 OpenClaw 部署与运维实战笔记

官方资源
官方文档: https://docs.openclaw.ai/zh-CN/install

核心配置与日常操作

🔐 安全与访问控制
功能 命令 说明
允许非加密访问 openclaw config set gateway.controlUi.allowInsecureAuth true 开发环境常用，允许 HTTP 访问 Dashboard

配置 CORS 白名单 openclaw config set 'gateway.controlUi.allowedOrigins' '["http://ai.rao.jx.cn"]' 仅允许指定域名访问控制面板

获取带令牌链接 openclaw dashboard --no-open 生成包含 Auth Token 的完整 URL，用于远程访问

🌐 网关管理
前台启动网关（调试用）
openclaw gateway run

注册并启用开机自启服务（详见第 4 节）
openclaw gateway install

📱 设备管理
查看待批准或已连接的设备列表
openclaw devices list

批准特定设备接入 (替换 )
openclaw devices approve

⚙️ 全局配置
进入交互式配置模式
openclaw configure

环境变量与 Shell 配置

🔄 立即生效环境变量
source ~/.bashrc # Bash 用户
或
source ~/.zshrc # Zsh 用户

🛠️ 解决环境变量不生效问题
如果重启后或新终端中变量未加载，请检查 Shell 类型并修正配置文件。

第一步：确认 Shell 类型
echo SHELL
输出 /bin/zsh -> 参考下方 "Zsh 用户"
输出 /bin/bash -> 参考下方 "Bash 用户"

第二步：修改配置文件

👉 场景 A：Zsh 用户 (macOS 默认/部分 Linux)
Zsh 默认不读取 .bashrc，需手动引入。
编辑文件：nano ~/.zshrc
在末尾添加：

  source ~/.bashrc

保存退出 (Ctrl+O, Enter, Ctrl+X) 并生效：source ~/.zshrc

👉 场景 B：Bash 用户
Bash 登录模式可能只读取 .bash_profile。
编辑文件：nano ~/.bash_profile (不存在则创建)
确保包含以下逻辑：

  if [ -f ~/.bashrc ]; then
   source ~/.bashrc

fi

保存退出并生效：source ~/.bash_profile

配置开机自启 (关键步骤)

⚠️ 注意：openclaw gateway install 默认安装为 用户级服务 (User Service)，而非系统级服务。
这意味着必须开启 Linger (残留会话) 才能实现真正的开机自启，否则重启后服务不会运行。

🚀 标准启用流程

安装服务文件

  openclaw gateway install

# 若需强制重写配置，使用：openclaw gateway install --force

生成的文件位置通常为：~/.config/systemd/user/openclaw-gateway.service

重载用户守护进程

  systemctl --user daemon-reload

启用并启动服务

  systemctl --user enable --now openclaw-gateway

【至关重要】开启 Linger 模式
如果不执行此步，服务器重启后因无人登录该用户，服务将不会启动。

  sudo loginctl enable-linger (whoami)

# 或者指定用户：sudo loginctl enable-linger openclaw

🧰 常用服务管理命令 (用户级)
查看状态
systemctl --user status openclaw-gateway

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

停止/启动
systemctl --user stop openclaw-gateway
systemctl --user start openclaw-gateway

查看实时日志
journalctl --user -u openclaw-gateway -f

💡 补充说明：如果你看到教程中提到 /etc/systemd/system/openclaw-gateway.service，那是系统级服务的路径。OpenClaw 默认使用用户级方案以避免 root 权限问题，两者管理命令略有不同（用户级需加 --user 参数）。

高级定制：注入额外环境变量

如果需要让 OpenClaw 服务识别额外的工具（如 himalaya 或 linuxbrew），需修改 systemd 服务文件。

操作步骤

编辑服务配置

  # 用户级服务编辑命令

systemctl --user edit openclaw-gateway

(这会创建一个 override 文件，比直接修改原文件更安全)

添加环境变量
在编辑器中输入以下内容（示例为添加 linuxbrew 路径）：

  [Service]

Environment="PATH=/home/linuxbrew/.linuxbrew/bin:%PATH"
# 如有其他变量可继续添加
# Environment="HIMALAYA_CONFIG=/path/to/config"

重载并重启

  # 重载配置

systemctl --user daemon-reload

# 重启服务使变量生效
systemctl --user restart openclaw-gateway

验证
查看日志确认服务启动正常，或在服务运行的环境中测试命令是否可用。

故障排查速查
现象 可能原因 解决方案
重启后服务未运行 未开启 Linger 执行 sudo loginctl enable-linger

服务启动后立即失败 配置文件错误/端口占用 查看日志 journalctl --user -u openclaw-gateway -n 50

命令找不到 (command not found) 环境变量未加载 检查 .bashrc/.zshrc 配置，或参考第 5 节注入 PATH

Dashboard 无法访问 防火墙/CORS 限制 检查 allowedOrigins 配置及服务器防火墙设置