跳到文档内容
Anygent.ai文档

whalent-agent 常用参数

查看常驻运行、机器名、数据目录、Profile、会话恢复和升级方法。

约 8 分钟更新于 2026-09-23

开始前

  • 先完成“CLI 接入”（whalent 已能运行）

后台常驻

  1. screen / tmux

    直接运行的 whalent 会随终端断开而退出。用 screen 放到后台运行；服务器重启后需要重新启动。

    screen -dmS whalent whalent   # 后台启动
screen -r whalent             # 回到会话（Ctrl+A D 再次挂起）
screen -ls                    # 查看会话是否还在

  2. systemd 用户服务：开机自启

    注册成用户级服务后，开机自动启动、崩溃自动拉起。在自己的登录 shell 里整段粘贴（不要在 sudo 或 root shell 里），把 <你的Token> 换成永久 Token。

    mkdir -p ~/.config/systemd/user
tee ~/.config/systemd/user/whalent.service >/dev/null <<EOF
[Unit]
Description=Whalent Agent

[Service]
Type=simple
ExecStart=$(command -v whalent) --token <你的Token>
Environment=PATH=$PATH
Restart=always
RestartSec=5

[Install]
WantedBy=default.target
EOF
systemctl --user daemon-reload && systemctl --user enable --now whalent
sudo loginctl enable-linger $USER      # 开机自启（不登录也运行），仅此一步需要 sudo

systemctl --user status whalent --no-pager   # 查看状态
journalctl --user -u whalent -f              # 实时日志

常用参数

  1. 固定机器名：--machine

    机器名默认取 hostname。有的云主机重启会改 hostname，左侧栏就会多出一台“新机器”；用 --machine 固定后始终归到同一行，首次设置后会记住。参数和值之间用空格，不要写成 --machine=my-server。

    whalent --machine my-server

# 等价环境变量写法
WHALENT_MACHINE=my-server whalent

  2. 自定义数据目录：--home

    状态默认在 ~/.whalent-agent。--home <目录> 会改到 <目录>/.whalent-agent，适合数据盘或挂载卷。优先级：--home > WHALENT_HOME > $HOME；WHALENT_AGENT_HOME 直接指定状态目录本身。

    whalent --home /data/whalent
# 状态目录变为 /data/whalent/.whalent-agent

# 等价环境变量写法
WHALENT_HOME=/data/whalent whalent

# 直接钉死目录本身（不追加 .whalent-agent）
WHALENT_AGENT_HOME=/data/whalent-agent whalent

  3. Docker 容器里持久化

    把宿主机目录挂进容器，再用 --home 指向挂载点，重建容器后登录状态和对话都还在。

    docker run -d \
  -v /srv/whalent:/data/whalent \
  -e WHALENT_TOKEN=<你的Token> \
  node:24 sh -lc "npm i -g @whalent/agent@latest --registry=https://registry.npmmirror.com && whalent --home /data/whalent --machine my-docker"

  4. 多账号：--profile

    同一台机器登录多个账号时，用 --profile 给每个账号单独的状态目录，互不串号。不带 profile 时按 Token 自动归到同一账号目录。

    whalent --profile work --token <工作账号Token>
whalent --profile personal --token <个人账号Token>

  5. 续接云端对话：--resume

    在服务器上接着某个云端对话继续跑，不影响正在运行的 whalent。对话 ID 在对话右上角 ⋯ 菜单底部复制；支持 Codex 和 Claude Code，需要在交互式终端里运行。

    whalent --resume <对话ID>
    对话右上角更多菜单底部的对话 ID 复制入口
    从对话右上角 ⋯ 菜单底部复制对话 ID。

维护

  1. 升级 whalent

    重新全局安装即可，状态目录不受影响；也可以指定版本，如 @0.3.175。

    npm install -g @whalent/agent@latest --prefer-online --registry=https://registry.npmmirror.com

  2. 打开桌面 App：whalent app

    在 Windows、macOS 或 WSL 上打开 Anygent 桌面 App，缺少组件时会先自动安装。--route 直接打开某个页面，whalent app status 查看组件版本和连接状态。

    whalent app
whalent app --route /workbench/论文
whalent app status

  3. 多 provider 凭据隔离

    同一台机器可以同时跑 Codex、Claude Code 和 OpenCode。每个 Codex agent 使用独立的 CODEX_HOME，登录状态互不影响；新建实例时可以从已有凭据导入或 Resume。

  4. 连不上 / 不在线

    先在实例管理确认机器和 daemon 是否在线，再检查 whalent 进程是否还在（screen -ls）、Token 是否有效、机器名是否因重启变了。

注意事项

  • systemd 用用户级服务（systemctl --user），不要写到 /etc/systemd/system：系统级服务的 HOME 和 PATH 不是你的，找不到 nvm 安装的 node、claude、codex。
  • --home 只改数据目录位置，不改账号；换目录后需要迁移旧状态或重新登录。
  • 容器里挂载卷和 --home 缺一不可，只做一样仍会丢状态。
  • Token 等同账号凭据，不要写进镜像、提交到仓库或贴到公开页面。