内置 Agent 配置

当前内置 Agent 后端是 claude，由 Claude Agent SDK 实现。AxonX 管理会话身份、Job 工具桥接和状态目录；SDK 管理模型调用及自身执行选项。

启用默认内置 Agent

先完成快速开始，在启动目录的 .env 中配置服务 token 和模型环境：

AXONX_SERVICE_TOKEN=replace-with-your-local-service-token
CLAUDE_CODE_API_KEY=your-model-api-key
CLAUDE_CODE_BASE_URL=https://api.anthropic.com
CLAUDE_CODE_MODEL_NAME=your-model-name

替换为可用提供方的凭据、Claude 兼容地址和模型名。CLI 会发现当前目录或父目录中的 .env，已有环境变量优先。配置完整示例见 example.env。

运行 axonx start，在 Studio 设置本机服务 token，再进入 Agent。服务已经运行时，修改 .env 后需重启。默认配置已启用 Agent 组件，无需先创建 YAML。后续章节用于调整工具、指南、存储和 SDK 选项。

外部 Agent 由宿主管理模型环境，见外部 Agent。

基础配置

自定义服务配置继承 default，覆盖 Agent 组件即可：

extends: default
components:
  agent:
    default:
      backend: claude
      setting_sources: [project]
      state_dir: agent/claude
      session_store:
        backend: local
        path: agent/session-store
      job_tools:
        - list_entries
        - preview_file
        - list_task_ids
        - list_task_statuses
        - status
        - read_task_log
        - get_task_graph
        - get_task_context

此配置展示字段结构；模型与权限设置继续继承默认值。服务启动时会校验 Job 名称是否已配置，名单不能为空字符串、不允许重复；字符串不能代替列表。

内置开发指南

应用级 language 支持 en（默认）和 zh，在需要指南的 Agent 上开启 load_dev_guide：

extends: default
language: zh
components:
  agent:
    default:
      load_dev_guide: true

load_dev_guide 默认是 false，关闭时不读取也不注入指南。开启后，Agent 在启动时读取一次对应语言的完整开发指南。修改语言、开关或指南后需重启服务。没有应用上下文时使用 en；不支持的语言值会被拒绝。

Claude 后端将指南追加到已有系统提示词，保留 preset 的其他选项和原有 append 内容。字符串提示词在原文后追加；未配置提示词时使用 Claude Code preset。对于 type: file 提示词，后端以 UTF-8 读取文件并在原文后追加指南；相对路径基于 Agent 的 cwd 解析。新建和恢复会话的每一轮都使用启动时加载的同一份指南，不会累积重复内容。

language 只选择内置指南，不强制回复语言，Studio 仍使用自己的语言设置。指南资源随 Python 包分发；开启时若资源缺失或无法读取，启动失败。源码仓库中的资源链接到 docs/en/dev_guide.md 和 docs/zh/dev_guide.md，维护时只需编辑这两份原文。指南中的插件路径相对于源码仓库，并非 Agent 工作区。

模型环境

默认配置把服务环境中的变量映射到 SDK 子进程：

服务环境变量	SDK 环境用途
CLAUDE_CODE_API_KEY	ANTHROPIC_AUTH_TOKEN
CLAUDE_CODE_BASE_URL	ANTHROPIC_BASE_URL
CLAUDE_CODE_MODEL_NAME	ANTHROPIC_MODEL 及默认模型别名

export CLAUDE_CODE_API_KEY='<模型凭据>'
export CLAUDE_CODE_BASE_URL='<兼容后端地址>'
export CLAUDE_CODE_MODEL_NAME='<可用模型名>'

配置的具体地址与模型名由可用后端决定。AxonX 当前没有内置“选择任意模型后端”的适配目录，不应把一个 env 映射解释为所有服务兼容。

components.agent.default.env 是 SDK 子进程环境覆盖，框架会合并 Application 环境与该映射。不要把模型密钥放入会话提示或文件预览示例。

框架管理字段

