エージェントハーネスプラグイン

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

harness を使う場面

• thread と compaction を所有する native coding-agent server
• native plan/reasoning/tool event を stream する必要がある local CLI または daemon
• OpenClaw session transcript に加えて独自の resume id を必要とする model runtime

​

core が引き続き所有するもの

• provider と model
• runtime auth state
• thinking level と context budget
• OpenClaw transcript/session file
• workspace、sandbox、tool policy
• channel reply callback と streaming callback
• model fallback と live model switching policy

• provider-aware tool schema policy 用の runtimePlan.tools.normalize(...) と runtimePlan.tools.logDiagnostics(...)
• transcript sanitization と tool-call repair policy 用の runtimePlan.transcript.resolvePolicy(...)
• 共有 NO_REPLY と media delivery suppression 用の runtimePlan.delivery.isSilentPayload(...)
• model fallback classification 用の runtimePlan.outcome.classifyRunResult(...)
• 解決済み provider/model/harness metadata 用の runtimePlan.observability

​

harness を登録する

import type { AgentHarness } from "openclaw/plugin-sdk/agent-harness";
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

const myHarness: AgentHarness = {
  id: "my-harness",
  label: "My native agent harness",

  supports(ctx) {
    return ctx.provider === "my-provider"
      ? { supported: true, priority: 100 }
      : { supported: false };
  },

  async runAttempt(params) {
    // Start or resume your native thread.
    // Use params.prompt, params.tools, params.images, params.onPartialReply,
    // params.onAgentEvent, and the other prepared attempt fields.
    return await runMyNativeTurn(params);
  },
};

export default definePluginEntry({
  id: "my-native-agent",
  name: "My Native Agent",
  description: "Runs selected models through a native agent daemon.",
  register(api) {
    api.registerAgentHarness(myHarness);
  },
});

​

選択 policy

1. model-scoped runtime policy が優先されます。
2. 次に provider-scoped runtime policy が続きます。
3. auto は、登録済み harness に対して、解決済みの provider/model を support するかを問い合わせます。
4. 一致する登録済み harness がない場合、PI fallback が disabled でない限り OpenClaw は PI を使用します。

​

Provider と harness の組み合わせ

• 推奨される user model ref: openai/gpt-5.5
• compatibility ref: legacy codex/gpt-* ref は引き続き受け入れられますが、新しい config では通常の provider/model ref として使用すべきではありません
• harness id: codex
• auth: synthetic provider availability。Codex harness が native Codex login/session を所有するためです
• app-server request: OpenClaw は bare model id を Codex に送信し、harness に native app-server protocol と通信させます

​

Tool-result middleware

​

Terminal outcome classification

​

Native Codex harness mode

​

Runtime strictness

{
  "models": {
    "providers": {
      "openai": {
        "agentRuntime": {
          "id": "codex"
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "model": "openai/gpt-5.5"
    }
  }
}

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-7",
      "models": {
        "anthropic/claude-opus-4-7": {
          "agentRuntime": {
            "id": "claude-cli"
          }
        }
      }
    }
  }
}

{
  "agents": {
    "list": [
      {
        "id": "codex-only",
        "model": "openai/gpt-5.5",
        "models": {
          "openai/gpt-5.5": {
            "agentRuntime": { "id": "codex" }
          }
        }
      }
    ]
  }
}

{
  "agents": {
    "defaults": {
      "agentRuntime": {
        "id": "codex"
      }
    }
  }
}

​

Native session と transcript mirror

• channel-visible session history
• transcript search と indexing
• 後続ターンで組み込み PI harness に戻すこと
• generic /new、/reset、session deletion behavior

​

Tool と media result

​

現在の制限

• public import path は generic ですが、一部の attempt/result type alias は compatibility のためにまだ Pi 名を持っています。
• third-party harness installation は実験的です。native session runtime が必要になるまでは provider Plugin を推奨します。
• harness switching はターン間で support されています。native tool、approval、assistant text、または message send が開始された後、ターンの途中で harness を切り替えないでください。

​

関連

• SDK の概要
• ランタイムヘルパー
• プロバイダーPlugin
• Codex ハーネス
• モデルプロバイダー