配置与排查

先检查状态

在执行任务的机器上运行：

ginit paseo status

根据输出判断是本机服务、Hub 还是 Relay 连接异常，再处理对应问题。

常见问题

安装提示 EACCES 或 permission denied

如果错误路径是 /usr/local/lib/node_modules，说明 npm 正在向当前用户无权写入的系统目录安装。Linux 或 macOS 用户可以改用自己的目录：

export PATH="$HOME/.local/bin:$PATH"
npm_config_prefix="$HOME/.local" ginit paseo install

这会为本次安装显式指定用户目录，无需使用 sudo。仅运行 npm config set prefix 在部分 Ginit 安装流程中可能不生效，请使用上面的环境变量。如果 shell 启动配置中尚未包含 $HOME/.local/bin，请把上面的 export PATH 一行加入 ~/.bashrc（Bash）或 ~/.zshrc（Zsh），确保新终端也能找到命令。

若本机已有正在运行任务的 Paseo 服务，仅安装 CLI 时可在命令末尾添加 --no-start --no-attach，避免触发服务启动或重新接入。

找不到主机

确认查看端与执行机器登录的是同一飞书账号。新机器需要单独完成安装与接入，并保持开机联网。

已安装，但没有接入 Ginit

按跨设备连接中的重新接入步骤操作。若出现登录过期提示，先重新运行 ginit login。

主机在线，但任务无法启动

检查执行机器上的 agent CLI 是否已安装、登录且能独立运行，同时确认所选项目路径存在。Paseo 使用这台机器的环境和工具配置。

Hub 返回 404 或 Relay 无法连接

确认当前使用的是支持 Paseo 的 Ginit 服务环境。自定义部署时，请维护者核对 Hub 与 Relay 地址和网络可达性；不要将本机服务端口直接开放到公网来绕过连接问题。

偶尔超时

先重试并检查网络与状态。不要直接重启正在运行任务的后台服务，重启可能打断 agent。

自定义部署配置

普通安装通常无需修改以下配置。只有接入自建服务，或维护者明确要求时，才调整相应环境变量。

配置值应由所用环境的维护者提供，避免混用不同环境的地址。

模型与语音配置

模型由执行任务的 Host 提供；支持 ginit-codex、ginit-claude、Codex、Claude Code 等工具，具体以 Host 的 Provider 列表为准。添加模型见创建任务与选择模型及自定义 Provider 文档。

豆包 ASR 需要在 Host 上配置；Hub 登录不会自动下发凭据。配置文件为 $PASEO_HOME/config.json（默认 ~/.paseo/config.json），合并配置时保留原有字段，并将文件权限设为 0600。配置需在 daemon 启动时加载，由管理员安排维护窗口使其生效。ASR 会将音频发送到配置的服务，只负责转文字，不等于完整语音对话。

启智环境

在启智实例内部安装 Paseo 和 agent CLI，并确保：

• 实例能访问 Hub、Relay、模型接口及所需 ASR 服务，通常无需公开 6767 入站端口。
• 项目和 PASEO_HOME 位于平台持久目录，运行用户有读写权限。
• 实例保持运行；停止、休眠或回收会中断任务。

IS_SANDBOX=1 必须全大写。 需要使用该环境变量时，应在 Host 上按所用 Claude 工具的要求配置；不要假设所有适配器都会默认注入。它用于 Claude 的 root/容器权限模式检查，不会创建沙箱，也不适用于所有 provider。具体启智实例尚未验证；优先使用普通用户，root 跳过权限确认需在隔离环境使用。

中继切换与进阶排查

Q：如何修改中继服务器地址？

在运行 Paseo daemon 的主机终端执行以下命令，可将中继服务器切换为 paseo.opensii.cn:443 并启用 TLS。需要已安装 python3、ginit，且 $PASEO_HOME/config.json（默认 ~/.paseo/config.json）已存在；如使用自定义 PASEO_HOME，请先将其导出为环境变量。

命令会重启 daemon，执行前请确认运行中的任务可以中断。 脚本会先在同目录备份配置，再更新 Relay 字段，保留其他配置。切换到其他中继时，请替换下方全部四处 paseo.opensii.cn:443。

(
set -eu

python3 <<'PY'
import json
import os
import shutil
from pathlib import Path
from datetime import datetime

home = Path(os.environ.get("PASEO_HOME") or Path.home() / ".paseo")
path = home / "config.json"
config = json.loads(path.read_text())
backup = path.with_name(f"config.json.bak.{datetime.now():%Y%m%d%H%M%S%f}")
shutil.copy2(path, backup)

config.setdefault("daemon", {}).setdefault("relay", {}).update({
    "enabled": True,
    "endpoint": "paseo.opensii.cn:443",
    "publicEndpoint": "paseo.opensii.cn:443",
    "useTls": True,
    "publicUseTls": True,
})

path.write_text(json.dumps(config, ensure_ascii=False, indent=2) + "\n")
print(f"已更新：{path}")
print(f"已备份：{backup}")
PY

export PASEO_RELAY_ENDPOINT=paseo.opensii.cn:443
export PASEO_RELAY_PUBLIC_ENDPOINT=paseo.opensii.cn:443
export PASEO_RELAY_USE_TLS=true
export PASEO_RELAY_PUBLIC_USE_TLS=true

ginit paseo daemon restart
sleep 5
ginit paseo status
)

配置文件中的修改会持久保存；括号内的 export 仅对该子 shell 及其启动的进程生效。此命令仅修改 Relay，不修改 Hub 地址。重启后回客户端点击 Refresh、Connect；若 5 秒后尚未就绪，请稍后再查看状态，不要反复重启。需要恢复配置时，使用脚本打印的备份文件覆盖原配置，并在确认任务可中断后重启 daemon。

其他问题

日志位于 $PASEO_HOME/daemon.log，默认 ~/.paseo/daemon.log。不要因一次超时就重启，更不要未经确认重启 6767 上管理活跃任务的主 daemon。 源码开发与排查见 开发指南。