字段	默认行为	说明
backend	默认配置 claude	当前内置实现
load_dev_guide	false	追加应用级 language 对应的内置开发指南
job_tools	组件构造默认空列表，默认配置给出八个查询 Job	进程内 AxonX MCP 工具名单
state_dir	agent/claude	用于 SDK 配置目录，按组件名称再分一层
session_store.backend	local	当前仅支持 local
session_store.path	agent/session-store	会话存储根目录
cwd	工作区根目录	SDK 选项，由框架解析执行目录

状态路径相对工作区解析，绝对状态路径也必须位于工作区内。默认组件名为 default 时，SDK 配置目录是 <workspace>/agent/claude/default。

cwd 为空时使用工作区；相对 cwd 必须在工作区内，绝对 cwd 可指向其他目录。这会改变项目设置发现及会话项目身份，应先明确执行范围。

如果子进程环境显式设置 CLAUDE_CONFIG_DIR，框架不会再生成默认配置目录。会话 session_store.path 与 SDK 配置目录是不同用途，不要混为同一个缓存。

SDK 选项与权限

组件剩余关键字必须是当前安装 SDK 的 ClaudeAgentOptions 字段；未知选项会在构造时失败。字段随 SDK 版本可能变化，以实际依赖版本与运行校验为准。

默认配置包含 permission_mode: bypassPermissions、setting_sources: [project]、session_store_flush: batched 以及 Claude Code preset system prompt。默认追加提示要求以 AxonX 身份回答，并先查询实际工作区证据。

setting_sources: [project] 只声明加载项目级 Claude 设置，不意味着 SDK 自身工具被禁用。可选 skills 与 local plugins 属于 SDK 选项，默认配置中只是注释示例：

# 以下为 SDK 配置示例，具体值需匹配安装的 SDK
components:
  agent:
    default:
      skills: all
      plugins:
        - type: local
          path: /path/to/skills-plugin

路径示例需替换成服务机器上的实际插件位置。修改 SDK 权限模式或工具限制时使用该版本明确支持的值，并验证项目设置的影响。

Job 工具暴露

AxonX 把名单中的 Job 映射为 mcp__axonx__<job-name>，追加到 SDK allowed_tools；名单外 Job 不经这条桥接暴露。已有 mcp_servers 不能占用保留名 axonx。

默认八个 Job 用于任务和文件查询，但 allowed_tools 的桥接名单不等于 SDK 整体安全策略。SDK 自身文件、命令工具及 project/plugins 可能具备其他能力，尤其默认 bypassPermissions 不会把所有动作变成只读。

如果增加 submit 或 cancel，会改变 Agent 可调用的工作区操作。配置名单是能力授权，需要结合服务账号权限、cwd、SDK 工具和项目设置一起审查实际效果。

会话字段由框架管理

不能在组件 SDK 选项中手工配置 resume、session_id、continue_conversation 或 session_store 来取代 AxonX 会话管理。后端为新会话生成 UUID，续接通过请求中的 session_id，并始终使用框架会话存储。

每个 session_id 有独立轮次锁；同一会话的执行串行。运行中删除会话被拒绝，停止轮次调用 SDK interrupt，不等同于取消研究 Task。

调用深度

默认 agent_chat Step 的 max_depth 为 3，用于限制经过桥接的嵌套 Agent 调用链。当前深度达到限制时返回失败，不再调用模型。

jobs:
  agent_chat:
    steps:
      - backend: agent_stream
        max_depth: 3

这不是用户会话最多三次提问，也不是最多三次工具调用。内部深度参数由框架注入，不应作为普通用户参数手动维护。

应用与验证

配置更新后重启服务，先确认 Agent 组件能启动、Job 目录存在，再进行一个只查询已有任务的短轮次。检查实际工具块和最终结果，核对模型连接、cwd 和会话存储。

本页依据仓库的默认配置和适配层，没有发起实际模型请求。SDK 的外部能力和模型可用性需要在部署环境单独验证。

相关文档与实现

• Agent 使用、鉴权
• 默认配置
• Claude backend
• Job 工具桥接