OpenAI 兼容

使用 OpenClaw 接入 IteraCompute

构建文本与只读工具工作流。

三步完成连接

1. 创建 API Key

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

2. 配置 Base URL

添加使用 openai-completions 与环境变量 SecretRef 的 iteracompute 提供方,在 OpenClaw 内使用完整 provider/model 引用。

3. 选择模型

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

选择模型

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

准备隔离环境

在独立目录安装 OpenClaw 2026.11.1。保留的智能体测试使用 Bun 1.4.4;配置与状态须隔离。

Bash / macOS / Linux / WSL
# Node: >=24.16.0 <25 or >=26.1.0; npm <=11.15
node --version
npm --version
umask 077
mkdir -p itera-openclaw-demo
cd itera-openclaw-demo
export ITERA_RUNTIME="$PWD/runtime"
npm install --prefix "$ITERA_RUNTIME" openclaw@2026.11.1 bun@1.4.4 \
  --no-audit --no-fund
export BUN="$ITERA_RUNTIME/node_modules/.bin/bun"
export OPENCLAW_ENTRY="$ITERA_RUNTIME/node_modules/openclaw/openclaw.mjs"
"$BUN" --version
"$BUN" "$OPENCLAW_ENTRY" --version
mkdir -p workspace state home
export OPENCLAW_HOME="$PWD/home"
export OPENCLAW_STATE_DIR="$PWD/state"
export OPENCLAW_CONFIG_PATH="$PWD/openclaw.iteracompute.json"
export OPENCLAW_OFFLINE=1
Bash · 在当前终端输入密钥
umask 077
read -rsp 'IteraCompute API key: ' ITERACOMPUTE_API_KEY
printf '\n'
export ITERACOMPUTE_API_KEY

安装命令适用于 npm 11.15 及之前版本;npm 11.16+/12 须按当前官方说明添加 --allow-scripts=openclaw。显式 Bun 入口对应保留的成功运行时。OPENCLAW_OFFLINE 禁止辅助组件下载,不会阻止模型 API。无需 daemon 或消息平台账号。

配置示例

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

openclaw.iteracompute.json
{
  "models": {
    "mode": "replace",
    "providers": {
      "iteracompute": {
        "baseUrl": "https://api.iteracompute.com/v1",
        "api": "openai-completions",
        "apiKey": {
          "source": "env",
          "provider": "default",
          "id": "ITERACOMPUTE_API_KEY"
        },
        "timeoutSeconds": 180,
        "models": [
          {
            "id": "deepseek/deepseek-v4.1-flash-1017",
            "name": "DeepSeek V4.1 Flash 1017",
            "reasoning": true,
            "input": [
              "text"
            ],
            "contextWindow": 1048576,
            "contextTokens": 110000,
            "maxTokens": 512,
            "compat": {
              "maxTokensField": "max_tokens",
              "supportsReasoningEffort": false,
              "supportsUsageInStreaming": true
            }
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "iteracompute/deepseek/deepseek-v4.1-flash-1017",
        "fallbacks": []
      },
      "modelPolicy": {
        "allow": [
          "iteracompute/deepseek/deepseek-v4.1-flash-1017"
        ]
      },
      "models": {
        "iteracompute/deepseek/deepseek-v4.1-flash-1017": {
          "alias": "itera-model",
          "params": {
            "maxTokens": 512,
            "extraBody": {}
          }
        }
      },
      "thinkingDefault": "off",
      "skipBootstrap": true,
      "contextInjection": "never"
    }
  },
  "tools": {
    "deny": [
      "*"
    ],
    "toolSearch": false
  },
  "plugins": {
    "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 · 文本检查
"$BUN" "$OPENCLAW_ENTRY" config validate --json
"$BUN" "$OPENCLAW_ENTRY" models list --provider iteracompute --json
"$BUN" "$OPENCLAW_ENTRY" agent exec \
  'Reply with exactly OPENCLAW_ITERACOMPUTE_TEXT_OK. Do not use tools.' \
  --config "$OPENCLAW_CONFIG_PATH" --cwd "$PWD/workspace" \
  --model iteracompute/deepseek/deepseek-v4.1-flash-1017 --code-mode direct \
  --thinking off --timeout 360 --json > text-result.private.json

python3 - <<'PY'
import json
from pathlib import Path
r = json.loads(Path('text-result.private.json').read_text(encoding='utf-8'))
if not (r.get('ok') is True and r.get('provider') == 'iteracompute'
        and r.get('model') == 'deepseek/deepseek-v4.1-flash-1017'
        and (r.get('final') or '').strip() == 'OPENCLAW_ITERACOMPUTE_TEXT_OK'):
    raise SystemExit('FAIL: inspect redacted details privately')
print('OpenClaw text invocation passed')
PY

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

验证一次工具闭环

文本检查通过后,脚本复制文本配置,并将整个 tools 策略替换为仅限工作区的 read 权限,移除 deny: ["*"],因为 deny 优先于 allow。随机标记仅写入文件,不放入提示词。

Bash · 只读工具与断言
python3 - <<'PY'
import json
import secrets
from pathlib import Path
config = json.loads(Path('openclaw.iteracompute.json').read_text(encoding='utf-8'))
config['tools'] = {
    'allow': ['read'], 'fs': {'workspaceOnly': True}, 'toolSearch': False,
}
Path('openclaw.iteracompute.tools.json').write_text(json.dumps(config), encoding='utf-8')
Path('workspace/integration-marker.txt').write_text(
    'OPENCLAW_ITERACOMPUTE_TOOL_' + secrets.token_hex(8) + '\n', encoding='utf-8')
PY

"$BUN" "$OPENCLAW_ENTRY" agent exec \
  'Use read to read integration-marker.txt, then reply with exactly the marker in that file. Do not guess or use other tools.' \
  --config "$PWD/openclaw.iteracompute.tools.json" --cwd "$PWD/workspace" \
  --model iteracompute/deepseek/deepseek-v4.1-flash-1017 --code-mode direct \
  --thinking off --timeout 600 --json > tool-result.private.json

python3 - <<'PY'
import json
from pathlib import Path
r = json.loads(Path('tool-result.private.json').read_text(encoding='utf-8'))
expected = Path('workspace/integration-marker.txt').read_text(encoding='utf-8').strip()
tools = r.get('toolSummary') or {}
checks = [r.get('ok') is True, r.get('provider') == 'iteracompute',
          r.get('model') == 'deepseek/deepseek-v4.1-flash-1017', tools.get('calls') == 1,
          tools.get('tools') == ['read'], tools.get('failures') == 0,
          r.get('assistantTurns') == 2, (r.get('final') or '').strip() == expected]
if not all(checks):
    raise SystemExit('FAIL: inspect redacted details privately')
print('OpenClaw read tool loop passed')
PY

成功标准:provider/model 正确、恰好一次成功的 read 调用、两个 assistant 回合,且最终回复与文件标记相符。模型声称读过文件不算通过。

版本与验证

测试版本
OpenClaw 2026.11.1 · Bun 1.4.4
测试结果
文本与只读工具调用通过。

凭据、工具与数据

模型 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。

OpenClaw 官方配置参考 →

通过 OpenClaw 开始构建。

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