概念

OpenClaw 支援 slash commands（/new, /status, /model 等）。這些指令不經過 LLM，直接由 Gateway 處理。

核心檔案

src/auto-reply/
├── command-detection.ts     # 指令偵測
├── command-auth.ts          # 指令授權
├── commands-registry.ts     # 指令註冊
└── commands/
    ├── new.ts               # /new, /reset
    ├── status.ts            # /status
    ├── model.ts             # /model
    ├── thinking.ts          # /thinking
    ├── verbose.ts           # /verbose
    ├── ping.ts              # /ping
    └── ...更多

指令偵測

檔案：src/auto-reply/command-detection.ts

export type CommandDetection = {
  command: string;     // 指令名稱
  args: string;        // 參數
  raw: string;         // 原始文字
};

export function detectCommand(text: string): CommandDetection | null {
  const trimmed = text.trim();
  
  // 必須以 / 開頭
  if (!trimmed.startsWith("/")) {
    return null;
  }
  
  // 解析指令和參數
  const match = trimmed.match(/^\/(\w+)(?:\s+(.*))?$/s);
  if (!match) {
    return null;
  }
  
  return {
    command: match[1].toLowerCase(),
    args: match[2]?.trim() ?? "",
    raw: trimmed,
  };
}

指令註冊

檔案：src/auto-reply/commands-registry.ts

export type CommandHandler = (params: {
  args: string;
  ctx: MsgContext;
  cfg: OpenClawConfig;
  dispatcher: ReplyDispatcher;
}) => Promise<CommandResult>;

export type CommandDefinition = {
  name: string;
  aliases?: string[];
  description: string;
  handler: CommandHandler;
  requiresAuth?: boolean;
};

export const COMMANDS_REGISTRY: CommandDefinition[] = [
  {
    name: "new",
    aliases: ["reset"],
    description: "Start a new session",
    handler: handleNewCommand,
  },
  {
    name: "status",
    description: "Show session status",
    handler: handleStatusCommand,
  },
  {
    name: "model",
    description: "Change or show current model",
    handler: handleModelCommand,
  },
  {
    name: "thinking",
    description: "Toggle extended thinking",
    handler: handleThinkingCommand,
  },
  {
    name: "verbose",
    description: "Toggle verbose mode",
    handler: handleVerboseCommand,
  },
  {
    name: "ping",
    description: "Check if bot is alive",
    handler: handlePingCommand,
  },
  // ...更多指令
];

/new 指令

檔案：src/auto-reply/commands/new.ts

export async function handleNewCommand(params: {
  args: string;
  ctx: MsgContext;
  cfg: OpenClawConfig;
}): Promise<CommandResult> {
  const { ctx, cfg } = params;
  
  // 取得當前 session
  const sessionKey = ctx.SessionKey;
  const storePath = resolveStorePath(ctx);
  const store = await loadSessionStore(storePath);
  const entry = store[sessionKey];
  
  if (entry?.sessionId) {
    // Archive 現有 session
    await archiveSessionTranscripts({
      sessionId: entry.sessionId,
      reason: "reset",
    });
  }
  
  // 建立新 session
  const newSessionId = crypto.randomUUID();
  await updateSessionStore(storePath, {
    ...store,
    [sessionKey]: {
      sessionId: newSessionId,
      updatedAt: Date.now(),
    },
  });
  
  return {
    reply: "🔄 Session reset. Fresh start!",
  };
}

/status 指令

檔案：src/auto-reply/commands/status.ts

export async function handleStatusCommand(params: {
  ctx: MsgContext;
  cfg: OpenClawConfig;
}): Promise<CommandResult> {
  const { ctx, cfg } = params;
  
  // 收集狀態資訊
  const sessionEntry = await resolveSessionEntry(ctx);
  const modelConfig = resolveModelConfig(cfg, ctx.AgentId);
  
  const status = [
    `📊 **Session Status**`,
    ``,
    `• Session: \`${sessionEntry.sessionId.slice(0, 8)}...\``,
    `• Model: ${modelConfig.primary}`,
    `• Tokens: ${sessionEntry.totalTokens ?? 0}`,
    `• Updated: ${formatRelativeTime(sessionEntry.updatedAt)}`,
  ];
  
  if (sessionEntry.modelOverride) {
    status.push(`• Override: ${sessionEntry.modelOverride}`);
  }
  
  return { reply: status.join("\n") };
}

/model 指令

檔案：src/auto-reply/commands/model.ts

export async function handleModelCommand(params: {
  args: string;
  ctx: MsgContext;
}): Promise<CommandResult> {
  const { args, ctx } = params;
  
  if (!args) {
    // 顯示當前 model
    const current = await resolveCurrentModel(ctx);
    return { reply: `Current model: ${current}` };
  }
  
  // 設定新 model
  const newModel = args.trim();
  
  // 驗證 model 存在
  if (!isValidModel(newModel)) {
    return { reply: `❌ Unknown model: ${newModel}` };
  }
  
  // 更新 session
  await updateSessionModelOverride(ctx.SessionKey, newModel);
  
  return { reply: `✅ Model set to: ${newModel}` };
}

指令授權

檔案：src/auto-reply/command-auth.ts

export function resolveCommandAuthorization(params: {
  command: string;
  ctx: MsgContext;
  cfg: OpenClawConfig;
}): { authorized: boolean; reason?: string } {
  const { command, ctx, cfg } = params;
  
  // 某些指令需要 admin 權限
  const adminCommands = ["restart", "config", "debug"];
  if (adminCommands.includes(command)) {
    const adminIds = cfg.commands?.adminIds ?? [];
    if (!adminIds.includes(ctx.From)) {
      return { authorized: false, reason: "Admin only" };
    }
  }
  
  return { authorized: true };
}

常用指令

指令	說明
`/new`, `/reset`	開始新 session
`/status`	顯示 session 狀態
`/model [name]`	切換/顯示 model
`/thinking [on/off]`	切換 extended thinking
`/verbose [on/off]`	切換 verbose mode
`/ping`	檢查連線
`/help`	顯示可用指令

💡 關鍵洞察

指令不經過 LLM
- 直接由 Gateway 處理
- 回應速度快
Aliases 方便使用
- /new 和 /reset 是一樣的
- 可以自訂更多 aliases
部分指令需要授權
- Admin 指令只有特定用戶可以用
- 在 config 設定 adminIds
指令可以帶參數
- /model opus 切換到 opus
- /thinking on 開啟 thinking

🔗 核心檔案

功能	檔案
指令偵測	`src/auto-reply/command-detection.ts`
指令註冊	`src/auto-reply/commands-registry.ts`
指令授權	`src/auto-reply/command-auth.ts`
/new	`src/auto-reply/commands/new.ts`
/status	`src/auto-reply/commands/status.ts`

明天： Hooks 系統 — 擴展 OpenClaw 行為

Day 13: Commands 系統