API 与配置

本页覆盖 Agent 后端完整的配置面，包括启动选项、数据目录布局以及常见故障排查指引。

数据目录布局

Agent 将所有运行时数据保存在统一的数据目录下：

macOS / Linux：~/.aiagent/
Windows：%USERPROFILE%\.aiagent\

~/.aiagent/
├── config.yaml              ← 主配置文件（模型 provider、默认值）
├── workspaces.json          ← Workspace 列表
├── global_mcp_servers.json  ← 全局 MCP server 配置
├── workspaces/
│   └── <workspace-id>/
│       ├── workspace.json   ← Workspace 元数据
│       ├── mcp_config.json  ← Workspace 级 MCP 配置
│       └── sessions/        ← 会话历史
├── agent/
│   └── <profile-id>.yaml   ← Agent Profile 配置
├── skills/                  ← 用户自定义 skill
│   └── <skill-name>/
│       └── SKILL.md
└── selfhost/                ← 自托管设置（EasyGateway 节点、mTLS 证书）

配置模型 Provider

在 UI 中配置（推荐）

打开 Settings → LLM Configuration，添加 provider，输入 API key，并选择默认模型。

通过文件配置（运维 / 自托管）

编辑 ~/.aiagent/config.yaml（推荐文件权限：0600）：

providers:
  - id: deepseek
    name: DeepSeek
    type: openai          # 支持：openai | anthropic | responsemode
    api_key: sk-...
    base_url: https://api.deepseek.com
    enabled: true
    models:
      - id: deepseek-chat
        name: DeepSeek Chat
        context_window: 65536
        supports_thinking: false
        supports_tools: true

  - id: anthropic
    name: Anthropic
    type: anthropic
    api_key: sk-ant-...
    base_url: https://api.anthropic.com
    enabled: true
    models:
      - id: claude-sonnet-4-5
        name: Claude Sonnet 4.5
        context_window: 200000
        max_output_tokens: 16000
        supports_thinking: true
        supports_tools: true

defaults:
  provider: deepseek
  model: deepseek-chat

支持的 type 取值：

type	说明
`openai`	OpenAI 兼容 API（DeepSeek、本地模型等同类端点）
`anthropic`	原生 Anthropic API（Claude 系列）
`responsemode`	OpenAI Responses API（适用于 gpt-4o 等模型）

用环境变量覆盖

环境变量优先级高于文件配置，适用于容器或 CI 环境：

export ANTHROPIC_API_KEY=sk-ant-...
export ANTHROPIC_BASE_URL=https://api.anthropic.com
export DEEPSEEK_API_KEY=sk-...

Agent Profile 配置

Agent Profile 控制 AI 的行为参数。每个 workspace 可绑定不同的 profile。

Profile 文件位于 ~/.aiagent/agent/<profile-id>.yaml：

model: "anthropic:claude-sonnet-4-5"   # providerId:modelId

language: zh           # UI 语言：zh | en | system

timeout_seconds: 18000  # 单轮对话超时（秒）

thinking:
  enabled: true          # 启用 extended thinking 模式（需要模型支持）
  budget: 32000          # Thinking token 预算

cache:
  enabled: true          # 启用上下文缓存以降低重复 token 成本
  cache_threshold: 5     # 触发缓存的对话轮次阈值

compression:
  enabled: true          # 启用自动上下文压缩，避免超出上下文上限
  threshold_percent: 85  # 上下文使用率达到该百分比时触发压缩（50~95）
  cooldown_seconds: 300  # 两次压缩之间的最小间隔

启动后端服务

基础启动

./aiagent

完整示例

./aiagent -port 8080 -data ~/.aiagent -mcp <mcp-server-url> -model <default-model>

参数	默认值	说明
`-port`	`8080`	HTTP 监听端口
`-data`	`~/.aiagent`	数据目录路径
`-mcp`	空	全局 MCP server URL
`-model`	空	兜底默认模型（优先级低于 `config.yaml`）

验证服务健康

# 健康检查（无需鉴权）
curl http://localhost:8080/health

# 版本信息
curl http://localhost:8080/api/version

agentui 与 aiagent 配对

agentui 首次连接 aiagent 后端时，必须从该后端 claim 一个本地凭证。这一步证明操作 UI 的人能够访问目标机器。

典型用户流程

