企业官网建设流程全解析

1. 为什么要在 Mac 上折腾 TEN 的 Computer use

TEN 是一个开源的实时对话式 Voice Agent 框架，它把语音识别、大模型推理、语音合成和工具调用串成一条低延迟、可打断的流水线。而 Computer use 是它最近比较受关注的能力：让 Agent 不只是聊天，还能真的去操作你的桌面，比如打开应用、执行命令、读取窗口内容。把这两者拼在一起，就是很多人想要的 Mac Assistant——你对着麦克风说一句话，Mac 上就真的动起来。

这套东西适合谁？我觉得是三类人：一是已经会用命令行、git、docker，想快速跑通一个语音控制桌面 demo 的开发者；二是做过 Python 或 Web 开发，想理解 Voice Agent 工具调用链路的人；三是手里有 Mac，想拿它当实验台，验证「语音指令触发本地操作」这条闭环的人。如果你只是想找个现成的语音助手用，那没必要折腾；但如果你想搞清楚 Agent 怎么从一句话走到一次真实操作，TEN 的 config.toml 骨架和联调流程值得走一遍。

我试过在本地把 TEN Agent 拉起来，再挂上 Computer use 的工具，整个过程最卡人的不是模型，而是配置项散、Key 通道多、启动顺序容易乱。所以这篇不聊大会报名，直接给你一份可复制的 config.toml 骨架，再配一套统一的 Key/API 接入方式，最后用启动和验证动作确认语音指令能触发 Mac 端操作。

2. TaoToken 前置：统一 Key 与 API 通道怎么接

TEN 的默认配置里，LLM、TTS、ASR 往往要分别填不同厂商的 Key，调试阶段光切换就够烦。我的做法是走 TaoToken 的统一通道，把模型调用收敛到一个 API 入口，config.toml 里只维护一份 Key 和 base_url，后面换模型只改 model 字段。

官网入口在这里：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，注册后在控制台生成 API Key。API 基地址用 https://taotoken.net/api ，注意这个地址不带 UTM 参数，直接写进配置即可。

具体操作分三步。第一步，登录后进控制台，找到 API Keys 页面，新建一个 Key，复制出来先存到本地环境变量，别直接硬编码进仓库。第二步，确认你要用的模型名，比如对话模型和 TTS 模型分别是什么，TEN 的 config.toml 里会按模块填。第三步，把 base_url 统一指向 https://taotoken.net/api ，这样 LLM 和 TTS 可以共用同一个通道，减少配置分叉。

提示：Key 建议用环境变量注入，config.toml 里写${TAOTOKEN_API_KEY}这种占位，启动脚本里 export，避免提交到 git。

如果你后面要长期跑编码类或 Agent 类任务，可以顺带看下 Coding Plan 页面，它更适合高频调用场景；只是验证模型通不通，用模型对话页面直接试一句就行。接入文档在 doc 里，遇到字段对不上时优先查它。

3. 可复制的 config.toml 骨架

下面这份骨架是按 Mac Assistant 场景整理的，包含 RTC、LLM、TTS、ASR 和 Computer use 工具段。你把它存成config.toml，放在 TEN Agent 的配置目录下，然后按注释替换 Key 和模型名。

# TEN Agent - Mac Assistant 配置骨架 # 统一走 TaoToken 通道，base_url 不带 UTM [rtc] provider = "agora" app_id = "${AGORA_APP_ID}" app_certificate = "${AGORA_APP_CERTIFICATE}" channel = "mac_assistant" uid = 1001 [llm] provider = "openai_compatible" base_url = "https://taotoken.net/api" api_key = "${TAOTOKEN_API_KEY}" model = "gpt-4o-mini" temperature = 0.3 max_tokens = 1024 [tts] provider = "openai_compatible" base_url = "https://taotoken.net/api" api_key = "${TAOTOKEN_API_KEY}" model = "tts-1" voice = "alloy" sample_rate = 24000 [asr] provider = "default" language = "zh-CN" interrupt_enabled = true [computer_use] enabled = true platform = "macos" allow_apps = ["Finder", "Terminal", "Safari"] allow_shell = true shell_timeout_sec = 15 screenshot_on_action = true [agent] name = "mac-assistant" system_prompt = """ 你是一个运行在 macOS 上的语音助手。 用户用中文下达指令，你可以调用 computer_use 工具执行桌面操作。 执行前先复述你要做的动作，执行后返回结果摘要。 """

