故障排除

常见的故障模式，按你可能遇到的顺序排列。

遇到任何问题时的第一步：

安装时

未找到 `cargo`

sh

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

或者向 install.sh / setup.bat 传递 --prebuilt 参数以完全跳过 Rust。

在低内存主机上构建 OOM

从源代码构建 ZeroClaw 是非常占用内存的，尤其是在最终的链接阶段。install.sh 在从源代码构建时已经会自动适应这种情况：

当 install.sh 在 Linux 上从源码构建时，它会从 /proc/meminfo 读取 MemTotal，并在 RAM 低于 12 GiB 的主机上于构建前导出 CARGO_PROFILE_RELEASE_LTO=thin。Fat LTO（[profile.release] 的默认值）在跨 crate 类型处理阶段的 RSS 峰值可能超过 7 GB，从而使低 RAM 的开发板发生 OOM；thin LTO 以二进制体积的小幅增加换取了大幅降低的构建时内存峰值。

只有在你尚未固定该变量时，此切换才会生效。可显式覆盖任一方向：

# 即使在低内存主机上也强制使用 fat LTO（生成更小的二进制文件，但构建时占用更多内存）
export CARGO_PROFILE_RELEASE_LTO=fat

# 在大内存主机上强制使用 thin LTO（降低构建内存占用）
export CARGO_PROFILE_RELEASE_LTO=thin

如果你仍然遇到内存不足的问题，或者你不是通过 install.sh 进行构建：

使用预构建版本：./install.sh --prebuilt 会跳过工具链并从 GitHub Releases 下载。
在更强大的机器上交叉编译，然后复制二进制文件。
选择更轻量的构建配置：cargo build --profile release-fast（更高的代码生成并行度，更轻量的链接）或 --profile ci（thin LTO，最快/内存占用最低）。
序列化构建：CARGO_BUILD_JOBS=1 cargo build --release --locked。
添加交换空间（适用于内存，会占用磁盘，请确认两者都有足够空间）。

有关 Raspberry Pi 的具体细节，请参阅 Raspberry Pi setup → build。

构建速度非常慢

Matrix E2EE 堆栈（matrix-sdk、ruma、vodozemac）以及 TLS/crypto 原生依赖（aws-lc-sys、ring）是主要的成本来源。如果不需要它们，可以选择退出：

sh

cargo build --release --locked --no-default-features --features "默认精简"

或者检查正在发生的情况：

sh

cargo check --timings
# 在 target/cargo-timings/cargo-timing.html 处报告

安装后出现 `zeroclaw: command not found`

cargo install 将可执行文件安装到 ~/.cargo/bin/。将其添加到 PATH 中：

sh

export PATH="$HOME/.cargo/bin:$PATH"

将其持久化到 shell 配置文件中。

快速开始

快速入门不会覆盖现有配置

zeroclaw quickstart 没有 --force 标志，它会有意保留已有的安装不做改动。若要在过期的安装上运行全新的 quickstart，请删除该目录后重新开始：

sh

rm -rf ~/.zeroclaw
zeroclaw quickstart

或者，如果只想编辑单个过期字段而不是清空所有内容，请直接使用 zeroclaw config set <key> <value>。

Homebrew 安装：配置路径不匹配

Homebrew 安装时倾向于使用 $HOMEBREW_PREFIX/var/zeroclaw/（以便 brew services 正常工作），而默认的配置目录是 ~/.zeroclaw/。在运行 quickstart 之前，请将 ZEROCLAW_WORKSPACE 设置为 Homebrew 路径，以使两个路径保持一致：

sh

export ZEROCLAW_WORKSPACE="$HOMEBREW_PREFIX/var/zeroclaw"
zeroclaw quickstart

或手动创建一次符号链接：

sh

ln -s "$HOMEBREW_PREFIX/var/zeroclaw" ~/.zeroclaw

运行时

OpenAI Codex 订阅认证会针对配置或流式传输发出警告

症状：

代理的 model_provider = "openai.<alias>" 指向某个 Codex 条目，但运行时仍感觉配置有误
配置加载时会对未知的顶级字段发出警告，例如 api_key / api_url（这些字段应位于 provider 条目下，而非文件根部）
智能体记录 provider streaming failed, falling back to non-streaming chat

检查项（请将 <alias> 替换为 [agents.<alias>] 中配置的智能体别名）：

对于 OpenAI Codex 订阅，请在提供方别名上设置 requires_openai_auth = true 并保持 api_key 未设置；运行时会使用已存储的 Codex 登录凭据。请通过供应商自有的登录流程获取订阅凭据。完整的凭据模型请参阅 Provider Configuration → OAuth and subscription auth。然后进行测试：

sh

zeroclaw agent -a <alias> -m hello

注意事项：

在别名上设置 requires_openai_auth = true（且 api_key 未设置）将选择订阅路径；请将其与最小可用示例中的标准 agent + 风险配置文件配合使用。
别名条目中的 api_key / uri 仅在使用自定义的 OpenAI 兼容网关或其他显式端点覆盖时才需要。
streaming-disabled 警告本身并不是身份验证失败；ZeroClaw 会以非流式模式重试该请求。

守护进程启动后立即退出

检查 journald / 平台日志（参见日志与可观测性）以获取实际错误信息。常见原因：

配置无效：使用 zeroclaw config list 打印解析后的值，使用 zeroclaw config schema 查看预期的结构
端口冲突：另一进程占用了 42617；请更改 [gateway] port 或释放该端口
缺少密钥：加密密钥存储库因密钥文件丢失而无法解密；请从备份恢复或重新运行初始化引导

守护进程不断重启

