收起侧栏

模型接入 Agent 工具指导文档

最近更新时间: 2026-10-10 17:24:59

模型接入 Agent 工具指导文档

本文介绍如何将中国电信的两款模型接入 TeleAgent、Claude Code、OpenCode 等 AI 工具。

准备两样东西

第 1 样：API Key（模型密钥）

API Key 就像一把"钥匙"，工具拿着它才能调用模型。

1、去模型服务平台控制台，在 API 管理/模型管理页面申请API Key。

2、模型 1：Xing4.0-29B-A4B 模型开通入口，

3、模型 2：TeleChat3-438B-A24B 模型开通入口，

第 2 样：Node.js（Claude Code 和 OpenCode 需要）

Claude Code 和 OpenCode 是基于 Node.js 的命令行工具，必须先装好它。

1、Windows

打开浏览器，访问下载
用命令行安装标注 “LTS”（长期稳定版）的版本
或者手动下载与电脑适配的.msi 安装包，双击运行安装包，一路点"下一步"完成安装
验证：按 Win + R，输入 powershell 回车打开终端，输入下面命令：

node -v

如果显示版本号（如 v20.11.0），说明安装成功

2、macOS

方式一：打开浏览器，访问下载，下载 macOS 版 .pkg，双击安装
方式二（推荐有 Homebrew 的用户）：打开"终端"，执行 brew install node
验证：在终端输入 node -v，显示版本号即成功

3、Linux

# Ubuntu / Debian
sudo apt update && sudo apt install -y nodejs npm

# CentOS / RHEL
sudo yum install -y nodejs npm

# 也可以用 nvm（推荐，灵活切版本）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20

验证：终端输入 node -v，显示版本号即成功。

一、TeleAgent

TeleAgent（星辰超级智能体）是中国电信自研的桌面智能体。

1. 安装

1.1 下载

打开浏览器，访问官网
选择你电脑对应的系统版本，下载安装包

1.2 安装

系统	安装方式
Windows	下载 .exe 安装包，双击运行，按提示选择安装路径，点击"安装"
macOS	下载 .dmg 安装包，打开后将 TeleAgent 图标拖入"应用程序"文件夹，自动完成安装
Linux	下载 .deb 或 .AppImage 包；.deb 双击安装，.AppImage 赋予执行权限后双击运行

安装完成后，桌面或应用程序列表中会出现 TeleAgent 图标，双击即可启动。

注意： TeleAgent 需要 v1.1.3 及以上版本才支持配置自定义模型供应商。

2. 配置

通过 UI 界面配置自定义模型供应商，按以下三步操作：

步骤一：点击左下角头像，点击「设置」

步骤二：点击「模型设置」，下拉到最下方，点击「添加」

步骤三：填写配置信息

添加兼容 OpenAI API 格式的模型服务商，填写名称、API 地址、模型 ID、上下文长度等参数：

两个模型的配置信息如下：

配置项	模型 1（星辰 29B）	模型 2（星辰 438B）
模型 ID	Xing4.0-29B-A4B	TeleChat3-438B-A24B
API 地址	https://openapi.teleagi.cn/aipaas/algo/v1/telechat-29b/v1	https://openapi.teleagi.cn/aipaas/algo/v1/telechat3-438b-a24b/v1
上下文长度	256000	256000
最大 Token 数	64000	64000

配置完成后，在对话框右下角选在您配置的模型后，即可对话框开始使用。

二、Claude Code

Claude Code 是一个运行在终端里的 AI 编程助手。

1. 安装 Claude Code

怎么打开终端：

系统	操作
Windows	按 Win + R，输入 powershell，回车
macOS	打开"启动台"→"其他"→"终端"（或搜索"Terminal"）
Linux	直接打开系统自带的终端

在终端里执行以下命令（三平台命令完全相同，直接复制粘贴）：

npm install -g @anthropic-ai/claude-code

等待安装完成（约 1~2 分钟）。然后验证：

claude --version

显示版本号即安装成功。如果提示"不是内部或外部命令"，说明 Node.js 没装好或没重启终端，回到前面重装 Node.js。

Windows版本：如果提示”程序'claude.exe'无法运行:拒绝访问。“，则在命令前增加sudo前缀。

2. 配置环境变量

