十分钟跑通第一个任务

安装

Nexus 要求 Python 3.10–3.13（本条核于 2026-09-13）。

⚠️ 两个时间相关的提醒（2026-10-02 核）：

1. 下限 3.10 已于 2026-10-01 到达官方 EOL（最后一版 3.10.22）。若你在 2026-10 之后新装环境，建议直接从 3.12 或 3.13 起步，不要用已 EOL 的解释器。
2. 上限 3.13 之外已有 3.14（2025-10-07 发布，当前 3.14.8）。本章所述区间是否包含 3.14 尚未核实——若你已装 3.14 且安装失败，请回退到 3.13 再试，并以 nexus modules 的输出为准。

# 如果你已有 Python 环境
pip install tencent-nexus \
  --extra-index-url https://mirrors.tencent.com/repository/pypi/tencent_pypi/simple

# 如果需要从头搭建
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv --python 3.13
source .venv/bin/activate
pip install tencent-nexus \
  --extra-index-url https://mirrors.tencent.com/repository/pypi/tencent_pypi/simple

安装完成后验证：

nexus modules

这会列出所有已发现的模块及其依赖状态。看到一堆绿色的 ✓ 就说明安装成功了。

YAML 配置文件解剖

Nexus 的一切都从一个 YAML 配置文件开始。下面是最小可运行的配置：

# test.yaml — 最小示例
task_name: "echo"
task_config:
  message: "Hello, Nexus!"
  run_oracle: false

runtime_provider_name: "docker"
runtime_configs:
  main:
    worker_venv: false

agent_name: "demo_agent"
agent_config:
  max_iterations: 10

openai_clients:
  main:
    name: "openai"
    config:
      client_args:
        api_key: "${oc.env:OPENAI_API_KEY}"
        base_url: "https://api.openai.com/v1"
      request_args:
        model: "${oc.env:MODEL_NAME}"

processors:
  chat:
    name: "chat_tracker"

逐块解读：

task_name + task_config

指定要执行的 Task 和它的参数。echo 是 Nexus 内置的教学任务——它要求 Agent 把指定消息写入 /tmp/echo.txt，然后验证文件内容。

Task 名通过注册系统查找。echo 对应 nexus/extensions/tasks/echo.py 中的 @task_registry.register('echo')。

runtime_provider_name + runtime_configs

配置运行时环境。这里选了 docker，意味着 Nexus 会：

1. 检查本地是否有 nexus-runtime 镜像（没有会自动构建）
2. 启动一个 Docker 容器
3. 在容器内启动 Runtime Server（FastAPI + Socket.IO）
4. 通过 HTTP 与容器通信

worker_venv: false 表示不在沙箱内创建额外的 Python 虚拟环境。对大多数任务来说这就够了。

agent_name + agent_config

指定 Agent。demo_agent 是 Nexus 的教学 Agent，它实现了一个基本的 tool-calling 循环。max_iterations: 10 限制最多调用 10 轮工具。

openai_clients

LLM 配置。main 是默认客户端名——Agent 通过 ctx.openai_client 获取它。

注意 ${oc.env:OPENAI_API_KEY} 语法——这是 OmegaConf 的环境变量插值。Nexus 在加载配置时会自动解析。同理，model: "${oc.env:MODEL_NAME}" 表示模型名由环境变量提供、不给默认值——运行前请先 export MODEL_NAME=<你的目标模型>。本书示例不预设具体模型名，以免随版本腐烂。

processors

数据处理器。chat_tracker 会记录完整的对话轨迹，可在 RunOutput.processor_results['chat'] 中获取。

三种常用 Runtime Provider（共 6 种）

在跑之前，选对 Runtime 很重要。

Nexus 实际内置 6 种 Runtime Provider，本章只覆盖本地开发最常用的 3 种。完整清单与选型对比见第 1 章：

Provider	底层环境	适合场景	本章
local	当前进程	本地调试	✅ 讲
docker	Docker 容器	本地开发	✅ 讲
gongfeng	远端沙箱	生产评测	✅ 讲
ags	腾讯云 AGS	云端弹性	见 Ch01
android_websocket	Android 沙箱	移动端测试	见 Ch01
android_cloudtest	真机云设备	真机交互	见 Ch01

如果你要做的是移动端 / GUI Agent 评测，请直接翻到第 1 章——那两个 Android Provider 是 Nexus 相对通用 Agent 框架最不一样的地方，本章不会涉及。

方式一：local（最快，无隔离）

runtime_provider_name: "local"

所有操作直接在当前进程执行。适合本地调试，不适合跑需要隔离的 benchmark（Agent 会直接操作你的文件系统）。

