OpenAI 兼容

使用 Hermes Agent 接入 IteraCompute

将终端智能体接入 IteraCompute。

三步完成连接

1. 创建 API Key

注册或登录 IteraCompute,然后在控制台创建 API Key。

2. 配置 Base URL

通过 chat_completions 配置命名自定义提供方。Python AIAgent 与 CLI 配置使用独立 profile。

3. 选择模型

使用准确的 API Model ID,启用智能体或视觉功能前确认上下文与模型能力。

选择模型

DeepSeek V4.1 Flash 1017 是付费参考模型,可替换为密钥允许访问的已上架对话模型。切换后请重新核对模型权限、价格、上下文与工具支持;配置示例随选择更新,保留的测试结果仍仅对应 Qwen。

准备隔离环境

使用隔离的 Hermes Agent v0.23.0 源码目录与 HERMES_HOME,在启动终端中设置 ITERACOMPUTE_API_KEY。

Bash / macOS / Linux / WSL
git clone --branch v0.23.0 --depth 1 \
  https://github.com/NousResearch/hermes-agent.git hermes-agent-v0.23.0
cd hermes-agent-v0.23.0
test "$(git rev-parse HEAD)" = \
  "2bd378ed1b8d6bf2192cb26e0a55ff3091e6bd19"
export HERMES_HOME="$PWD/.hermes-iteracompute-cli"
export HERMES_RUNTIME_DIR="$HERMES_HOME/tools"
umask 077
mkdir -p "$HERMES_HOME"
source ./activate
hermes --version
hermes pm doctor
Bash · 在当前终端输入密钥
umask 077
read -rsp 'IteraCompute API key: ' ITERACOMPUTE_API_KEY
printf '\n'
export ITERACOMPUTE_API_KEY

Hermes CLI 可能为未知自定义模型添加 reasoning_effort=medium。请按所选模型参数核对实际请求。下方 reasoning_config={} 是 Python 构造参数,不是 YAML 配置,也不能证明 CLI 已关闭推理。

配置示例

将 API Key 保存在服务端环境或工具凭据存储中;需要手动填写密钥的字段请使用自己的 API Key。

CLI · $HERMES_HOME/config.yaml
providers:
  iteracompute:
    api: https://api.iteracompute.com/v1
    key_env: ITERACOMPUTE_API_KEY
    transport: chat_completions
    default_model: deepseek/deepseek-v4.1-flash-1017
    context_length: 1048576
    discover_models: false
    extra_body:
      max_tokens: 512
model:
  provider: custom:iteracompute
  default: deepseek/deepseek-v4.1-flash-1017
  context_length: 1048576
  streaming: false
agent:
  max_turns: 3
  api_max_retries: 0
  auto_recovery_cycles: 0
fallback_providers: []
toolsets: [todo]
tools:
  tool_search:
    enabled: off
approvals:
  mode: manual
compression:
  enabled: false
auxiliary:
  title_generation:
    enabled: false
    model_upgrade_enabled: false

仅将配置保存到上方创建的隔离 profile。示例使用 Chat Completions,首次输出为 512 tokens,不设置 fallback。上下文元数据不等于账户权益;OpenClaw 使用更小的输入预算。选择 Qwen 时使用 128K 账户上下文。推理控制因模型而异:Python 与 OpenClaw 示例仅对 Qwen 添加 reasoning: false,不向其他模型套用该参数。

先检查直接 API