对比维度	方式一 settings.json（推荐）	方式二 Windows 注册表	方式三 shell 配置文件	方式四临时变量
API Key是否落入终端历史	否（在编辑器里粘贴）	是	是	是
API Key存放位置	单个 JSON 文件	注册表	.zshrc/.bashrc	进程内存
生效范围	全部项目	全部项目	全部项目	仅当前窗口
重开终端后是否生效	是	是	是	否
清除凭据难度	删一个文件即可	逐条清理注册表	逐行删配置	关窗即清

结论：优先用方式一，安全、集中、好清理；方式四仅用于快速测试。方式之间不要重复配置同名变量，换方式时先清掉旧配置。

2.1 方式一：用户级 settings.json（推荐，三平台通用，安全 + 便捷 + 持久化）

配置文件位置：

系统	文件路径
Windows	C:\Users\你的用户名\.claude\settings.json
macOS	~/.claude/settings.json
Linux	~/.claude/settings.json

.claude 文件夹或 settings.json 不存在时，手动新建即可。用记事本、VS Code 等任意编辑器打开该文件，粘贴以下模板：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openapi.teleagi.cn/aipaas/algo/v1/telechat3-438b-a24b",
    "ANTHROPIC_AUTH_TOKEN": "把这里替换成你的API Key",
    "ANTHROPIC_MODEL": "TeleChat3-438B-A24B",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "TeleChat3-438B-A24B",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "TeleChat3-438B-A24B",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "TeleChat3-438B-A24B",
    "CLAUDE_CODE_SUBAGENT_MODEL": "TeleChat3-438B-A24B",
    "CLAUDE_CODE_EFFORT_LEVEL": "max",
    "CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT": "1"
  }
}

只需改两处：API Key 和模型三件套（BASE_URL + 5 个模型变量即 AUTH_TOKEN、OPUS_MODEL、SONNET_MODEL、HAIKU_MODEL、SUBAGENT_MODEL）。保存后，新启动的 claude 自动加载，无需重启终端；已开着的 claude 会话需退出重进一次。

安全加固（macOS/Linux 可选）：chmod 600 ~/.claude/settings.json，防止其他用户读取。

整个过程 API Key 只在编辑器里出现，不经过终端命令行，因此不会进入终端历史文件。

2.2 方式二：Windows 环境变量（写入注册表，永久生效）

打开 PowerShell，整段复制以下 9 行回车执行（先把 API Key 替换好）：

