> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# SessionConfig

> 通过 Laravel Copilot SDK 的 SessionConfig 配置工具、MCP、钩子、代理与生命周期事件。

## SessionConfig

通过 `SessionConfig` 类可以进行各种设置。

按 `Copilot::run(prompt: '...', config: $config)` 或 `Copilot::start(function (CopilotSession $session) { ... }, config: $config)` 的方式使用。
当你只是想指定模型这种无需用到 `SessionConfig` 类的情况时，也可以用数组指定。`Copilot::run(prompt: '...', config: ['model' => 'auto'])`

```php theme={null}
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\SystemMessageConfig;
use Revolution\Copilot\Types\InfiniteSessionConfig;
use Revolution\Copilot\Types\UserInputRequest;
use Revolution\Copilot\Types\Rpc\ModelCapabilitiesOverride;
use Revolution\Copilot\Types\Rpc\ModelCapabilitiesOverrideSupports;
use Revolution\Copilot\Types\Rpc\ModelCapabilitiesOverrideLimits;
use Revolution\Copilot\Enums\ReasoningEffort;

$config = new SessionConfig(
    // 指定要使用的模型
    model: 'auto',

    // 在创建新会话时指定固定的 session ID
    sessionId: 'session-123',

    clientName: 'my-app',

    // 推理级别。仅在支持的模型上可设置。
    reasoningEffort: ReasoningEffort::HIGH,

    // 覆盖模型的 capabilities。会与运行时的默认值 deep-merge。
    // modelCapabilities: new ModelCapabilitiesOverride(
    //     supports: new ModelCapabilitiesOverrideSupports(vision: true, reasoningEffort: true),
    //     limits: new ModelCapabilitiesOverrideLimits(max_prompt_tokens: 200000),
    // ),
    // 也可以用数组指定
    // modelCapabilities: ['supports' => ['vision' => true]],

    // 覆盖 config 目录
    configDirectory: '',

    // 启用 MCP 配置和技能目录的自动发现
    // 会从工作目录自动发现 .mcp.json 或 .vscode/mcp.json，
    // 并与显式指定的 mcpServers 或 skillDirectories 合并（名称冲突时显式指定优先）
    enableConfigDiscovery: true,

    // 自定义工具
    tools: [...],

    // 系统消息
    systemMessage: new SystemMessageConfig(
        content: 'You are a helpful assistant for Laravel developers.',
    ),

    // 系统消息：replace 模式（完全替换 system prompt）
    // systemMessage: new SystemMessageConfig(
    //     mode: 'replace',
    //     content: '自定义的完整 system prompt',
    // ),

    // 系统消息：customize 模式（按段落覆盖）
    // systemMessage: new SystemMessageConfig(
    //     mode: 'customize',
    //     sections: [
    //         'tone' => new SectionOverride(action: SectionOverrideAction::REPLACE, content: 'Always respond in Japanese.'),
    //         'safety' => new SectionOverride(action: SectionOverrideAction::REMOVE),
    //         'custom_instructions' => new SectionOverride(action: SectionOverrideAction::APPEND, content: 'Additional instructions here.'),
    //     ],
    //     content: '与 append 模式类似的追加内容（可选）',
    // ),

    // 自定义提供商
    provider: new ProviderConfig(),

    // 每个会话独立的 GitHub token（多租户支持）
    // 可以在客户端级别 github_token 之外，按会话指定 token
    gitHubToken: $user->github_token,

    // 远程会话的行为模式
    // 'off' - 仅本地（默认）
    // 'export' - 将会话事件导出到 GitHub（不带远程 steering）
    // 'on' - 同时启用导出和远程 steering
    remoteSession: \Revolution\Copilot\Enums\RemoteSessionMode::Export,

    // 云端会话（不在本地而是在云端创建会话）
    // 可以选择性地关联仓库信息
    cloud: new \Revolution\Copilot\Types\CloudSessionOptions(
        repository: new \Revolution\Copilot\Types\CloudSessionRepository(
            owner: 'myorg',
            name: 'myrepo',
            branch: 'main',
        ),
    ),

    onPermissionRequest: function (array $request) {
        // 处理权限请求
    },

    onUserInputRequest: function (UserInputRequest $request) {
        // 处理用户输入请求。ask_user
    },

    // Elicitation 请求处理器
    // 设置后可以接收来自代理的基于表单的 UI 对话请求
    onElicitationRequest: function (ElicitationContext $context) {
        // 处理 elicitation 请求
        return ['action' => 'accept', 'content' => ['field' => 'value']];
    },

    // Plan 模式退出请求处理器
    // 设置后可以在代理退出 plan 模式时接收请求
    onExitPlanModeRequest: function (ExitPlanModeRequest $request) {
        // 检查 plan 内容并批准 / 拒绝
        return new ExitPlanModeResult(approved: true, selectedAction: $request->recommendedAction);
    },

    // 自动模式切换请求处理器
    // 在达到速率限制时，可以选择是否允许切换到 auto 模式
    onAutoModeSwitchRequest: function (AutoModeSwitchRequest $request) {
        // 返回 "yes"、"yes_always"、"no" 之一
        return 'yes';
    },

    // 会话钩子
    hooks: [],

    // 工作目录
    workingDirectory: '',

    // 启用流式输出
    streaming: true,

    // 是否将子代理的流式事件包含到主流中（默认: true）
    includeSubAgentStreamingEvents: true,

    // 可用的内置工具
    availableTools: ['read_file', 'write_file'],

    // 或者要排除的工具
    excludedTools: ['shell'],

    // MCP 服务器配置
    mcpServers: [
        'github' => [
            'type' => 'http',
            'url' => 'https://api.githubcopilot.com/mcp/',
        ],
    ],

    // 自定义代理
    customAgents: [
        [
            'name' => 'reviewer',
            'displayName' => 'Code Reviewer',
            'description' => 'Reviews code for best practices',
            'prompt' => 'You are an expert code reviewer.',
        ],
    ],

    // 默认代理配置。当没有选择自定义代理时使用的内置代理配置。
    // excludedTools: 从默认代理中排除的工具列表。
    // 对自定义子代理仍然可用。
    defaultAgent: ['excludedTools' => ['tool_name']],

    // 指定会话启动时激活的代理。需要与 customAgents 的 name 一致。
    agent: 'reviewer',

    // 技能目录
    skillDirectories: [],

    // 已禁用的技能
    disabledSkills: [],

    // 无限会话配置。默认启用。
    infiniteSessions: new InfiniteSessionConfig(
        enabled: true,
        backgroundCompactionThreshold: 0.80, // 上下文使用率达到 80% 时开始压缩
        bufferExhaustionThreshold: 0.95,     // 直到压缩完成前在 95% 时阻塞
    ),

    // 禁用无限会话
    // infiniteSessions: new InfiniteSessionConfig(enabled: false),

    // 在会话创建 RPC 之前注册事件处理器。
    // 用于避免遗漏 session.start 等早期事件。
    // 与之后调用 $session->on($handler) 等价，但在生命周期更早阶段注册。
    onEvent: function (SessionEvent $event) {
        // 接收所有会话事件
    },
);

$response = Copilot::run('...', config: $config);
```

会话恢复时使用 `ResumeSessionConfig` 类。它与 `SessionConfig` 几乎相同，只有一点点差异。ResumeSessionConfig 只指定要变更的配置项。其他会沿用新建会话时的配置。

云端执行请参考 [Cloud Sessions](/zh/packages/laravel-copilot-sdk/cloud-sessions)，Plugin Directory 请参考 [Plugin Directories](/zh/packages/laravel-copilot-sdk/plugin-directories)。

<Info>
  最新信息请参考 [GitHub 仓库](https://github.com/invokable/laravel-copilot-sdk)。
</Info>


## Related topics

- [Cloud Sessions](/zh/packages/laravel-copilot-sdk/cloud-sessions.md)
- [自定义代理](/zh/packages/laravel-copilot-sdk/custom-agents.md)
- [Skills](/zh/packages/laravel-copilot-sdk/skills.md)
- [快速开始 - GitHub Copilot SDK for Laravel](/zh/packages/laravel-copilot-sdk/getting-started.md)
- [流式事件](/zh/packages/laravel-copilot-sdk/streaming-events.md)