跳到文档内容
Anygent.ai文档

whalent-agent 常用参数

常驻运行、固定机器名、数据目录、多账号、服务器代理、续接对话和升级的常用写法。

约 5 分钟更新于 2026-11-12

开始前

  • 已按「CLI 接入」装好并能运行 whalent

后台常驻

  1. 用 screen 后台运行

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

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

  2. 用 systemd 开机自启

    开机自启、崩溃自动拉起。在自己的登录 shell 里整段粘贴（别用 sudo 或 root），把 <你的Token> 换成永久 Token。

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

[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，左侧栏会多出一台“新机器”。用 --machine 固定（设一次就记住），参数和值之间用空格，别写成 --machine=my-server。

    whalent --machine my-server

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

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

    状态默认在 ~/.whalent-agent，可用 --home 放到数据盘或挂载卷。优先级：--home > WHALENT_HOME > $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 分开各账号的状态目录，互不串号；不带时按 Token 自动归到所属账号。

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

  5. 服务器流量走代理：--server-proxy

    只能经代理出网时，用 --server-proxy 让连 Anygent 服务器的全部流量（平台、网关、中继、上传、云端机器中继）走同一个代理；账号登录、额度查询、模型 API 等其他流量照旧。支持 socks5://、socks5h://、http://、https://，不支持 SOCKS4；服务器域名一律交给代理解析。设一次就按账号记住，--server-proxy none 清除；代理连不上会直接报错，不会绕开代理直连。需要 whalent 0.3.612 及以上。

    whalent --server-proxy socks5://127.0.0.1:1080
whalent --server-proxy http://user:pass@proxy.example.com:3128   # 用户名、密码含 @ : / 等字符时先做 URL 编码

# 只用这一次、不保存
WHALENT_SERVER_PROXY=socks5://127.0.0.1:1080 whalent

whalent server-proxy          # 查看当前设置
whalent server-proxy check    # 经代理测试能否连上服务器
whalent --server-proxy none   # 清除保存的代理

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

    在目标机器的交互式终端运行下方命令，或在对话工具菜单选「使用终端访问」。接管时托管进程会先停下，退出后恢复并补齐消息；仅支持 Codex、Claude Code、Antigravity CLI（Agent Core 0.3.518 起）。

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

维护

  1. 升级 whalent

    重新全局安装即可，状态目录不受影响。要固定版本时，先在 npm 或发布说明里确认版本号，不要照抄旧教程里的版本号。

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

  2. 打开桌面 App：whalent app

    在 Windows、macOS 或 WSL 上打开桌面 App（缺组件会先安装）；--route 打开指定页面，status 查看组件版本和连接状态。

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

  3. 排查不在线

    先在对话主机管理看机器是否在线，再查 whalent 进程还在不在（screen -ls）、Token 是否有效、机器名是否因重启变了。

注意事项

  • systemd 要用用户级服务（systemctl --user）：写到 /etc/systemd/system 的系统级服务不用你的 HOME 和 PATH，找不到 nvm 装的 node、claude、codex。
  • --home 只改数据目录位置，不改账号；换目录后要迁移旧状态或重新登录。
  • 同一台机器可以同时跑 Codex、Claude Code 等多种 Agent；每个 Codex 实例用独立的 CODEX_HOME，各自登录、互不影响。
  • Token 等同账号凭据，不要写进镜像、提交到仓库或贴到公开页面。
  • HTTP 代理要允许 CONNECT 到 443 端口和云端机器的 SSH 中继端口（默认 2222），否则云端机器中继会报 proxy refused CONNECT；桌面 App 暂不支持设置服务器代理。