Agent 运维
这一页只看电脑侧 agent：怎么启动、怎么托管、怎么配对，以及怎么观察和治理本地会话。
1. agent 的角色
agent 运行在你的电脑上，负责：
- 管理本地
tmux会话 - 保留会话主数据和终端输出
- 与 relay 保持 WebSocket 连接
- 给已配对浏览器提供输出同步和轻控制入口
2. 启动方式
后台模式
bash
termpilot agent首次运行时会：
- 询问 relay 地址
- 保存本地配置
- 启动后台 agent
- 打印一次性配对码
常用命令：
bash
termpilot agent
termpilot agent --pair
termpilot agent status
termpilot agent stop前台模式
如果你希望交给系统进程管理器托管：
bash
termpilot agent --foreground --relay wss://your-domain.com/ws适合：
launchdsystemd --usersupervisord
3. 进程管理器托管
macOS launchd
最小示例：
xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.fengye.termpilot-agent</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/termpilot</string>
<string>agent</string>
<string>--foreground</string>
<string>--relay</string>
<string>wss://your-domain.com/ws</string>
</array>
<key>KeepAlive</key>
<true/>
<key>RunAtLoad</key>
<true/>
</dict>
</plist>Linux systemd --user
最小示例：
ini
[Unit]
Description=TermPilot Agent
After=network-online.target
[Service]
ExecStart=/usr/local/bin/termpilot agent --foreground --relay wss://your-domain.com/ws
Restart=always
RestartSec=3
[Install]
WantedBy=default.target4. 配对、授权与审计
重新生成配对码
bash
termpilot agent --pair注意：
agent --pair默认复用已运行的后台 agent- 它不会强制重启已有 agent
- 电脑端会打印设备指纹；浏览器配对时应核对该指纹
查看 grants
bash
termpilot grants查看审计事件
bash
termpilot audit --limit 20撤销 access token
bash
termpilot revoke --token <accessToken>5. 状态目录与日志
默认状态目录：
text
~/.termpilot常见文件：
config.json：保存 relay 配置state.json：本地会话状态device-id：自动生成的设备 IDdevice-key.json：agent 设备密钥agent-runtime.json：后台 agent 运行信息agent.log：agent 日志
如果你要切换状态目录：
bash
TERMPILOT_HOME=/data/termpilot termpilot agent6. 会话运维
托管命令会话
bash
termpilot claude code
termpilot run -- opencode
termpilot run -- python -m http.server这些会话的语义是：
- 当前程序结束，会话也一起结束
- 如果只是把本地终端窗口关掉，但会话本体仍在
tmux中，agent 会继续保留这条会话 - 对于长期无人附着且无输出的托管命令会话，当前实现会自动治理
相关环境变量：
TERMPILOT_ORPHAN_WARNING_MSTERMPILOT_MANAGED_SESSION_AUTOCLEANUP_MS
普通 shell 会话
bash
termpilot create --name deploy --cwd /srv/app
termpilot list
termpilot attach --sid <sid>退出动作区分两种：
- 临时离开：
Ctrl+B然后按D - 彻底结束：
exit/Ctrl+D或termpilot kill --sid <sid>
7. 日常检查
至少记住这几条：
bash
termpilot agent status
termpilot grants
termpilot audit --limit 20
tail -f ~/.termpilot/agent.log