几个关键点解释一下。[llm]和[tts]都指向同一个 base_url，Key 也共用，这就是统一通道的好处。[computer_use]里的allow_apps是白名单，先限制在 Finder、Terminal、Safari，避免 Agent 乱开应用；allow_shell打开后它能执行 shell 命令，shell_timeout_sec防止卡死。screenshot_on_action打开后每次操作会截屏，方便你回看它到底干了什么。

注意：allow_shell = true在本地实验可以，但别在存有敏感数据的机器上长期开着。白名单和超时是底线。

4. 启动与验证：确认语音指令触发 Mac 操作

配置写好后，启动分两步：先起 TEN Agent 服务，再起 RTC 通道。假设你已经 clone 了 TEN-Agent 仓库，并且装好了 docker 和 docker compose。

# 1. 注入环境变量 export TAOTOKEN_API_KEY="你的Key" export AGORA_APP_ID="你的AgoraAppId" export AGORA_APP_CERTIFICATE="你的Agora证书" # 2. 启动 TEN Agent docker compose -f docker-compose.yml up -d # 3. 查看日志，确认 LLM 和 TTS 初始化成功 docker compose logs -f ten-agent | grep -E "llm|tts|computer_use"

日志里如果出现llm initialized、tts initialized、computer_use enabled，说明配置被正确读取。接下来打开 TEN Agent 的 Web 控制台，连上mac_assistant这个 channel，允许麦克风权限。

验证动作我建议按三步走，从简单到复杂。第一步，说「你好，介绍一下你自己」，确认语音链路通，TTS 有回音。第二步，说「打开 Finder」，观察 Mac 上 Finder 是否被激活，日志里应该有computer_use action: open_app。第三步，说「在终端里执行 echo hello」，看 Terminal 是否弹出并输出 hello，同时截图记录被保存。

# 验证 shell 动作是否真的执行 docker compose exec ten-agent ls -la /tmp/ten_screenshots/ # 应该能看到按时间戳命名的截图文件

如果第三步成功，说明语音指令已经能触发 Mac 端操作，整条闭环跑通了。这时候你可以回到 config.toml，把allow_apps再加一个你常用的应用，试试自定义 tool 的扩展。

5. 本篇常见错排查

第一个坑是 Key 没生效。表现是日志里 LLM 初始化失败，报 401。原因通常是环境变量没 export 到 docker 容器里，或者 config.toml 里写的是明文 Key 但被 git 忽略规则覆盖了。排查方法：进容器docker compose exec ten-agent env | grep TAOTOKEN，看变量在不在。

第二个坑是 RTC 连不上。表现是 Web 控制台一直转圈，日志里rtc join failed。先确认 Agora 的 app_id 和 certificate 没写反，再确认 channel 名和前端填的一致。Mac 的防火墙有时会拦 UDP，临时关掉试一次。

第三个坑是 Computer use 不执行。表现是语音识别到了，LLM 也回复了，但 Mac 没动静。先看allow_apps白名单里有没有你要操作的应用，再看allow_shell是不是 false。如果日志里出现permission denied，那是 macOS 的辅助功能权限没给，去系统设置里把终端或 docker 的辅助功能权限打开。

第四个坑是 TTS 没声音。检查sample_rate和前端播放器是否匹配，24000 是常见值，但有些浏览器要求 48000。改一下再试。

提示：排障时优先看docker compose logs -f ten-agent的实时输出，比翻历史日志快。接入相关的字段问题，直接查接入文档最准。

6. 把 Key 和通道固定下来，再谈扩展

跑通之后，我建议你做的第一件事不是加功能，而是把 Key 和 API 通道固定成一套可复用的配置模板。因为 Computer use 的调试会反复重启服务，如果每次都要重新填 Key，效率很低。统一走 TaoToken 的 API 通道后，你只需要维护一个环境变量文件，config.toml 里全是占位符，换机器也能直接搬。

如果你接下来要验证更多模型，比如换个对话模型看指令理解准不准，可以直接在模型对话页面先试 prompt，确认效果再写回 config.toml。如果你打算把这个 Mac Assistant 长期挂着跑，或者接进日常编码流程，那 Coding Plan 会更合适，调用额度和稳定性都更省心。API Keys 页面用来管理你的 Key 轮换，接入文档用来查字段，这几个入口配合起来，基本覆盖了从调试到长期运行的需求。

最后留一个我踩过的坑：别在 config.toml 里同时写两套 base_url，一套给 LLM 一套给 TTS，那样切换模型时容易漏改。统一成一个，改 model 字段就够了。