Python · 直接文本检查
python3 - <<'PY'
import json
import os
import urllib.error
import urllib.request
payload = {
    'model': 'deepseek/deepseek-v4.1-flash-1017',
    'messages': [{'role': 'user', 'content': 'Reply with exactly: ITERACOMPUTE_API_OK'}],
    'max_tokens': 512,
    **{},
}
request = urllib.request.Request(
    'https://api.iteracompute.com/v1/chat/completions',
    data=json.dumps(payload).encode('utf-8'),
    headers={'Authorization': 'Bearer ' + os.environ['ITERACOMPUTE_API_KEY'],
             'Content-Type': 'application/json'}, method='POST',
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as exc:
    raise SystemExit(f'HTTP {exc.code}; inspect redacted details privately') from None
except (urllib.error.URLError, TimeoutError):
    raise SystemExit('Network or timeout failure; no automatic retry') from None
choice = result['choices'][0]
if ((choice.get('message', {}).get('content') or '').strip() != 'ITERACOMPUTE_API_OK'
        or choice.get('finish_reason') != 'stop'):
    raise SystemExit('FAIL: expected final marker and stop reason not returned')
print('Direct API text passed; test the agent separately')
PY

运行时会发送一次真实请求。确认精确可见标记与 finish_reason=stop;HTTP 200 但正文为空不算完成。付费模型调用消耗 API 余额,结果不确定时不要自动重试。

检查智能体文本调用

Bash · 文本检查
hermes chat --oneshot --ignore-rules --toolsets todo --max-turns 2 \
  --format stream-json \
  -q 'Do not call tools. Reply with exactly: HERMES_ITERACOMPUTE_OK' \
  > hermes-text.private.jsonl 2> hermes-text.private.stderr

先运行下方直接 API 检查,再确认智能体返回非空最终标记、使用指定 provider/model,且正常退出。配置校验或 provider 探针不能证明智能体与工具流程已通过。

验证一次工具闭环

上方 CLI profile 是文档参考。验证 Python 路线时,在已激活的源码目录内创建另一个 HERMES_HOME,将下方配置保存为其中的 config.yaml,Python 脚本保存为 iteracompute_agent_smoke.py。两份配置不能混用。

Bash · 独立 Python 配置
export HERMES_HOME="$PWD/.hermes-iteracompute-python"
mkdir -p "$HERMES_HOME"
Python 配置 · config.yaml
model:
  provider: custom
  default: deepseek/deepseek-v4.1-flash-1017
  base_url: https://api.iteracompute.com/v1
  streaming: false
providers:
  custom:
    request_timeout_seconds: 240
    stale_timeout_seconds: 240
tools:
  tool_search:
    enabled: off
agent:
  api_max_retries: 0
  auto_recovery_cycles: 0
fallback_providers: []
compression:
  enabled: false
auxiliary:
  title_generation:
    enabled: false
    model_upgrade_enabled: false
iteracompute_agent_smoke.py
import os
from run_agent import AIAgent

agent = AIAgent(
    provider="custom",
    api_mode="chat_completions",
    base_url="https://api.iteracompute.com/v1",
    api_key=os.environ["ITERACOMPUTE_API_KEY"],
    model="deepseek/deepseek-v4.1-flash-1017",
    enabled_toolsets=["todo"],
    max_iterations=3,
    max_tokens=512,
    run_budget_seconds=600,
    reasoning_config={},
    request_overrides={"extra_body": {}},
    skip_context_files=True,
    skip_memory=True,
    skip_background_review=True,
    load_soul_identity=False,
    save_trajectories=False,
    quiet_mode=True,
    fallback_model={},
)
try:
    result = agent.run_conversation(
        "Call todo_list exactly once to write one item with id smoke-1, "
        "content API smoke test, and status completed. Then read the tool result "
        "and reply with exactly HERMES_ITERACOMPUTE_TOOL_OK. Do not use other tools."
    )
    if not (result.get("completed") is True and
            (result.get("final_response") or "").strip() == "HERMES_ITERACOMPUTE_TOOL_OK"):
        raise SystemExit("FAIL: inspect redacted details privately")
    print("Final marker passed; verify actual todo_list events separately")
finally:
    agent.close()
Bash · 运行 Python 智能体
python iteracompute_agent_smoke.py

成功标准:检查真实 todo_list 调用、已完成的 smoke-1 项、工具结果回传,以及最终 HERMES_ITERACOMPUTE_TOOL_OK 回复。脚本仅检查最终标记,工具事件须单独核对。三次迭代与关闭配置重试不构成严格 HTTP 请求次数或费用上限。

版本与验证

测试版本
Hermes Agent v0.23.0
测试结果
Python 非流式工具调用通过。

凭据、工具与数据

模型 API 在云端运行,无需本地 GPU 或公开 Gateway 端口;智能体仍需要本地 CPU、内存与权限。密钥仅从启动进程环境读取,原始日志保持私有,仅开放测试必需工具。外部工具与服务需要独立配置,并可能另行收费。

测试连接

cURL · Chat Completions
# Bash / zsh / WSL; set ITERACOMPUTE_API_KEY in your environment first.
curl --fail-with-body https://api.iteracompute.com/v1/chat/completions \
  -H "Authorization: Bearer $ITERACOMPUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek/deepseek-v4.1-flash-1017","messages":[{"role":"user","content":"Reply with exactly: Hello!"}],"max_tokens":512}'

确认 choices[0].message.content 包含可见文本;HTTP 200 本身不够。推理可能消耗输出预算。免费 Auto 可使用首次免费调用示例关闭思考,再在工具中发送提示。

所选模型的能力

能力表示 IteraCompute 接口的支持情况。工作流程中的可用性也取决于工具与配置,推理参数因模型而异。

  • 对话生成支持
  • 工具调用支持
  • 推理支持
  • 图像输入支持
  • 流式输出支持

故障排除

401 / 403 / 404

检查启动进程密钥、模型权限与付费余额。Base URL 只保留一次 /v1。API 使用原始 Model ID;iteracompute/ 前缀仅用于 OpenClaw 内部路由。

400 / 空回复 / 429

检查模型专属推理参数、输出预算与账户限制,遵循 Retry-After。不要叠加推理参数方言、根据 HTTP 200 宣称成功,或自动切换其他付费模型。

工具缺失 / Profile 错误

Hermes:todo 测试关闭 tool_search,Python 与 CLI profile 分开。OpenClaw:工具测试将 deny-all 替换为只读策略;此自定义配置不要添加 --isolated 或 --auth-env-only。

Hermes Agent 官方配置参考 →

通过 Hermes Agent 开始构建。

连接 API Key,选择模型,发送第一个请求。