Spacebot完整配置教程从config.toml到Anthropic OAuth认证的每一步详解【免费下载链接】spacebotAn AI agent for teams, communities, and multi-user environments.项目地址: https://gitcode.com/gh_mirrors/spac/spacebotSpacebot 是一款面向团队、社区和多用户环境的开源 AI Agent 框架。本教程带你从零完成 Spacebot 配置编写第一个 config.toml、接入 LLM 模型密钥并掌握 Anthropic OAuth 认证5 分钟让 AI 助理跑起来。准备工作三种启动方式怎么选安装 Spacebot 后官方提供了三种配置入口新手按场景选择即可环境变量最快只需设置ANTHROPIC_API_KEYSpacebot 会自动创建一个默认mainAgent无需任何配置文件交互式引导直接运行spacebot若未检测到任何配置会引导你依次选择模型供应商、填入密钥、命名 Agent配置文件推荐手动创建~/.spacebot/config.toml可完整控制模型路由、消息渠道、定时任务等所有行为 三种方式可混合使用配置文件优先未覆盖的设置会回退到环境变量最后使用内置默认值。配置文件的存放位置Spacebot 按以下顺序查找配置文件位置说明~/.spacebot/config.toml默认位置推荐$SPACEBOT_DIR/config.toml通过环境变量覆盖实例根目录适合开发/生产双实例spacebot --config /path/to.toml命令行临时指定首次启动后~/.spacebot/目录会自动生成完整的数据结构Agent 身份文件SOUL.md、IDENTITY.md、ROLE.md、工作区workspace/、SQLite 与向量数据库等。完整目录布局可参考官方文档 config.mdx/config.mdx)。第一步配置 LLM 模型密钥[llm]段是配置的核心——实例级密钥所有 Agent 共享至少需要配置一个[llm] anthropic_key env:ANTHROPIC_API_KEY openai_key env:OPENAI_API_KEY密钥的三种引用方式Spacebot 的字符串值支持三种解析模式这是配置安全的关键设计前缀来源推荐度secret:名称从加密密钥库读取⭐ 最推荐env:变量名从系统环境变量读取⭐ 推荐无直接写值明文不推荐使用secret:前缀可将明文密钥迁入加密存储配置文件中不再出现真实密钥。此外即使 TOML 中完全没写密钥Spacebot 也会自动回退检查ANTHROPIC_API_KEY、OPENAI_API_KEY等常见环境变量。自定义模型供应商除内置的 Anthropic、OpenAI、OpenRouter、Groq 等 15 家供应商外还可以通过自定义 Provider 接入任意兼容端点如本地 LLM、Azure OpenAI[llm.provider.local_llm] api_type openai_completions base_url http://localhost:8080 api_key env:LOCAL_LLM_KEY name Local LLaMA Server第二步设置模型路由Spacebot 将不同任务分配给不同模型实现性能与成本的平衡。[defaults.routing]控制五类进程的模型进程类型作用默认模型channel用户对话Claude Sonnet 4branch深度思考分支Claude Sonnet 4worker任务执行Claude Haiku 4.5compactor历史压缩Claude Haiku 4.5cortex系统观察者Claude Haiku 4.5模型名以供应商/模型名格式书写例如anthropic/claude-sonnet-4-20250514。还可以配置fallbacks 回退链主模型限流或故障时自动切换到备用模型保证服务不中断。第三步创建 Agent 并接入消息渠道定义你的 Agent至少需要一个 Agent第一个或标记default true的为默认 Agent[[agents]] id main default true每个 Agent 拥有独立的工作区、数据库和身份文件身份文件修改后会热加载无需重启。接入消息平台Spacebot 原生支持 Discord、Slack、Telegram、Twitch、Email、Signal、Mattermost 和 Webhook。以 Discord 为例[messaging.discord] enabled true token env:DISCORD_BOT_TOKEN用 Bindings 路由消息[[bindings]]决定哪个平台的对话交给哪个 Agent按顺序匹配、首条命中生效[[bindings]] agent_id main channel discord配置多 Agent 时可用guild_id、channel_ids等字段把不同频道精准分流给不同 Agent。各平台的完整字段说明见 messaging 目录文档/messaging.mdx)。第四步Anthropic OAuth 认证详解如果你有 Claude Pro/Max 订阅无需申请 API Key——Spacebot 内置了完整的 Anthropic OAuth 认证流程一条命令完成授权spacebot auth login登录流程是如何工作的命令行打印一个授权 URL 并自动打开浏览器在浏览器中登录 Claude 账户并授权授权码回填到终端Spacebot 通过PKCE 安全流程换取访问令牌凭据保存到~/.spacebot/anthropic_oauth.json文件权限自动设为0600仅当前用户可读写认证实现细节可参考源码 auth.rs 和 CLI 命令实现 cli/auth.rs。两种登录模式命令授权来源适用场景spacebot auth loginClaude Pro/Max 订阅claude.ai订阅用户spacebot auth login --consoleAnthropic API ConsoleAPI 账户用户 注意OAuth 凭据会被系统识别为已配置状态——即使没有config.toml和 API Key只要登录过 OAuth首次启动引导也会自动跳过。日常认证管理spacebot auth status # 查看令牌是否有效、剩余有效期 spacebot auth refresh # 手动刷新访问令牌 spacebot auth logout # 登出并删除本地凭据令牌自动刷新机制Spacebot 在每次 API 调用前检查令牌状态当访问令牌**临近过期提前 5 分钟**时会自动用 refresh_token 静默换取新令牌整个过程无感。认证路径检测逻辑位于 anthropic/auth.rs——以sk-ant-oat前缀开头的令牌会自动走 OAuth Bearer 认证通道而sk-ant-api前缀走标准 API Key 通道二者无需任何额外配置即可区分。配置热加载哪些改动不用重启修改config.toml后Spacebot 通过文件监听器在 2 秒去抖后自动热加载大部分设置模型路由、压缩阈值、Agent 身份文件、技能文件、消息渠道适配器等全部即时生效。但以下改动需要重启进程LLM API 密钥供应商客户端在启动时初始化一次Agent 拓扑变更新增/删除[[agents]]因为数据库和事件总线按 Agent 隔离数据库路径⚠️ 小贴士修改完密钥后记得执行spacebot restart使认证变更生效。验证配置是否成功启动 Spacebot 并打开 Web 控制台spacebot start -f -d # 前台 调试日志推荐首次运行访问http://localhost:19898能看到 Agent 状态、消息渠道连接情况即配置成功。若配置有误Spacebot 会在启动日志中给出具体报错字段Docker 部署用户也可直接查看容器日志。常见问题 FAQQ1不写 config.toml 能运行吗可以。设置ANTHROPIC_API_KEY环境变量即可进入纯环境变量模式Spacebot 会用默认配置创建一个 main Agent。Q2开发环境和生产环境会冲突吗不会。设置不同的SPACEBOT_DIR环境变量即可完全隔离两套实例的数据库、配置和日志详见 quickstart.mdx/quickstart.mdx)。Q3OAuth 登录失败了怎么办先用spacebot auth status查看当前凭据状态令牌过期可执行spacebot auth refresh彻底重置则spacebot auth logout后重新login。Q4想给不同 Agent 用不同模型在对应 Agent 下添加[agents.routing]段覆盖[defaults.routing]未覆盖的字段自动继承实例默认值。总结步骤关键配置是否热加载模型密钥[llm]段 env:/secret:引用需重启模型路由[defaults.routing]✅Agent 定义[[agents]]拓扑变更需重启消息渠道[messaging.*][[bindings]]✅OAuth 认证spacebot auth login自动刷新配置完成后你的 Spacebot 团队 AI 就已经就绪——连接 Discord 频道、 它开始对话吧【免费下载链接】spacebotAn AI agent for teams, communities, and multi-user environments.项目地址: https://gitcode.com/gh_mirrors/spac/spacebot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Spacebot完整配置教程：从config.toml到Anthropic OAuth认证的每一步详解
Spacebot完整配置教程从config.toml到Anthropic OAuth认证的每一步详解【免费下载链接】spacebotAn AI agent for teams, communities, and multi-user environments.项目地址: https://gitcode.com/gh_mirrors/spac/spacebotSpacebot 是一款面向团队、社区和多用户环境的开源 AI Agent 框架。本教程带你从零完成 Spacebot 配置编写第一个 config.toml、接入 LLM 模型密钥并掌握 Anthropic OAuth 认证5 分钟让 AI 助理跑起来。准备工作三种启动方式怎么选安装 Spacebot 后官方提供了三种配置入口新手按场景选择即可环境变量最快只需设置ANTHROPIC_API_KEYSpacebot 会自动创建一个默认mainAgent无需任何配置文件交互式引导直接运行spacebot若未检测到任何配置会引导你依次选择模型供应商、填入密钥、命名 Agent配置文件推荐手动创建~/.spacebot/config.toml可完整控制模型路由、消息渠道、定时任务等所有行为 三种方式可混合使用配置文件优先未覆盖的设置会回退到环境变量最后使用内置默认值。配置文件的存放位置Spacebot 按以下顺序查找配置文件位置说明~/.spacebot/config.toml默认位置推荐$SPACEBOT_DIR/config.toml通过环境变量覆盖实例根目录适合开发/生产双实例spacebot --config /path/to.toml命令行临时指定首次启动后~/.spacebot/目录会自动生成完整的数据结构Agent 身份文件SOUL.md、IDENTITY.md、ROLE.md、工作区workspace/、SQLite 与向量数据库等。完整目录布局可参考官方文档 config.mdx/config.mdx)。第一步配置 LLM 模型密钥[llm]段是配置的核心——实例级密钥所有 Agent 共享至少需要配置一个[llm] anthropic_key env:ANTHROPIC_API_KEY openai_key env:OPENAI_API_KEY密钥的三种引用方式Spacebot 的字符串值支持三种解析模式这是配置安全的关键设计前缀来源推荐度secret:名称从加密密钥库读取⭐ 最推荐env:变量名从系统环境变量读取⭐ 推荐无直接写值明文不推荐使用secret:前缀可将明文密钥迁入加密存储配置文件中不再出现真实密钥。此外即使 TOML 中完全没写密钥Spacebot 也会自动回退检查ANTHROPIC_API_KEY、OPENAI_API_KEY等常见环境变量。自定义模型供应商除内置的 Anthropic、OpenAI、OpenRouter、Groq 等 15 家供应商外还可以通过自定义 Provider 接入任意兼容端点如本地 LLM、Azure OpenAI[llm.provider.local_llm] api_type openai_completions base_url http://localhost:8080 api_key env:LOCAL_LLM_KEY name Local LLaMA Server第二步设置模型路由Spacebot 将不同任务分配给不同模型实现性能与成本的平衡。[defaults.routing]控制五类进程的模型进程类型作用默认模型channel用户对话Claude Sonnet 4branch深度思考分支Claude Sonnet 4worker任务执行Claude Haiku 4.5compactor历史压缩Claude Haiku 4.5cortex系统观察者Claude Haiku 4.5模型名以供应商/模型名格式书写例如anthropic/claude-sonnet-4-20250514。还可以配置fallbacks 回退链主模型限流或故障时自动切换到备用模型保证服务不中断。第三步创建 Agent 并接入消息渠道定义你的 Agent至少需要一个 Agent第一个或标记default true的为默认 Agent[[agents]] id main default true每个 Agent 拥有独立的工作区、数据库和身份文件身份文件修改后会热加载无需重启。接入消息平台Spacebot 原生支持 Discord、Slack、Telegram、Twitch、Email、Signal、Mattermost 和 Webhook。以 Discord 为例[messaging.discord] enabled true token env:DISCORD_BOT_TOKEN用 Bindings 路由消息[[bindings]]决定哪个平台的对话交给哪个 Agent按顺序匹配、首条命中生效[[bindings]] agent_id main channel discord配置多 Agent 时可用guild_id、channel_ids等字段把不同频道精准分流给不同 Agent。各平台的完整字段说明见 messaging 目录文档/messaging.mdx)。第四步Anthropic OAuth 认证详解如果你有 Claude Pro/Max 订阅无需申请 API Key——Spacebot 内置了完整的 Anthropic OAuth 认证流程一条命令完成授权spacebot auth login登录流程是如何工作的命令行打印一个授权 URL 并自动打开浏览器在浏览器中登录 Claude 账户并授权授权码回填到终端Spacebot 通过PKCE 安全流程换取访问令牌凭据保存到~/.spacebot/anthropic_oauth.json文件权限自动设为0600仅当前用户可读写认证实现细节可参考源码 auth.rs 和 CLI 命令实现 cli/auth.rs。两种登录模式命令授权来源适用场景spacebot auth loginClaude Pro/Max 订阅claude.ai订阅用户spacebot auth login --consoleAnthropic API ConsoleAPI 账户用户 注意OAuth 凭据会被系统识别为已配置状态——即使没有config.toml和 API Key只要登录过 OAuth首次启动引导也会自动跳过。日常认证管理spacebot auth status # 查看令牌是否有效、剩余有效期 spacebot auth refresh # 手动刷新访问令牌 spacebot auth logout # 登出并删除本地凭据令牌自动刷新机制Spacebot 在每次 API 调用前检查令牌状态当访问令牌**临近过期提前 5 分钟**时会自动用 refresh_token 静默换取新令牌整个过程无感。认证路径检测逻辑位于 anthropic/auth.rs——以sk-ant-oat前缀开头的令牌会自动走 OAuth Bearer 认证通道而sk-ant-api前缀走标准 API Key 通道二者无需任何额外配置即可区分。配置热加载哪些改动不用重启修改config.toml后Spacebot 通过文件监听器在 2 秒去抖后自动热加载大部分设置模型路由、压缩阈值、Agent 身份文件、技能文件、消息渠道适配器等全部即时生效。但以下改动需要重启进程LLM API 密钥供应商客户端在启动时初始化一次Agent 拓扑变更新增/删除[[agents]]因为数据库和事件总线按 Agent 隔离数据库路径⚠️ 小贴士修改完密钥后记得执行spacebot restart使认证变更生效。验证配置是否成功启动 Spacebot 并打开 Web 控制台spacebot start -f -d # 前台 调试日志推荐首次运行访问http://localhost:19898能看到 Agent 状态、消息渠道连接情况即配置成功。若配置有误Spacebot 会在启动日志中给出具体报错字段Docker 部署用户也可直接查看容器日志。常见问题 FAQQ1不写 config.toml 能运行吗可以。设置ANTHROPIC_API_KEY环境变量即可进入纯环境变量模式Spacebot 会用默认配置创建一个 main Agent。Q2开发环境和生产环境会冲突吗不会。设置不同的SPACEBOT_DIR环境变量即可完全隔离两套实例的数据库、配置和日志详见 quickstart.mdx/quickstart.mdx)。Q3OAuth 登录失败了怎么办先用spacebot auth status查看当前凭据状态令牌过期可执行spacebot auth refresh彻底重置则spacebot auth logout后重新login。Q4想给不同 Agent 用不同模型在对应 Agent 下添加[agents.routing]段覆盖[defaults.routing]未覆盖的字段自动继承实例默认值。总结步骤关键配置是否热加载模型密钥[llm]段 env:/secret:引用需重启模型路由[defaults.routing]✅Agent 定义[[agents]]拓扑变更需重启消息渠道[messaging.*][[bindings]]✅OAuth 认证spacebot auth login自动刷新配置完成后你的 Spacebot 团队 AI 就已经就绪——连接 Discord 频道、 它开始对话吧【免费下载链接】spacebotAn AI agent for teams, communities, and multi-user environments.项目地址: https://gitcode.com/gh_mirrors/spac/spacebot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考