[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://openapi.teleagi.cn/aipaas/algo/v1/telechat3-438b-a24b", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "把这里替换成你的API Key", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_MODEL", "TeleChat3-438B-A24B", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_DEFAULT_OPUS_MODEL", "TeleChat3-438B-A24B", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_DEFAULT_SONNET_MODEL", "TeleChat3-438B-A24B", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_DEFAULT_HAIKU_MODEL", "TeleChat3-438B-A24B", "User")
[Environment]::SetEnvironmentVariable("CLAUDE_CODE_SUBAGENT_MODEL", "TeleChat3-438B-A24B", "User")
[Environment]::SetEnvironmentVariable("CLAUDE_CODE_EFFORT_LEVEL", "max", "User")
[Environment]::SetEnvironmentVariable("CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT", "1", "User")

写入注册表后，必须关闭当前终端，重新打开才能生效。

安全提醒：此命令会带着 API Key 进入 PowerShell 历史文件（%APPDATA%\Microsoft\Windows\PowerShell\PSReadLine\ConsoleHost_history.txt），介意的话请用方式一。

2.3 方式三：macOS / Linux 写入 shell 配置文件（永久生效）

在终端逐行执行以下命令（先把 API Key 替换好；bash 用户把 .zshrc 全部换成 .bashrc）：

echo 'export ANTHROPIC_BASE_URL="https://openapi.teleagi.cn/aipaas/algo/v1/telechat3-438b-a24b"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="把这里替换成你的API Key"' >> ~/.zshrc
echo 'export ANTHROPIC_MODEL="TeleChat3-438B-A24B"' >> ~/.zshrc
echo 'export ANTHROPIC_DEFAULT_OPUS_MODEL="TeleChat3-438B-A24B"' >> ~/.zshrc
echo 'export ANTHROPIC_DEFAULT_SONNET_MODEL="TeleChat3-438B-A24B"' >> ~/.zshrc
echo 'export ANTHROPIC_DEFAULT_HAIKU_MODEL="TeleChat3-438B-A24B"' >> ~/.zshrc
echo 'export CLAUDE_CODE_SUBAGENT_MODEL="TeleChat3-438B-A24B"' >> ~/.zshrc
echo 'export CLAUDE_CODE_EFFORT_LEVEL="max"' >> ~/.zshrc
echo 'export CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT="1"' >> ~/.zshrc
source ~/.zshrc

API Key 会随命令进入终端历史（~/.zsh_history / ~/.bash_history），介意的话请用方式一。

2.4 方式四：临时变量（仅当前窗口生效，快速测试用）

Windows PowerShell：

$env:ANTHROPIC_BASE_URL="https://openapi.teleagi.cn/aipaas/algo/v1/telechat3-438b-a24b"
$env:ANTHROPIC_AUTH_TOKEN="把这里替换成你的API Key"
$env:ANTHROPIC_MODEL="TeleChat3-438B-A24B"

macOS / Linux：

export ANTHROPIC_BASE_URL="https://openapi.teleagi.cn/aipaas/algo/v1/telechat3-438b-a24b"
export ANTHROPIC_AUTH_TOKEN="把这里替换成你的API Key"
export ANTHROPIC_MODEL="TeleChat3-438B-A24B"

关闭终端即失效。需要 opus/sonnet/haiku 映射等其他变量时，参照方式一模板按需补齐。

3. 验证配置是否生效

配置方式	环境检查	说明
方式一	无需环境检查，直接做功能验证	settings.json 的变量注入 claude 进程，echo 看不到是正常的
方式二	重开 PowerShell 后执行 echo$env:ANTHROPIC_AUTH_TOKEN	输出API Key即生效
方式三	新开终端执行 echo$ANTHROPIC_AUTH_TOKEN	输出API Key即生效
方式四	当前窗口直接做功能验证	关窗即失效

统一功能验证（最可靠）：在任意终端执行

claude -p "回复：配置成功"

模型返回“配置成功”即表示配置生效。

4. 进入项目目录，执行 claude

"项目目录"就是你要让它帮你写代码的文件夹。

cd 你的文件夹路径
claude

比如你的代码在 D:\myproject，就输入 cd D:\myproject，再输入 claude 回车。

第一次启动可能需要确认一些提示，按提示输入 y 回车即可。启动后你就可以直接用自然语言和它对话了。

运行效果（启动后的界面长这样）：

三、OpenCode

OpenCode 是开源的终端编程助手，特点是两个模型可以换着用。

1. 安装 OpenCode

三平台命令相同，在终端执行：

npm install -g @opencode-ai/cli

也可使用下载源手动安装

验证：

opencode2 --version

显示版本号即安装成功。

注意：建议升级到最新版本（≥ v1.14.24），旧版本可能有兼容性问题。

2. 配置

重要提示： OpenCode 桌面版 UI 不支持直接在界面中添加自定1义 Provider，正确做法是编辑配置文件。以下同时提供配置文件方式和 UI 界面参考效果图。

2.1 配置文件在哪

系统	配置文件路径
Windows	C:\Users\你的用户名\.config\opencode\opencode.jsonc
macOS	~/.config/opencode/opencode.jsonc
Linux	~/.config/opencode/opencode.jsonc

2.2 配置文件怎么创建

2.2.1 Windows

打开 PowerShell，逐行执行：

New-Item -ItemType Directory -Path "$env:USERPROFILE\.config\opencode" -Force

然后用记事本打开该路径下创建一个 opencode.jsonc 文件，把下面的"配置内容"粘贴进去。

2.2.2 macOS / Linux

mkdir -p ~/.config/opencode
nano ~/.config/opencode/opencode.jsonc

在编辑器里粘贴下面的"配置内容"，按 Ctrl + O 保存、Ctrl + X 退出。

2.3 配置内容

把下面两个 API Key 分别替换成你在开头申请的两个模型的 API Key：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "xinghe-telechat-29b": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "星辰4.0-29B",
      "options": {
        "baseURL": "https://openapi.teleagi.cn/aipaas/algo/v1/telechat-29b/v1",
        "apiKey": "把这里替换成你的API Key"
      },
      "models": {
        "Xing4.0-29B-A4B": {
          "name": "星辰4.0-29B-A4B"
        }
      }
    },
    "xinghe-telechat3-438b": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "TeleChat3-438B",
      "options": {
        "baseURL": "https://openapi.teleagi.cn/aipaas/algo/v1/telechat3-438b-a24b/v1",
        "apiKey": "把这里替换成你的API Key"
      },
      "models": {
        "TeleChat3-438B-A24B": {
          "name": "TeleChat3-438B-A24B"
        }
      }
    }
  }
}