方式二：docker（推荐本地开发）

runtime_provider_name: "docker"

需要本地安装 Docker。首次运行会自动构建 nexus-runtime 镜像（约 5 分钟）。也可以手动预构建：

nexus build-runtime -f

构建完成后会看到 nexus-runtime:X.Y.Z 镜像。后续运行会自动复用。

方式三：gongfeng（远端沙箱，适合批量）

runtime_provider_name: "gongfeng"
runtime_provider_config:
  token: "${oc.env:GONGFENG_TOKEN}"

使用工蜂统一沙箱服务，无需本地 Docker。适合大规模批量评测场景。

实际跑一下

# 设置 API Key
export OPENAI_API_KEY="your-api-key"

# 跑任务
nexus run-single test.yaml

你会看到类似这样的输出：

INFO  Starting runner for task: echo (run_id: a1b2c3d4e5f6)
INFO  Acquiring runtime 'main'...
INFO  Runtime 'main' acquired successfully
INFO  Executing task: echo
INFO  Running agent: demo_agent
...
INFO  Task completed: echo
INFO  Task output:
  score: 1.0
  message_found: true

score: 1.0 表示 Agent 成功完成了任务。

如果想把结果保存到文件：

nexus run-single test.yaml -o result.json

配置的环境变量插值

Nexus 使用 OmegaConf 处理配置文件，支持环境变量插值：

# 从环境变量读取
api_key: "${oc.env:OPENAI_API_KEY}"

# 带默认值
max_iterations: "${oc.env:MAX_ITER,10}"

注意：代码补丁、prompt 等自由文本字段中的 ${...} 会被自动转义，不会被 OmegaConf 解析。

💡 为什么本节的示例不写具体模型名：旧版示例写的是 model: "gpt-4o"。教学示例里写死模型名必然腐烂——本书上一版（2026-09）曾在这里列举”当期主流编码模型”作为佐证，到 2026-10 那三个系列都已换代。本节只保留机制：从环境变量读、不设默认值——MODEL_NAME 由你自己指定目标模型。这既避免了名称随时间失效，本身也是 OmegaConf 插值的正确用法。

⚠️ 一条从这次自我腐烂里得出的写作规则：用”列举当期型号”来论证”不该写死型号”，本身就是一个新的腐烂源。 腐烂的不是论断（“写死模型名必然腐烂”永远成立），而是支撑论断的举证方式。凡”以当前状态举例”的论证，都必须自证它抗腐烂——否则它会先于论断失效。

🔎 一条可执行的自检（低成本、可复用）：若本书仓库要做自动化检查，可在示例代码块中 grep 具体模型名、具体版本号、具体价格数字，命中即告警。本章这两处腐烂（写死的 gpt-4o、列举的”当期主流型号”）都能被这条规则在写入当天抓到，而不必等到 19 天后靠人工扫描发现。

常见问题排查

Q: ModuleNotFoundError: No module named 'xxx'

运行 nexus modules 查看哪些模块缺依赖，然后：

nexus modules install <module_name>
# 或者一次性装全部
nexus modules install --all

为什么需要先 nexus modules：nexus 的依赖发现与注册机制见第 7 章（注册系统）。

Q: Docker 构建失败

检查 Docker 是否正在运行。如果在公司环境需要代理：

export NEXUS_DOCKER_CMD="sudo -n docker"
nexus build-runtime -f

想理解镜像是怎么被构建与复用的，见第 10 章（Runtime 系统：沙箱的一切）。

Q: Runtime 连接超时

Socket.IO 连接有 20 次重试（指数退避）。如果容器启动慢，可能需要等待。检查容器日志：

docker logs <container_id>

重试策略与 Runtime 生命周期见第 10 章（Runtime 系统）；批量跑时这些超时如何被并发调度放大，见第 13 章（Runner 与批量执行）。

Q: ContextLengthExceededError

Agent 的对话超过了 LLM 的上下文长度限制。可以在 agent_config 中配置 compaction（上下文压缩），或减少 max_iterations。

compaction 的完整策略——触发阈值、压缩边界、与 Trace 的关系——见第 15 章（上下文管理与 Compaction）；这些配置如何被 Runner 装配进一次运行，见第 13 章（Runner 与批量执行）。

下一章我们接入一个真正的 benchmark。

📌 给两条阅读路径的分流：到这里你已经能跑通一个任务了。想继续”赶时间”，直接去第 3 章接入 benchmark；如果你开始好奇”为什么一个 YAML 就能装配出这么多东西”，从第 7 章（注册系统）开始按路径 B 读——这正是 Ch00 承诺的”遇到’为什么这样设计’的困惑时，跳到对应的原理章节”。