启动 aiagent 并确认后端可达。
在 agentui 中输入后端 URL。
agentui 调用 GET /api/pairing/status。
如果后端尚未配对，agentui 会要求输入配对码。
在目标机器上从 本地 aiagent 日志 中读取当前的配对码，然后填入 agentui。
agentui 通过 POST /api/pairing/claim 提交配对码。
成功后，aiagent 将该节点标记为已配对，并返回长期 credential 与 node_id。
agentui 将凭证保存在本地，后续 API 与 WebSocket 访问都使用它。

重要行为

配对码是由 aiagent 生成的 6 位数字码，有效期为 24 小时。
GET /api/pairing/status 返回的配对状态包括 bound、pairing_required、pairing_expires_at、display_name 与 bootstrap_mode。
状态接口不会返回配对码本身。后端仍未配对时，aiagent 会把当前的配对码记录到本地 stdout/stderr。
如果你使用 macOS 桌面端 App 及其内置的本地后端，这些日志会被收集到：

~/Library/Application Support/com.example.agentui/flutter_logs.txt

配对完成后的行为

成功 claim 后：

受保护的 HTTP API 接受返回的 credential，可通过以下任一方式传递：
- Authorization: Bearer <credential>
- X-Aiagent-Credential: <credential>
WebSocket 连接也可以通过 agent_credential 查询参数携带凭证
如果用户已登录 Helix 账户，agentui 还可以将该已配对节点绑定到云端账户，便于在其他设备上恢复凭证
如果用户未登录，配对将仅限当前设备 本地有效

进阶 / 受管部署

某些受管或容器化部署使用一次性的 bootstrap_secret 替代人工输入的配对码。在这种情况下，agentui 仍通过 POST /api/pairing/claim 完成配对，但提交的字段是 bootstrap_secret 而不是 pairing_code。

常见错误

400 Bad Request：未提供 pairing_code 或 bootstrap_secret
401 Unauthorized：配对码 / bootstrap secret 无效或已过期，或后续请求使用了错误的凭证
409 Conflict：后端已配对

如需重新配对、轮换凭证或重置配对状态，请参阅本页后续介绍的受保护 self-host 端点。

Workspace 级配置

每个 workspace 都可以独立配置：

绑定 Agent Profile：选择不同的模型与行为预设
MCP Server：挂载项目专属工具链
上下文压缩：根据项目规模调优触发策略
上下文缓存：控制缓存时机以降低 API 成本

当不同项目需要不同的安全边界、工具链或模型策略时，Workspace 隔离是最佳实践。

Docker 部署

# docker-compose.yml
services:
  aiagent:
    image: aiagent:latest
    ports:
      - "8080:8080"
    volumes:
      - ~/.aiagent:/root/.aiagent
    environment:
      - GIN_MODE=release
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}

GIN_MODE=release 可降低 HTTP 访问日志的冗余度，更适合生产环境。

故障排查

后端无法访问

确认进程在运行：ps aux | grep aiagent
确认端口与监听地址：curl http://localhost:8080/health
检查防火墙与网络策略

模型 Provider 报错

确认 API key 有效
确认该 provider 下存在对应的 model ID
检查账户配额与访问限制
确认 base_url 正确（不要带末尾斜杠）

Workspace 工具不可用

确认 workspace 目录路径有效
检查代码智能所需的语言标记文件是否存在（例如 go.mod、package.json）
验证 MCP server 配置中的命令路径可执行

查看日志

Agent 后端日志输出到 stdout/stderr。在 macOS 桌面端，UI 会捕获后端输出并写入：

~/Library/Application Support/com.example.agentui/flutter_logs.txt

最近 2000 行会被保留。

API 鉴权

管理类 API 需要在请求头中携带凭证：

curl http://localhost:8080/api/config/providers \
  -H "X-Aiagent-Credential: <credential>"

下列端点无需鉴权，适合健康检查与监控：

GET /health
GET /api/version
GET /api/pairing/status

数据目录布局​

配置模型 Provider​

在 UI 中配置（推荐）​

通过文件配置（运维 / 自托管）​

用环境变量覆盖​

Agent Profile 配置​

启动后端服务​

基础启动​

完整示例​

验证服务健康​

agentui 与 aiagent 配对​

典型用户流程​

重要行为​

配对完成后的行为​

进阶 / 受管部署​

常见错误​

Workspace 级配置​

Docker 部署​

故障排查​

后端无法访问​

模型 Provider 报错​

Workspace 工具不可用​

查看日志​

API 鉴权​

相关文档​