systemctl --user status zeroclaw 显示最后一次退出的状态。如果是配置错误，服务会停止重启（退出码为 2），你需要修复配置文件。如果是 panic，该单元会每 10 秒重试一次。

启用调试日志并捕获下一次失败：

sh

zeroclaw service stop
RUST_LOG=调试 zeroclaw daemon

网关不可达

sh

curl -sv http://localhost:42617/health

如果连接被拒绝：守护进程未运行，或绑定到了不同的接口。请检查配置文件中的 [gateway] host 和 port。

如果返回 403 / 401：表示配对未完成或令牌已过期。请重新运行配对流程。

频道

Telegram：`被其他 getUpdates 请求终止`

两个进程正在轮询同一个机器人令牌。Telegram 一次只允许一个轮询器。

修复：停止所有使用同一令牌的其他 zeroclaw daemon / zeroclaw channel start 实例，仅保留一个。

Discord / Slack 身份验证失败

在开发者门户中重新生成令牌会导致 Discord 令牌过期。Slack 机器人令牌不会过期，但可以被撤销。请检查机器人是否仍安装在目标工作区/服务器中。

对于以下任一情况：

sh

zeroclaw channel doctor

SOP 扇入不在 `channel doctor` 的覆盖范围内

zeroclaw channel doctor 在没有守护进程实时 SOP 引擎和审计句柄的情况下构造传输适配器。它可以检查普通频道传输，但无法证明 MQTT、文件系统或 AMQP SOP 分发能够启动运行。对于这些来源，请在启用 SOP 运行时的情况下启动 zeroclaw daemon（将 sop.sops_dir 设置为非空值；默认未设置，这会将其禁用；文档中的值为 shared/sops），然后检查来源连接和 SOP ingress 日志事件。当 SOP 句柄不可用时，使用 dispatch = "sop" 或 "sop_and_agent_loop" 的 AMQP 频道会在守护进程启动时以故障关闭方式失败；在此状态下，它会被有意从 doctor 工作列表中省略。

Matrix：“未知设备”

如果您在重新加入时未保留设备密钥，主服务器会看到一个尚未验证的新设备。请从另一个已登录的客户端重新验证，或重置密钥存储：

sh

rm -rf ~/.zeroclaw/workspace/matrix-crypto
# 在下一个通道启动时重新运行配对流程

IMAP 轮询已停止

通常是身份验证失败，可能是提供商更换了密码，或应用专用密码已过期。请检查：

sh

journalctl --user -u zeroclaw -n 200 | grep -i imap

提供者

与 Ollama 的连接超时

Ollama 守护进程未运行：systemctl status ollama（Linux）、brew services list（macOS）
配置中的 URL 错误，在容器内部，localhost:11434 无法访问宿主机；请使用 host.docker.internal 或宿主机的局域网 IP
防火墙阻止 11434 端口，本地环境少见，但在共享局域网中常见

Anthropic / OpenAI 401

API 密钥无效或已过期。请在提供商的控制台重新生成，并更新到 [providers.models.<name>] api_key，然后重启服务。

如果使用 OAuth（sk-ant-oat*），OAuth 令牌可能已过期。OAuth 颁发的令牌有效期较长，但并非永久有效。请重新进行身份验证。

工具

“被策略阻止的 Shell 命令”

在 Supervised 自主模式下，对于未知命令的预期行为。要么：

在提示时批准内联
将命令添加到 [autonomy] allowed_commands
如果你信任上下文，将自主性提升至 Full。

请参阅安全 → 自主级别。

在 Docker 沙箱中工具调用失败

容器镜像未拉取，请对你在 [security.sandbox].image 下配置的镜像（默认为 alpine:latest）运行 docker pull <image>
无法从 ZeroClaw 用户访问 Docker 守护进程，请检查 docker info
工具需要一个未透传的设备，请扩展 allow_devices

浏览器工具在首次使用时挂起

Playwright 在首次启动时会下载 Chromium（约 150 MB）。请等待其完成。如果一直卡住，请检查磁盘空间和代理配置。

服务模式

服务已安装但显示为未激活

sh

zeroclaw service start
zeroclaw service status

使用 zeroclaw service logs 实时查看已安装服务的日志。添加 --follow 可流式输出新的日志条目，或使用 --lines <count> 更改显示的历史记录数量。如果该封装工具不可用，或者你需要直接检查平台，请使用：

Linux：journalctl --user -u zeroclaw.service -f
macOS：log stream --predicate 'process == "zeroclaw"'
如果你直接在终端中运行 zeroclaw daemon，请使用该前台输出，而不是服务日志命令。

如果交互式运行成功，但服务在后台运行时终止，这几乎总是配置或权限问题，请查看日志：

sh

journalctl --user -u zeroclaw --since 5 分钟前

服务无法找到配置文件

如果服务与 CLI 以不同的用户身份运行或使用了不同的环境变量，它们解析配置的方式可能会不同。强制打印守护进程所看到的路径：

sh

zeroclaw config list

如果 zeroclaw config list（以你的用户身份）与服务（以其用户身份）之间的路径不同，请执行以下任一操作：

在服务单元的 Environment= 中设置 ZEROCLAW_CONFIG_DIR
以您（启用持久化的用户服务）的身份运行该服务
将配置文件复制或链接到服务期望的路径

仍然遇到问题？

收集诊断信息并提交问题：

sh

zeroclaw --version
zeroclaw doctor
zeroclaw channel doctor
journalctl --user -u zeroclaw --since 1 小时前 > zeroclaw-log.txt

清理 zeroclaw-log.txt（如果有任何频道令牌混入其中，请将其编辑掩盖，不过本不应出现这种情况），并将其附加到该 issue。请参阅 Contributing → Communication 了解附加位置。

Keyboard shortcuts

ZeroClaw Docs