OpenClaw源码剖析 #02 · Gateway 控制平面：API 路由与协议

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

const BOOT_FILENAME = "BOOT.md";

function buildBootPrompt(content: string) {
  return [
    "You are running a boot check. Follow BOOT.md instructions exactly.",
    "",
    "BOOT.md:",
    content,
    "",
    "If BOOT.md asks you to send a message, use the message tool.",
    `After sending, reply with ONLY: ${SILENT_REPLY_TOKEN}.`,
    `If nothing needs attention, reply with ONLY: ${SILENT_REPLY_TOKEN}.`,
  ].join("\n");
}

1
2
3
4

type BootRunResult =
  | { status: "skipped"; reason: "missing" | "empty" }
  | { status: "ran" }
  | { status: "failed"; reason: string };

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

type CallGatewayBaseOptions = {
  url?: string;           // Gateway URL
  token?: string;         // 认证 token
  password?: string;      // 密码
  tlsFingerprint?: string; // TLS 指纹
  config?: OpenClawConfig; // 配置对象
  method: string;          // 调用的方法名
  params?: unknown;       // 方法参数
  expectFinal?: boolean;  // 等待最终响应
  timeoutMs?: number;     // 超时
  clientName?: GatewayClientName;
  clientDisplayName?: string;
  clientVersion?: string;
  platform?: string;
  mode?: GatewayClientMode;
  deviceIdentity?: DeviceIdentity | null;
  instanceId?: string;
  minProtocol?: number;
  maxProtocol?: number;
  requiredMethods?: string[];
};

1
2
3
4
5
6
7
8
9

// 作用域调用（需要显式权限）
export type CallGatewayScopedOptions = CallGatewayBaseOptions & {
  scopes: OperatorScope[];
};

// CLI 调用（可选权限）
export type CallGatewayCliOptions = CallGatewayBaseOptions & {
  scopes?: OperatorScope[];
};

1
2
3
4
5

// GATEWAY_CLIENT_MODES 定义了不同的客户端模式
type GatewayClientMode = /* 客户端模式枚举 */;

// GATEWAY_CLIENT_NAMES 定义了客户端名称
type GatewayClientName = /* 客户端名称枚举 */;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// 认证核心流程
interface AuthResult {
  success: boolean;
  token?: string;
  error?: string;
}

async function authenticate(
  credentials: Credentials,
  config: AuthConfig
): Promise<AuthResult>;

1
2
3
4
5
6

// 不同的认证模式
type AuthMode =
  | "token"        // Token 认证
  | "password"    // 密码认证
  | "device"       // 设备认证
  | "anonymous";   // 匿名

1
2
3
4
5
6
7

// 凭证解析优先级
type GatewayCredentialPrecedence = [
  "env",           // 环境变量
  "config",        // 配置文件
  "interactive",  // 交互式输入
  "keychain",      // 系统密钥链
];

1
2
3
4
5

interface RateLimitConfig {
  maxAttempts: number;
  windowMs: number;
  lockoutMs: number;
}

1
2
3
4
5

type GatewayCredentialMode =
  | "env"           // 环境变量
  | "config"        // 配置文件
  | "interactive"  // 交互式
  | "secret";      // 密钥管理

1
2
3
4

// 从多种来源解析凭证
export async function resolveGatewayCredentials(
  options: CallGatewayBaseOptions
): Promise<GatewayCredentials>;

1
2
3
4
5

// 密钥输入处理
export function resolveGatewayCredentialsWithSecretInputs(
  secretInputs: SecretInputs,
  config: OpenClawConfig
): Promise<GatewayCredentials>;

1
2
3
4
5

import { PROTOCOL_VERSION } from "./protocol/index.js";

// 协议版本检查
const minProtocol: number = /* 最小支持版本 */;
const maxProtocol: number = /* 最大支持版本 */;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

// 操作员权限范围
type OperatorScope =
  | "gateway:read"     // 读取网关状态
  | "gateway:write"   // 修改网关配置
  | "channel:manage"   // 管理渠道
  | "session:read"     // 读取会话
  | "session:write";   // 修改会话

// 解析方法需要的最小权限
function resolveLeastPrivilegeOperatorScopesForMethod(
  method: string
): OperatorScope[];

// 判断方法是否属于某权限类
function isGatewayMethodClassified(
  method: string,
  scope: OperatorScope
): boolean;

1
2
3
4

// 解析会话 Key
function resolveAgentIdFromSessionKey(sessionKey: string): string;
function resolveMainSessionKey(agentId: string): string;
function resolveAgentMainSessionKey(agentId: string): string;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// 加载会话存储
function loadSessionStore(
  storePath: string,
  options?: { skipCache?: boolean }
): SessionStore;

// 更新会话存储
function updateSessionStore(
  storePath: string,
  updater: (store: SessionStore) => void
): void;

1
2
3
4
5
6
7
8
9

interface SessionEntry {
  sessionKey: string;
  agentId: string;
  createdAt: number;
  updatedAt: number;
  lastActiveAt: number;
  messages: Message[];
  metadata?: Record<string, unknown>;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

interface GatewayConnectionDetails {
  url: string;
  port: number;
  protocol: "http" | "https" | "ws" | "wss";
  auth?: {
    token?: string;
    username?: string;
  };
  tls?: {
    enabled: boolean;
    fingerprint?: string;
  };
}

// 构建连接详情（带域名解析）
function buildGatewayConnectionDetailsWithResolvers(
  config: OpenClawConfig
): GatewayConnectionDetails;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

interface ChannelHealth {
  channelId: string;
  status: "healthy" | "degraded" | "down";
  lastCheckAt: number;
  latencyMs?: number;
  errorRate?: number;
}

// 监控所有渠道的健康状态
async function monitorChannelHealth(): Promise<ChannelHealth[]>;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

interface HealthPolicy {
  maxLatencyMs: number;
  maxErrorRate: number;
  checkIntervalMs: number;
  recoveryIntervalMs: number;
}

// 默认策略
const DEFAULT_HEALTH_POLICY: HealthPolicy = {
  maxLatencyMs: 5000,
  maxErrorRate: 0.05,
  checkIntervalMs: 60000,
  recoveryIntervalMs: 300000,
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

interface AuditEvent {
  timestamp: number;
  clientId: string;
  method: string;
  params: unknown;
  result: "success" | "failure";
  error?: string;
  durationMs: number;
}

// 记录审计事件
function recordAuditEvent(event: AuditEvent): void;

1
2
3
4
5

// 过滤敏感参数
function sanitizeAuditParams(
  method: string,
  params: Record<string, unknown>
): Record<string, unknown>;