3. 模型配置

配置完成后重启open code，在设置中打开模型选项并启用Xing4.0-29B-A4B和TeleChat3-438B-A24B模型在 OpenCode 界面中，可以通过修改配置文件的 "model" 字段来切换模型，也可以在项目目录新建 opencode.json 做项目级覆盖。

桌面版：

效果图 1：在设置中打开模型选项

效果图 2：使用模型问答

窗口版：

输入ctrl+x → 按键“M”，使用“↑” 、“↓”键或鼠标点击确认使用29b或者438b模型

终端版：

切换模型用/models

四、模型信息

model	BaseURL	协议类型	公网地址
Xing4.0-29B-A4B	https://api-maas.teleai.com.cn/v1	anthropic	https://api-maas.teleai.com.cn/v1/messages
openai	https://api-maas.teleai.com.cn/v1/chat/completions
responses	https://api-maas.teleai.com.cn/v1/responses
TeleChat3-438B-A24B	https://api-maas.teleai.com.cn/v1	anthropic	https://api-maas.teleai.com.cn/v1/messages
openai	https://api-maas.teleai.com.cn/v1/chat/completions
responses	https://api-maas.teleai.com.cn/v1/responses

五、常见报错

现象	原因	解决办法
no available worker matches the requested model	模型名称拼错	核对模型 ID：Xing4.0-29B-A4B 和 TeleChat3-438B-A24B，大小写、数字、点都不能错
npm 不是内部或外部命令（Windows）	Node.js 没装好或没重启终端	重装 Node.js（LTS 版），安装后关掉终端重新打开
claude 不是内部或外部命令	Claude Code 没装好或环境变量没生效	重新执行 npm install -g @anthropic-ai/claude-code；Win 确认注册表写入后新开终端
配了环境变量但不生效（Windows）	写入注册表后在旧终端里不生效	关掉当前终端，重新打开一个新的
401 Unauthorized 或 Authentication failed	API Key错了或过期	回控制台重新确认API Key，重新写入环境变量
OpenCode 启动后看不到模型	配置文件路径不对或 JSON 格式有误	核对路径（见上文对照表）；用 JSON 校验工具检查格式；确认文件名是 opencode.jsonc
两个模型API Key混用报错	两个模型地址和API Key不通用	分别申请，分别配置，不能把 29B 的API Key填到 438B 的配置里

大模型体验中心

开放能力

开发平台

应用产品

解决方案

关于天翼AI

热门搜索

模型接入 Agent 工具指导文档

模型接入 Agent 工具指导文档

准备两样东西

第 1 样：API Key（模型密钥）

第 2 样：Node.js（Claude Code 和 OpenCode 需要）

1、Windows

2、macOS

3、Linux

一、TeleAgent

1. 安装

1.1 下载

1.2 安装

2. 配置

二、Claude Code

1. 安装 Claude Code

2. 配置环境变量

2.1 方式一：用户级 settings.json（推荐，三平台通用，安全 + 便捷 + 持久化）

2.2 方式二：Windows 环境变量（写入注册表，永久生效）

2.3 方式三：macOS / Linux 写入 shell 配置文件（永久生效）

2.4 方式四：临时变量（仅当前窗口生效，快速测试用）

3. 验证配置是否生效

4. 进入项目目录，执行 claude

三、OpenCode

1. 安装 OpenCode

2. 配置

2.1 配置文件在哪

2.2 配置文件怎么创建

2.2.1 Windows

2.2.2 macOS / Linux

2.3 配置内容

3. 模型配置

四、模型信息

五、常见报错