# 快速入门

## 首次设置

运行交互式初始化向导：

```bash
agentteam onboard
```

向导会创建 `~/.agentteam/`、写入默认配置、检测可用 runtime、可选择安装 daemon 为系统服务，并在结束时运行诊断。

只打印 runtime 检测状态和修复建议：

```bash
agentteam onboard --runtime
```

AgentTeam Desktop 包含内置运行时，它使用托管的 OpenCode 运行时。OpenCode、Claude Code、Codex 仍作为手动 PATH 或 binary 配置路径保留；`agentteam onboard --runtime` 不会安装或升级它们。

## 启动 AgentTeam Desktop Client daemon

以前台方式运行 AgentTeam Desktop Client daemon：

```bash
agentteam daemon
```

该命令会读取本地 profile、把这台机器连接到 AgentTeam、提供认证后的本地 API、启动频道连接、加载 runtime/LLM 配置，并接收 Agent 会话流量。使用 `Ctrl+C` 或 `SIGTERM` 停止。

常用 daemon 参数：

| 参数 | 含义 |
|------|------|
| `--host` | 仅本次运行生效的监听地址覆盖 |
| `--port` | 仅本次运行生效的监听端口覆盖 |
| `--server-url` | 启动前保存或更新 AgentTeam machine server URL |
| `--api-key` | 启动前保存或更新 AgentTeam machine API key |

daemon 始终以 headless 模式运行。macOS 与 Windows 需要窗口和托盘时，应启动
打包后的 AgentTeam Electron 应用。

AgentTeam machine 接入/重连的 canonical 命令是：

```bash
agentteam daemon --server-url https://agentteam.pingcap.com --api-key <machineApiKey>
```

浏览器发起的一次性连接链接也可以通过下面命令处理：

```bash
agentteam connect 'agentteam://connect?token=...&origin=https%3A%2F%2F...'
```

## 系统服务

安装为平台原生后台服务：

```bash
agentteam service install
agentteam service start
```

平台行为：

| 平台 | 服务管理器 | 说明 |
|------|------------|------|
| macOS | launchd | `agentteam service` 下暴露 `install`、`uninstall`、`restart`、`reinstall`；install 会 bootstrap 并启动用户 LaunchAgent |
| Linux | systemd | `install`、`start`、`stop`、`restart`、`reinstall`、`uninstall`、`status` 支持 `--user` 用户级服务 |
| Windows | Windows Service | 支持服务 start/stop/restart |

常用命令：

```bash
agentteam status
agentteam status -f json
agentteam service restart
agentteam service reinstall
agentteam service uninstall
```

macOS 上，`agentteam service reinstall` 会在重装前服务正在运行时启动 LaunchAgent；如果 reinstall 实际是在做首次安装，也会立即启动。Linux 上，`agentteam service install` 负责注册并启用 systemd 服务；如果希望现在就启动它，还需要执行 `agentteam service start`。`agentteam status` 默认检查 system 和 user 两类服务，并显示已安装服务的 active、failed 或 inactive 状态。连接命令和 service 命令应使用同一个系统用户；如果连接配置在普通用户下，请从该用户执行 `sudo agentteam service install`。使用 `agentteam status --user` 只查看当前用户的 systemd 服务。

## 日志

```bash
agentteam journal
agentteam journal --tail 50
agentteam journal --head 20
agentteam journal -f
agentteam j -f --tail 20
```

不带参数时，`agentteam journal` 会输出解析后的日志路径和用法。默认日志文件在 macOS 上是 `~/Library/Logs/agentteam/agentteam.log`，Linux 上是 `${TMPDIR:-/tmp}/agentteam/log/agentteam.log`，Windows 上是 `%LOCALAPPDATA%\agentteam\Logs\agentteam.log`。也可以通过 `config.yaml` 中的 `log.dir` 或 `log.file` 覆盖。

Desktop 仪表盘里的 **AgentTeam 日志** 入口会显示最近 500 条 daemon 日志，并支持复制当前可见日志文本。

## 配置

主配置文件：

```text
~/.agentteam/config.yaml
```

设置 `AGENTTEAM_CONFIG_DIR` 可以把全部 daemon profile 文件移动到其他目录。

当前顶层设置：

| 字段 | 用途 |
|------|------|
| `host` | 本地 API 监听地址，默认 `127.0.0.1` |
| `port` | 本地 API 端口。`0` 表示自动选择：daemon 会请求 OS 分配可用 loopback 端口并持久化实际端口；正数表示固定端口并在重启时复用。 |
| `pid_file` | PID 文件路径 |
| `language` | daemon 默认语言，默认 `zh-CN` |
| `default_agent` | 会话没有 override 或频道绑定时使用的 Agent |
| `ui.theme` | `light`、`dark` 或 `system` |
| `ui.color_scheme` | Dashboard 配色方案 |
| `ui.language` | Dashboard 语言，`en` 或 `zh` |
| `ui.show_sidebar_labels` | 侧边栏图标+文字显示模式 |
| `log.dir` / `log.file` | 日志位置 |
| `security.public_key` / `security.private_key` | Ed25519 API key 签名密钥 |

## 环境变量

| 变量 | 用途 |
|------|------|
| `AGENTTEAM_CONFIG_DIR` | 覆盖 `~/.agentteam/` |
| `AGENTTEAM_VERBOSE` | 设置为 `1`、`true` 或 `yes` 时启用 verbose 输出 |
| `AGENTTEAM_MCP_AGENTTEAMBACK_NO_PROXY` | 控制 runtime MCP 本地回环流量的 `NO_PROXY` 注入：`auto`、`on` 或 `off` |

`AGENTTEAM_MCP_AGENTTEAMBACK_NO_PROXY=auto` 是默认值。它只会在 MCP endpoint 是本地地址时，把 `127.0.0.1`、`localhost` 和 `::1` 追加到 `NO_PROXY` / `no_proxy`。

## 诊断与升级

运行诊断：

```bash
agentteam doctor
agentteam doctor --fix-runtime
```

检查并应用升级：

```bash
agentteam upgrade
agentteam upgrade --check
```

输出版本信息：

```bash
agentteam --version
agentteam --version -f json
```